Class board V0.2

class-board-2026

The teaching instrument for Basic Skills for Experimentalists (TIGP, 2026): one ESP32-S3 board (the ESP32-S3 is the microcontroller we use — a small computer on a chip, with WiFi) with three student-designed sections, a phone web app, and a Python client. The board is a small NMR console: a 2 mT field, a bottle of water, a pulse at 89 kHz, and the free induction decay that comes back turned into a spectrum on your phone.

The three sections of the board (one design, made together in Workshop 2; each student added one section): A — inputs and the NMR receiver (the 8-channel 16-bit converter; the tuned coil, low-noise amplifier, blanking switch, I/Q mixer, IF filters and clock generator) · B — signal generation, timing and the NMR transmitter (±10 V outputs; the DDS synthesizer, reconstruction filter and power stage; TTL buffers, TRIG, the I²C expander) · C — the front panel board (the whole second board: the SMA field, the OLED, the LEDs, the TTL strip, the TX coil terminal and the Qwiic; the two isolated inputs; the module header with its 5 V buffer — seven outputs, MODULE OUT 1–7 plus a reserved spare pin, for driving opto-isolated modules outside the box). The instructor owns the base: the dev-board socket and the buses, the power entry and the rails, the external power input, the H-bridge and the polarizer switch.

Firmware drivers (the firmware calls each driver a block): base (dev board itself) · b1_inputs (ADS8688 8-ch ADC, analog-to-digital converter) · b2_power (rails) · b3_outputs (DAC8563 digital-to-analog converter + ±10 V) · b4_switching (7 module outputs, 2 isolated inputs) · b5_dio_trig (8 TTL out, 2 fast out, TRIG) · nmr (the console: pulse → free induction decay → spectrum). The drivers follow the sections: Section A b1_inputs and the receiver capture; Section B b3_outputs and b5_dio_trig; Section C b4_switching; b2_power is the instructor's. Protocol: firmware/PROTOCOL.md.

Until the class board arrives everything runs in SIM mode on a bare Jinhua ESP32-S3 N16R8 dev board (the development board: the microcontroller on a small board with a USB connector and pins): each driver fakes its hardware, so the app, the chart and the alarms all work from Workshop 1.

How this repository fits the course. Workshop 1: AI for experimentalists is Project 1 (a web app of your choice — a simulator or a game, built with the AI method) and Project 2 (your own phone app that controls the ESP32 over WiFi). The firmware and app in this repository are Step 1 of Project 2: every student flashes them onto their own board first — a known working hardware baseline, which separates hardware problems from software problems — then builds their own app in its own repository, reading this code for the access point, the WebSocket and the LED. They stay the fallback: flash them again if your own build stalls and you have a working app on the phone today. In Workshop 2: Designing printed circuit boards we design the class board together in KiCad — one board for everyone. They are also the base for Project 3 (from Workshop 3: Firmware and basic mechanical design (PCB housing)): your instrument — the firmware and the app that use the class board's capabilities, in a housing you design, presented on a great project website. You choose what instrument it is. The course ends with a project presentation and demonstration, 26–30 Oct.

The student package (everything you need is in this repository — the project folder whose complete history git keeps, stored online on GitHub)

Flash in 5 commands (VS Code + PlatformIO)

Prerequisites: VS Code with the PlatformIO IDE extension (installs its own Python and pio), git, the dev board on a USB-C data cable plugged into the port marked USB (native USB, not UART).

git clone https://github.com/TIGP-Experimental-Methods/class-board-2026.git
cd class-board-2026/firmware
pio run -e esp32s3-sim -t upload        # 1st time: downloads the toolchain
pio run -e esp32s3-sim -t uploadfs      # copies host/pwa/ to the board's LittleFS (its file store)
pio device monitor                      # watch it boot; note the AP name

(In VS Code: PlatformIO sidebar → esp32s3-sim → Upload, then Upload Filesystem Image, then Monitor.) If the upload cannot find a port: hold BOOT, tap RST, release BOOT, retry. Windows needs no driver for native USB. If the upload says "No serial data received" (a factory-fresh board, USB ID 303A:4001): hold BOOT, tap RST, release BOOT — the board comes back as 303A:1001 on a new COM port; pio device list again and flash to that port. Once only; the port also disappears and reappears at every reset, which is normal. All flashing and serial symptoms, and the secrets rule, are on one page: workbook ch. C, §C.2.

Open the app on your phone

1. The board's RGB LED turns blue = it is an access point (its own WiFi network, which your phone joins). Serial monitor prints AP "instrument-XXXX" password "instrument".
2. On the phone join WiFi instrument-XXXX, password instrument.
3. Open http://192.168.4.1 in the browser (type the http://; stay connected when the phone warns about no internet, mobile data off on Android). Tap Red on the Base tab: the LED changes. The chart plots base.counter; pick another key from the dropdown.
4. Add to Home screen gives an app icon. (Full "install" prompts need HTTPS, which the board does not have; the shortcut is enough.)

