CS 452/652 Winter 2026 - Assignment 0

(Version 1)

Due Date: Mon Jan 19, 9:00am

Introduction

In this assignment you will familiarize yourselves with the basic functionality of the Raspberry Pi, its ARM CPU, and the train controller, while learning techniques for handling asynchronous events by polling. It is recommended that you first write, compile, and execute several simple programs for the Raspberry Pi, and only then start working on the assignment.

Description

Write a program that runs on the Raspberry Pi system. Your program interacts with the user via the serial interface to a virtual terminal while controlling the following independent real-time activities:
  1. a digital clock showing minutes, seconds, and tenths of seconds, which measures time accurately, in the sense that it does not slow down or lose ticks,
  2. a user command interface that can be used to set train speeds and control switch turn-outs, and
  3. a real-time display on the terminal showing the state of the track.
The monitor should use cursor addressing (using appropriate ASCII sequences for terminal control) to display on its screen at least the following:
  1. the current time,
  2. a table of switch positions,
  3. a list of the most recently triggered sensors, and
  4. a prompt at which the user can type commands.
These four components should be organized so that the display is easy to understand.

The user command interface should support, at a minimum, the following commands.

  1. tr <train number> <train speed> – Set any train in motion at the desired speed (0 for stop).

  2. rv <train number> – The train should reverse direction. To reverse direction set the train speed to zero, wait until the train stops, send the reverse direction command, then send a speed command to re-accelerate the train to the same speed in reverse as it was going forward before the command. Do not send the reverse direction command before the train has stopped!

  3. sw <switch number> <switch direction> – Throw the given switch to straight (S) or curved (C). Make sure you can reliably communicate with the track and train hardware before attempting to throw switches.

  4. q – halt the program and return to boot loader (reboot).
Use the Raspberry Pi's built-in system timer (BCM Chapter 10) to implement the clock. Do not use interrupts.

Program Structure

Your program should be written as a polling loop, using the UART0 device to talk to the terminal and CAN bus to talk to the train set. (This is the default configuration and you should always leave it so.) The clock should not lose time.

Possibly Helpful Comments

You can use the headlight on the trains as an easy method for telling if your commands to the trains are successful. Also, the headlights provide an indication of the current travelling direction of a train. You can use the 'wireshark' tool on the PCs to monitor CAN bus traffic via interface can0.

If you are using the various get/put/print functions from the example code for anything except debugging you are probably doing the assignment incorrectly.

It should not be necessary to use the Märklin CS3 manual control box other than maybe the 'stop/go' button.

Submission

Your readable and documented source code should be in your repository at https://git.uwaterloo.ca. The repository must be set to 'Private' with instructor and TAs added as 'Reporter'. Your repository should include a README-A0 file, which briefly describes how to make and operate your program. Make sure that your repository does not contain any unnecessary files that are generated during the build process.

Each student should submit a single PDF file into the A0 dropbox for this course in Learn. The PDF should include the following information:

  1. The commit hash value of the commit that we should be using for this assignment. The commit must be dated before the assignment deadline.
  2. A description of the structure of your program. Aside from testing, we will judge your program primarily on the basis of this description.
  3. Describe which algorithms and data structures you use and why you chose them.
  4. If appplicable, a description of unimplemented aspects of the assignment. Also, if you know of bugs in your implementation describe them explicitly.
  5. Answers to the following questions:
    1. How do you know that your clock does not miss updates or lose time?
    2. How long does the train hardware take to reply to the various commands?
    (Note: To answer these questions, you need to perform and report some timing of your polling loop.)
  6. Make sure (test!) that the following sequence of operations results in a successful build of your program in the linux.student.cs environment. Make it clear in the README file where to find the documentation and image! 
    git clone <your repository>
git checkout <commit hash>
make
  7. The code for sensor timing measurements must be part of your submission, along with any special instructions to build, load, and run - if applicable.

We may perform code reviews with students, in which case a TA and/or instructor will contact you to set up a meeting.

Three examples of highly rated documentation (note different hardware) from previous years: