Real-time Lab Administration Guide

The Real-time Lab is used by students taking courses in CS 452/652 where students design and implement a real-time multi-tasking operating system using the tools and techniques of real-time programming for embedded systems. Implementation uses cross-compilation for an ARM-based system-on-chip. The operating system then supports an application program involving process control, data acquisition, and communication.

This page serves as an administration guide for CSCF staff supporting the course (although others may find it useful).

Note: This page is currently under construction. Information may be missing, or may require clarification.

Glossary

Physical Lab Space

The Real-time Lab is located in MC3018 and is restricted to students enrolled in CS 452/652. The lab is locked at all times with a keyfob scanner on the door for staff access, and a mechanical keypad on the door for student access. The code for the keypad changes every term after Assignment 0 (A0) and is given out during the lecture. Students are not to share the code with anyone else.

Outer Room

The outer room for MC3018 features a standard linux nettop lab for software development.

There are also PCs present with Raspberry Pi controllers connected. The purpose of these PCs is to allow students to test and debug their code without taking up an entire train track.

(Note: Add the exact amount of nettop and debugging stations) -- Devon Merner - 2023-09-29

Inner Room (MC3018a)

The inner room for MC3018 features two train tracks with associated Raspberry Pi controllers and PCs. There are two empty tables for future expansion (for a total of four potential train tracks).

The inner room is generally noisier due to the nature of the trains. The doors leading to the room can be closed if noise becomes an issue.

Hardware

(Note: A diagram of our standard hardware setup would be useful here) -- Devon Merner - 2023-09-29

Raspberry Pis

The Raspberry Pi is used by students to run and test their code. The Raspberry Pi loads the student's code over TFTP and communicates with the track controller and console PC via RS-232.

The Raspberry Pi 4 with a BCM2711 processor is currently used in the lab. Any RAM option should work, although 4GB models are generally preferred (if available) in case a full OS is required for testing.

Older model Raspberry Pis will not work due to their limited UARTs.

Bring-up

A brand new Raspberry Pi cannot boot over TFTP without changing the EEPROM settings. This is done by temporarily booting the Raspberry Pi from an SD card with Raspbian and running sudo rpi-eeprom-config --edit. The EEPROM settings should be configured to the following:

[all]
BOOT_UART=1
BOOT_ORDER=0xf241
TFTP_PREFIX=2
USB_MSD_DISCOVER_TIMEOUT=5000

Reasoning:

• BOOT_UART=1 will enable bootloader output over UART0.
• BOOT_ORDER=0xf241 will set the default boot order to the following (read from right to left):
  1. SD card (0x1)
  2. USB (0x4)
  3. Network/TFTP (0x2)
  4. Reboot (0xf)
• TFTP_PREFIX=2 will make the Raspberry Pi look for a MAC address-specific folder on the root of the TFTP server before falling back to normally TFTP booting from the root of the TFTP server.
  • This feature is used to have each Raspberry Pi load a different image without having to run a TFTP service with unique TFTP root directories (such as dnsmasq)
• USB_MSD_DISCOVER_TIMEOUT=5000 will set the USB boot timeout to 5 seconds (default is 20 seconds).

The Raspberry Pi will have to be fully rebooted to apply the changes.

In order to boot the Raspberry Pi over the network, it needs to know the IP address of the TFTP server. This can be done on the University network by adding the Raspberry Pi to the lab network and then setting DHCP option 66 to 129.97.167.60 via IPAM. Alternatively, you can hardcode the TFTP server's IP address in the EEPROM config by using the TFTP_IP=x.x.x.x option. This can be useful when working off-campus, or if you don't want to worry about editing the DHCP settings for the Raspberry Pi.

Serial Hat

We currently use a custom designed and built serial Raspberry Pi hat rather than one off the shelf. This is due to modern Raspberry Pi serial hats not supporting dual channels with hardware flow control (for CTS).

The git repo for this custom serial hat can be found at https://git.uwaterloo.ca/dmerner/Engineer-Hat . The project files for the PCB can be opened and edited using the latest version of KiCad.

The serial hat adds two separate RS-232 channels to the Raspberry Pi. These channels are electrically isolated from the Raspberry Pi's GPIO and from each-other. Each channel uses a separate MAX232 serial driver/receive with support for RTS and CTS signals.

+5V power for the Raspberry Pi is backfed from the hat. This is to provide a solid power toggle without the use of an external in-line power dongle.

Bring-up

Ordering new serial hat PCBs can be done by submitting the included gerbers to JLCPCB. The serial hat is a 4-layer PCB sized 105x200mm. No extra options should be required.

The .STEP files for a compatible case is provided in the git repo. The current cases in the lab were printed in PETG using a Prusa i3 MK3S. Heat-set brass threaded inserts are required to assemble the case.

Trains and Tracks

We currently use Marklin locomotives and tracks.

A Marklin 6021 control unit is used to control the trains. A Marklin 6050/6051 Interface Unit is used to control the 6021 control unit via RS-232.

Track A

Preparing a New Train

Replacing a Solenoid

Maintenance

Trains require lubrication at set intervals.

• New grease should be applied to the propulsion unit gear assembly every 20 hours of use (using Marklin 66626 or equivalent PTFE grease).
• Machine oil should be applied to the train axles every 30 hours (using Marklin 7149 oil or equivalent).

Only synthetic lubricants should be used. Do NOT use petroleum or oil-based lubricants!

If dirty, the wheels of a train can be cleaned with 99% Isopropyl alcohol and a microfibre cloth. The wheels should also be inspected for any missing or damaged tires. Missing or damaged tires can be replaced with new ones from the parts bin (using Marklin part 7153).

The electric pickup shoe of a train should be inspected and cleaned with 99% Isopropyl alcohol. A pickup shoe should be replaced if damaged or heavily worn. Pickup shoes with a groove worn into them may not trigger the sensors on the track reliably.

The train tracks should be cleaned after periods of heavy use, and after periods of no use. This can be done with 99% Isopropyl alcohol and a microfibre cloth. Be careful not to damage the sensors or turnout mechanisms.

Troubleshooting

Trains on the track can be controlled by pressing the "L" button on the control unit and entering in the number of the train. If a train has a single digit number, then enter a 0 before the actual number (e.g train 2 can be controlled by pressing L->0->2). The direction of a train can be switched by setting the control unit's power knob to zero and then turning it slightly further to activate the direction toggle. The direction should be indicated with an arrow on the control unit's display. Press the green "go" button to activate power to the track.

Remember to turn off power to the track by pressing the red "stop" button before performing any maintenance or adding/removing any train to the track.

Sensors and turnouts/solenoids can not be controlled manually using the 6021 control unit. Testing them will require a working program to be loaded onto the Raspberry Pi.

Nettops

The nettops in this lab are the same as the nettops in our other public labs and run the same software/image. See NettopAdministrationGuide for more details.

Software

Boot Server

cs452.student.cs.uwaterloo.ca is the bootserver used in the Real-time Lab. It runs tftpd-hpa for serving TFTP files, and Apache with Mellon ADFS and a custom webapp to allow students to upload their code. Using a webapp with ADFS support allows us to control student access without having to rely on DFSc home directories or any other integration with LDAP. PostreSQL is used as a database for the webapp.

The TFTP root for the server is located at /var/www/dispatch/storage/app/tftp. MAC address-specific folders for the Raspberry Pis are automatically generated from /var/www/dispatch/storage/app/tftp/skeleton when an image is uploaded to a specific Raspberry Pi.