Workshop 3 — Firmware and basic mechanical design (PCB housing)

The slides: Workshop 3: getting things made. Nobody learns a CAD program (computer-aided design: the program a part is drawn in) today: Claude Code writes the geometry; you specify, look, check the numbers, slice and decide.

Setup check — your laptop with VS Code and Claude Code, OpenSCAD and Bambu Studio installed and opened once, the class repository up to date, your dev board and a USB-C data cable.
Getting things made: the fabrication menu — two ways to a part: make it here (FDM printing on the Bambu P1S, the laser cutter, hand tools) or order it (CNC machining, sheet metal, resin and metal printing, EDM); typical times, costs and tolerances.
Tips to make 3D prints and cut parts turn out right — layer direction and the 45° rule, walls and tolerances, nuts in pockets, materials, the slicer, the laser.
From an idea to a file — design the way it will be made; the files (STEP, STL/3MF, DXF); the five CAD programs compared; reading OpenSCAD (a part as a short program of shapes, moves and combinations); the AI design loop: specify, generate, look, measure, slice, test.
The housing — we build it together in OpenSCAD with Claude Code, in eight steps: specify · answer Claude's questions · generate · look · check the numbers · fix and make it yours · export and slice · the test coupon and your files.
Pulling the course together — Project 3 is your instrument: the firmware and the app that use the class board, in your housing; your first firmware driver and app panel in sim mode; a great project website that shows what the app does, how to use it and what it can do (one repository, one website, one card); the presentation; the option of a video the AI renders for you.
This was the last workshop — from here, build.

Hard cutoff: Friday 9 October, 2 pm. The final housing files for 3D printing / laser cutting must be in for manufacturing then.

Prerequisite: OpenSCAD 2021.01 and Bambu Studio installed and opened once (setup step 11). Bring your laptop and your dev board.

Detailed plan (follows the workshop outline above)

The boards are on order (placed 28 September, back around 16 October), so everything on the firmware side runs in sim mode on the dev board (a build in which the firmware — the program on the microcontroller — fakes its hardware, so the app works on the bare board). You start your instrument's firmware with a driver and its app panel, wire one alarm rule, and design the housing.

Firmware and app — a driver and its panel

The block-driver interface

Every driver is a folder firmware/src/blocks/<section>_<name>/ implementing name() / begin() / loop() / handle(cmd, reply) / status(out). You start from blocks/template/.

The protocol

WebSocket (a live two-way connection between the phone page and the board) messages {block, cmd, args} in and {block, status} out; one panel module per driver in host/pwa/panels/<section>.js; instrument.py (a Python program on your PC) mirrors the same commands in Python.

Sim mode

The SIM flag fakes the hardware so the whole app runs on a bare dev board — you work ahead of the boards and swap the flag off when they arrive.

One alarm rule per panel

A driver's status → the base alarm engine → a module output + notification: A "AI1 above a threshold" or "no free induction decay seen" · B "output clipped" or "TRIG edge seen" · C "opto count jumped" or "a module output left on".

E11: driver + panel in sim. Choose the part of the board your instrument needs first — the section you worked on in Workshop 2 is a natural start, not an obligation. /tutor L3: copy the template to blocks/<section>_<name>/; fill in the section's commands (A read_all, set_range, capture · B set_dc, sine, pulse, dio · C module, module_all, opto_reset); make the SIM branch return plausible values; add the panel and one alarm rule; flash (write the firmware onto the board over USB); see the panel react on the phone; open the pull request (a request to merge your changes into the shared project; someone reviews it first). The tutor generates the skeleton; you name the commands, write the SIM values, and explain one message round-trip before flashing. Sections that talk to each other are paired (B ↔ A for a waveform measured on an input, B ↔ C for a pulse that switches a module output). Done when the panel controls the section in sim and the pull request is open.

Housing — part of Project 3

Tips for printed and cut parts

