TA guide

In every lab

Lab 1: First boot

Before the section: write the term's image on the spare station's boot media and check its SHA-256 against the recorded value; boot it with the console wired and capturing from power-on; log in over serial and over SSH from a bench PC, and install the staged course tools as students will. Check that each pair's phone, or the bench PC's imager, can write boot media.

• Checksum does not match: the image file or the write is bad. Check the SHA-256 of the image file on the bench PC first: if it is wrong, fetch the image again from libre.computer downloads on a campus-connected machine and replace the bench PC's copy; if it is right, write the media again and recompute.
• Board stops before the login prompt: swap in the station's spare boot media, which was written before the term.

Lab 2: Board anatomy and power rails

Before the section: find each rail's test point on the schematic and in the layout viewer (Das Frite, Solitude), mark them on a sheet for each station, and measure every rail on the spare station so you know the readings students should get; check that each station's USB power meter reads, at idle and under load; have the supplied power-up traces ready for every bench, and if the bench has an oscilloscope, show a live power-up as well.

• A rail reads zero or far off: the probe is on the wrong point or the board is not powered. Check against your own readings.
• A probe slipped and the board reset or stopped: power off, check the board on the spare station's boot media, and swap it if it does not boot.
• Current chart axis does not start at zero: ask for it to be redrawn; it is part of the hand-in.

Lab 3: Boot ROM and the SRAM stage

Before the section: on the spare station, flip the boot select switch and watch the boot order change, then put it back; hold the USB boot button at power-on and start the board over USB from a phone and from a bench PC; on each bench PC, build the first stage with libretech-builder-simple and start the board over USB with it.

• The board does not enter USB boot mode: the USB boot button was released before power was applied. Unplug, hold the button, and apply power.
• The board boots from an unexpected source in a later lab: the boot select switch was left in its changed position. Put it back.
• The student's build does not start: start the published first stage over USB first to separate the USB path from the build, then rebuild.

Lab 4: Memory and the bootloader

Before the section: on the spare station, build the first stage with a changed memory clock, start the board over USB with it and run sudo memtester 128M 1 in Linux; interrupt the boot at the U-Boot prompt and boot the kernel by hand with load and booti, with bootargs set from /proc/cmdline.

• The board stops after the memory change: the change failed the bring-up. Nothing was written to the board: power-cycle it and it boots from its own firmware.
• The kernel starts, then cannot mount its root filesystem: bootargs was not set (set it from the line /proc/cmdline shows on the normal boot), or the root is named by UUID= or LABEL= and the initramfs was not loaded and passed to booti as <address>:${filesize} (a raw initramfs needs its size; U-Boot's "Wrong Ramdisk Image Format" means the size is missing).
• The kernel or device tree is corrupted after loading: the two were loaded at overlapping addresses. Choose addresses further apart, using the memory map.

Lab 5: UEFI and Linux boot

Before the section: write the stock generic distribution the section will use to a second boot media, boot it on the spare station through the bootloader in SPI flash, and run efibootmgr -v and systemd-analyze on it; change a boot argument in its boot-loader entry and reboot, so you can show students how.

• A changed boot argument stops the boot: at the boot menu, edit the entry for one boot and remove the change, boot, then undo it in the boot-loader entry under /boot (GRUB's configuration or loader/entries, not the EFI system partition), or write the stock image to the spare again; the student then carries on from the systemd-analyze step. The first boot media was not changed.
• The service does not start at boot: check that the unit is enabled, and read its log with journalctl.

Lab 6: Device tree and GPIO

Before the section: on the spare station, apply a ready-made overlay with the wiring tool; write and apply an overlay for the DS3231 and check that a second /dev/rtc appears, then revert it; blink an LED with libgpiod with the logic analyser on its pin; build the motor circuit and switch it from a GPIO pin, and check that the motor's start does not reset the board.

• No second /dev/rtc: read the driver's probe in dmesg. A wrong compatible string, the I2C bus not enabled, or status off are the usual causes. A probe deferred for a clock, regulator or GPIO is retried later.
• The LED does not light: wrong libgpiod line, or the LED reversed. Check the line in the GPIO pinout.
• An LED lit with no series resistor: unplug the board at once and fit the 680 Ω resistor; the pin is being overdriven and its pad can be damaged.
• The flyback diode is backwards: the stripe goes to 5 V. Backwards, it shorts the supply the moment the MOSFET turns on. Check every pair's diode before they power on.
• The motor does not turn, or the board resets: a MOSFET that is not logic level stays half off at 3.3 V; a motor that draws too much needs its own supply, with grounds joined.
• No difference between idle and load histograms: the load was not running while measuring.

Lab 7: I2C and SPI

Before the section: on the spare station, enable the I2C and SPI buses with the wiring tool's overlays, find the DS3231 and the SSD1306 with i2cdetect, and read a channel of the MCP3008 through spidev. Make sure the lab 6 DS3231 overlay is reverted, so the clock is free to read by hand.

• i2cdetect finds nothing: the bus's overlay is not applied, the part has no 3.3 V or ground, or the two wires are swapped. Check on the logic analyser.
• The DS3231 is reported busy: the kernel's driver from lab 6 still holds it. Revert that overlay.
• ADC values are wrong or constant: wrong SPI mode, wrong bytes, or an SPI clock above the part's limit at 3.3 V (keep max_speed_hz at or below about 1 MHz). Compare the capture with the datasheet's timing diagram.
• A part was powered from 5 V: unplug the board at once, rewire to 3.3 V, and check the board still boots.

Lab 8: UART and a driver

Before the section: on the spare station, enable a header UART (on Das Frite, the second UART that the S805X guide enables, because the console is on pins 3 and 5) and exchange messages with a bench PC at two baud rates; bind the kernel's MCP3008 driver with an overlay (with reg, spi-max-frequency at or below 1 MHz and a 3.3 V vref-supply) and read a channel through /sys; build and load a minimal module to check that the image's kernel headers match.

• The module will not build: the kernel headers do not match the image the board runs. Install the matching headers from the packages staged on the bench PC before the term.
• No characters at all on the UART: the lines are not crossed, or the UART's overlay is not applied.
• The board stops answering after the adapter moves off the console: move the adapter back to the console and read what it says.

Lab 9: Project build and recovery

Before the section: on the spare station, break the boot configuration on spare boot media, boot it and read where it stops, then start the board over USB from a phone and from a bench PC, and restore the media both with the app and with the desktop imager. Check each pair's recovery path before they break anything.

• A pair broke their only working boot media: restore it from the station's spare, then recover the broken one as the exercise.
• The board will not come back over USB: follow when a board will not boot on lab setup: restore the boot firmware in SPI flash over USB, or swap the board.

Lab 10: Project demo

Before the section: have a spare station, a spare power supply and spare boot media at hand, so a hardware fault in the demo costs a swap, not the demo.