To use the lab WiFi instead: copy firmware/include/secrets.h.example to secrets.h, fill in SSID/password, and, if you want OTA (the update over WiFi), remove the // before OTA_PASSWORD and type a password of your own (left commented out, OTA stays off) — type the passwords into that file yourself, never into a Claude chat; the file is git-ignored (git check-ignore -v firmware/include/secrets.h prints a line) — and re-flash. For uploads over WiFi, copy firmware/secrets.ini.example to firmware/secrets.ini (git-ignored too), type the board's name and the same OTA password there, and run pio run -d firmware -e esp32s3-ota -t upload. The LED turns green and the board is at http://instrument-XXXX.local (mDNS: the board announces its own name on the local network, so no IP address is needed; XXXX is the same suffix as its access-point name, so several boards can share one network). If joining fails within 10 s it falls back to the AP.

Python client

pip install -e host/            # or: uv pip install -e host/
instrument status
instrument send base led --args '{"r":0,"g":255,"b":0}'
instrument stream base.counter --seconds 5 --csv out.csv
instrument alarms list

It talks to 192.168.4.1 (the board's own access point); on a lab network give --host instrument-XXXX.local (XXXX = the last four hex digits of the MAC, printed in the boot log) or the IP address.

Add a driver (Workshop 3, exercise E11)

1. Copy firmware/src/blocks/template/ → the driver folder of the block your instrument needs, e.g. firmware/src/blocks/b3_outputs/. Rename the class and name() → "b3".
2. Write the SIM branch first: status() returns plausible fake values; handle() accepts your commands. Flash; your tab appears with a generic key/value view.
3. Copy host/pwa/panels/template.js → panels/b3.js, set id: 'b3', replace the example control. Add it to PANELS in app.js. pio run -t uploadfs; reload the phone.
4. Register the driver in firmware/src/main.cpp (one registry.add(&b3) line — the stub drivers are already registered, so you only replace the stub of the driver you are writing).
5. Fill the #ifndef SIM branches with the real driver using the pin constants in firmware/include/pins.h; the chip's protocol, the signal path and the limits are in docs/class-board-reference.md (one subsection per capability, with a minimal snippet).
6. Open a pull request (PR — a request to merge your changes into the shared project; someone reviews it first); CI (continuous integration — the automatic build GitHub runs on every pull request) builds both envs.

The rules: a driver talks only to its own hardware; all driver code runs from loop() (no tasks, no locks); every status key you show in the panel is one your status() emits.

The housing (Workshop 3, Project 3)

hardware/release/ holds the two board models (class-board.stl, front-panel.stl meshes and the STEP files, exported from the final KiCad boards with kicad-cli, keeping the connectors, LEDs and modules) and nothing else: the housing is yours to design, from the housing brief with Claude Code, in docs/students/<name>/housing/, starting by opening each board on its own in OpenSCAD; chapter 3 §A.6 has the steps, and SETUP.md Step 11 installs OpenSCAD and Bambu Studio.

Add an alarm rule

Rules are data: {block, key, op, threshold, action}, evaluated 20× per second on the same status the app sees; they fire once when the condition becomes true.

• On the phone: Alarms tab → pick b1.ai1, gt, 9, action module 1 off → Add rule.
• From a panel: api.addAlarm({ block: 'b2', key: 'v5_raw', op: 'lt', threshold: 4.9, action: 'notify' }) (see panels/template.js).
• From Python: instrument alarms add --block b1 --key ai1 --op gt --threshold 9 --action module:1:off.

action is notify (toast on every phone, browser notification if allowed) or module:<n>:on|off (a module output on the front panel, Section C). Rules persist on the board in /alarms.json.

Layout

firmware/
  platformio.ini            envs esp32s3 (real), esp32s3-sim (-DSIM=1), esp32s3-ota (esp32s3 over WiFi)
  secrets.ini.example       OTA upload template (board name, OTA password)
  include/pins.h            GPIO map of the boards as ordered (docs/class-board-reference.md §3)
  include/secrets.h.example WiFi and OTA password template
  scripts/copy_pwa.py       pre-build: host/pwa -> firmware/data
  src/main.cpp              WiFi, mDNS, OTA, HTTP + WebSocket, 20 Hz broadcast
  src/blocks/Block.h        the 5-method driver interface
  src/blocks/Registry.*     list of drivers
  src/blocks/base/          LED, counter, temperature
  src/blocks/template/      copy-me block
  src/blocks/b1_inputs/ … b5_dio_trig/
  src/alarm/AlarmEngine.*   rules, block "alarms"
  PROTOCOL.md
host/
  pwa/                      index.html app.js style.css sw.js manifest, panels/*.js
  instrument.py, pyproject.toml
hardware/sections/                the main board split four ways BY AREA for routing (A rear right, B front right, C front left, D rear left); README.md there
hardware/scripts/main_sections.py  areas / split / check / merge / report for the main-board areas
hardware/front-panel/sections/    the front panel split four ways for routing (A analog, B digital, C modules, D isolated + power); README.md there
hardware/scripts/panel_sections.py  split / check / merge the four sections back into one board
docs/
  references.md             papers (NMR at low field), datasheets of every part, tools and suppliers
  class-board-reference.md  THE BOARD, PIN BY PIN: connectors, links, every chip's protocol, levels, limits, firmware state, known defects (netlist-derived, 2026-10-08)
  references/               the two Creative-Commons papers as PDF
.github/workflows/build.yml  both envs + ruff on every push/PR