Nuts in pockets are the fastening: an M3 nut slides into a 5.8 mm hexagonal pocket, 2.5 mm deep, and the screw pulls it tight. Walls 2 mm; holes +0.3 mm (printed holes come out small); layers are the weak direction, so let the load run along them; 45° is the steepest overhang that prints without support. Print a test coupon first: it answers the fit for your printer. The PCB front panel is the face of the instrument, so the front cover is a plate with holes where the panel's parts are.

Your own design

You write the specification yourself, from the housing brief: what the housing must hold, the printing rules, the files to hand in, and the two board models. Those models, hardware/release/class-board.stl and front-panel.stl (STEP versions beside them), were exported from the final KiCad boards with kicad-cli, keeping only the connectors, LEDs and modules, so every dimension comes from the boards and none from a ruler. Ask Claude to ask you its questions before it writes code. Start by opening each board on its own in OpenSCAD, one import() line at a time, and looking at it; there is no example housing to copy, because the design is yours.

Output

housing.scad, base.stl, cover.stl, coupon.stl (STL: the 3D-print file), cover.dxf (DXF: the laser-cutting drawing) and a screenshot, in docs/students/<name>/housing/, by the cutoff. The institute prints and cuts them.

E12: your housing. On the shared screen, and in your own Claude Code session with OpenSCAD beside it: write your specification from the brief, answer Claude's questions, let it write housing.scad, look at it and check the numbers in the console, fix it and make it yours, export the parts and slice them in Bambu Studio, add the test coupon, commit from Source Control. A design in another CAD program you already use is welcome too, if it fits the boards and meets the deadline. Done when the files are in your folder.

From here — this was the last workshop: E11–E12

The housing files by Friday 9 October, 2 pm; the driver + panel pull request; then your instrument: its firmware, its app and its project website; around 16 October, collect the boards and housings and assemble; 26–30 October, present. Improve your apps, build and have fun. Help: the tutor, then e-mail s.p.bennetts@g.iams.sinica.edu.tw.

E11 Driver + panel pull request. Finish the commands, one status value plotted, one alarm rule wired to the base alarm engine (a threshold on the driver's status → a module output → notification), CI green (continuous integration: the automatic build GitHub runs on every pull request passes); reviewed by a classmate.
E12 Housing files to docs/students/<name>/housing/ — by Friday 9 October, 2 pm.
Build your instrument: its firmware, its app and a great project website (what the app does, how to use it, examples, demonstrations, videos or animations); read workbook ch. 3.

Presentation and demonstration

~Friday 16 October: collect the manufactured PCBs and housings.
Assemble your ESP32, PCB and housing. Flash your own build without SIM, open your app, see your instrument move real hardware (for example A a voltage on AI1 and the receiver's I and Q · B a sine on AO1 into AI1, a TTL line and TRIG direction · C a module output switching, an opto count and a line on the OLED).
Test and refine your firmware and app.
26–30 October: present and demonstrate your project, app, website and video — about 15 minutes each. For example, make a video to describe your app and your instrument.
Project websites and the wall: each project has its own public repository and project website (GitHub Pages). Project 3 — your instrument: firmware, app and housing — is one repository and one website, and the website deserves care: what the app does, how to use it, what it can do, examples for the user and demonstrations of its capability — screenshots, what was measured, videos or animations, a great interface — with links to your pull requests in class-board-2026 and to the class repository (your repository may hold the housing CAD export, photos and the video); it is one card on the wall. All of them are on the class project wall.

The demonstration is yours to shape: your instrument, your app and your website at work, in the order that shows them best; ask the tutor if you want help planning it.

Materials

Slides: Workshop 3: getting things made (PDF). Video recordings are not online.
Workbook on GitHub: ch. 3 — Workshop 3 · ch. 4 — presentation and demonstration · ch. B How the software works (self-study).
In the class repository: PROTOCOL.md · blocks/template (with the SIM branch and the alarm-engine hook) · panels/template.js · the housing brief · the example specification · hardware/release (the reference housing.scad and the board meshes) · the cheat sheet in workbook ch. C §C.6.
The tutor: /tutor L3 and /tutor HW3 in the class repository.
See also the resources for getting things made.