# Uncle Magic's Liquid Turntable

*(Repository name: `LiquidTurntable`. Default network name: `liquidturntable`.)*

BPM-synced motorized turntable controller: an ESP32-S3-ETH drives a NEMA17 stepper through a TMC2209,
takes tempo from OSC (with local tap-tempo fallback), and drives an SK9822 (APA102-type) LED ring itself with an
in-firmware LED engine. Successor to the Arduino Mega 2560-based
[MegaMagicTurntable](https://github.com/scoobiekw/MegaMagicTurntable), with the same motor behavior plus
onboard Ethernet, dual-core headroom and a web config UI.

This is the short reference for the current design. The full discussion, with the reasoning behind each
choice, is in [README_DETAILED.md](README_DETAILED.md); how the design got here is in [CHANGELOG.md](CHANGELOG.md).
The KiCad schematic is the authority for the mainboard's electrical design.

## Documents

- **[Documentation index](../index.html)**: every document in one dark-themed page (HTML first, then Markdown, PDF, CSV, SVG, DXF and STL files), with a filter box.
- **[User Guide](../USER_GUIDE.html)**: running it (panel, tempo, lighting, web pages, OSC, network, safety, troubleshooting).
- **[Hardware Overview](../HARDWARE_OVERVIEW.html)**: how it is built (boards, power, signals, connectors, ring, motor, manufacturing).
- **[FAQ](../FAQ.html)**: the things that catch people out (phone browsers and Android's permissions, Art-Net, saving, tempo), with short answers.
- **[Breadboard Guide](../BREADBOARD_GUIDE.html)**: a picture-by-picture beginner guide to prototyping the whole controller on three breadboards before the PCB is made.
- **[README_DETAILED.md](README_DETAILED.md)**: the long design reference. **[CHANGELOG.md](CHANGELOG.md)**: history.

The `.html` files are self-contained and open in any browser. GitHub shows them as source, so there use the
Markdown versions ([User Guide](../USER_GUIDE.html), [Hardware Overview](../HARDWARE_OVERVIEW.html), [FAQ](../FAQ.html)). The Markdown is
the editable source: edit it, then run `python docs/build_docs.py` to rebuild the HTML. Every push to `main` that
changes `docs/` publishes it to the web server over SFTP (`.github/workflows/publish-docs.yml` running
`tools/publish_docs.py --ci`: the files the push changed and any the server lacks or has at another size; nothing is
deleted). It uses the repository secret `PUBLISH_TOKEN` (renew it monthly on GitHub) and the variables `PUBLISH_HOST`,
`PUBLISH_USER` and `PUBLISH_REMOTE`; the server's host keys are pinned in `tools/publish_known_hosts`. From a PC,
`python docs/build_docs.py --publish` (or `tools/publish_docs.py`, `--dry-run` to only list) does the same with the
settings in the git-ignored `tools/publish.local.json` (template `tools/publish.example.json`; needs `pip install paramiko`).

Copyright © 2026 Steve Kennedy-Williams. Released under the [MIT License](https://github.com/scoobiekw/LiquidTurntable/blob/main/LICENSE); the unit's About page
(`/about`) shows it too.

## Contents

- [Hardware](#hardware) (including [Test points](#test-points))
- [Firmware pinout](#firmware-pinout)
- [OSC API](#osc-api)
- [Web config API](#web-config-api)
- [Design notes](#design-notes)
- [Building / flashing](#building--flashing) (including [First boot](#first-boot))
- [Testing](#testing)
- [Board notes](#board-notes)
- [Heat and ventilation](#heat-and-ventilation)
- [Open items](#open-items)
- [Repo layout](#repo-layout)

## Hardware

Three physical pieces:

- **Main board**: one 100 x 100 mm PCB carrying the ESP32-S3-ETH (Waveshare, W5500 Ethernet) and a BigTreeTech
  TMC2209 module. **One chip does everything**, including the LEDs. Everything runs from 3.3 V. Two level shifters, `U3` and `U5` (74AHCT1G125),
  lift the ring's data (GPIO18) and clock (GPIO2) to 5 V; `R26`/`R62` (10k to GND) keep their inputs low while the
  ESP32 boots. Encoders and buttons wire to the board's headers directly (no separate panel PCB).
- **LED ring**: 178 SK9822-A (APA102-type: data + clock, 27 kHz PWM, so it films without flicker) in an offset/brick
  matrix on a 203 x 203 mm two-layer board (54 mA per LED at full white at the full current field; the firmware holds each LED to 36.6 mA and the
  whole ring to 4.5 A), in [`kicad_led_ring_offset/`](https://github.com/scoobiekw/LiquidTurntable/tree/main/kicad_led_ring_offset) with a `jlc_export/` folder ready to order.
  Two cables join it to the mainboard: **power** on its `J1` (JST VH 4-pin, side entry, B4PS-VH,
  [C157996](https://www.lcsc.com/product-detail/C157996.html)), pin for pin with the mainboard's `J5`, and **signal** on its
  `J2` (JST XH 5-pin: DATA, GND, CLK, GND, NTC) to the mainboard's `J-LED-SIG`, straight through. A 10k NTC on the ring (`TH1`, just inside the inner LEDs) reports its temperature. It mounts near the top of
  the case and does not spin with the platter. Clamp both cables to the tray or lid near the ring, with slack before the plugs, so they never load the board edge.
- **NEMA17 stepper**, direct-coupled through a flexible shaft coupler, no gearbox.

The mainboard schematic is [`kicad_mainboard/Mainboard.kicad_sch`](https://github.com/scoobiekw/LiquidTurntable/blob/main/kicad_mainboard/Mainboard.kicad_sch) (PDF:
`Mainboard_schematic.pdf`), a one-page index with one sheet per function:

| Sheet | File | Contents |
|---|---|---|
| Power | `power.kicad_sch` | `J-PWR-5V`, `J-PWR-12V`, `F1`, `D1`, TVS, bulk caps, `Q5` (no 3.3 V regulator: the module makes `+3V3`) |
| Controller | `controller.kicad_sch` | ESP32-S3-ETH sockets (`J1-H1`/`J1-H2`; `VSYS` fed from `+5V_LED_LOGIC`, `+3V3` out of the module), boot-strap pull-up `R23` |
| Motor | `motor.kicad_sch` | TMC2209 sockets, UART resistor `R9`, motor connector |
| LED | `led.kicad_sch` | Ring data/clock buffers `U3`/`U5`, `D33` buffer supply, ring connectors `J-LED-SIG` (signal and ring NTC) and `J5` (power), the NTC input `R65`/`R66`/`C16`/`D34`, fan header `J-FAN` with PWM inverter `Q6` |
| Panel IO | `panel_io.kicad_sch` | TCA9555 `U1`, I2C pull-ups, encoder and tap-button headers |
| Test points | `testpoints.kicad_sch` | `TP1` to `TP13`, probe pads on the rails and a few signals (see [Test points](#test-points)) |

`GND` and `+3V3` use power symbols at every pin; `+12V_MOTOR` and `+5V_LED_RING` use symbols from
`Mainboard_power.kicad_sym`. Global labels carry signals between sheets and mark the ESP32 GPIO on each header pin.

### Power rails

Two rails come in from outside (a single Mean Well RD-85A 5 V / 12 V supply, or separate 12 V and 5 V supplies,
on `J-PWR-5V` and `J-PWR-12V`). `+3V3` is made on the board. The 12 V rail has a fuse (`F1`); the 5 V rail has a 7.5 A blade fuse in the harness at the supply (see the Hardware Overview, section 3).

| Rail | Feeds | Protection |
|---|---|---|
| `+12V_MOTOR` | TMC2209 VM, NEMA17, fan header `J-FAN` (~0.1 A) | `F1` 2 A resettable fuse, `D1` Schottky (SS34), `C8` + `C11` 2 x 100 µF/35 V at the TMC2209, `D5` SMBJ15A TVS, `R27` 4.7 kΩ bleeder |
| `+5V_LED` | LED ring only (`+5V_LED_RING`, about 6.5 A at full white) | `Q5` reverse-polarity FET, `D32` SMBJ5.0A TVS; a 7.5 A blade fuse in the harness at the supply (the supply's own overload protection is on total power, not a 5 V current limit; the LED engine's 4.5 A limiter is what holds the ring in range) |
| `+3V3` | ESP32-S3-ETH, TMC2209 VIO, TCA9555, encoder pull-ups | made by the module's own JW5060 buck (3 A) from `VSYS`; `D4` is ESD protection only |

The two LED buffers and the module's `VSYS` pin run from `+5V_LED_LOGIC`, fed from `+5V_LED_PSU` (straight from the input) through `D33` (about 4.7-4.8 V; the 74AHCT works from 4.5 V, the module's buck from 4 V).
**The SK9822's supply limit is 5.3 V:** keep the 5 V supply at 5.1 V.

Reverse polarity is stopped by the keyed Mini-Fit input connector, by `D1` on the 12 V rail, by `Q5` on the 5 V ring line and by `D33` on the logic feed.

**3.3 V source: the ESP32-S3-ETH module's own regulator.**
- On the module, `VSYS` feeds a JoulWatt JW5060 buck (4-18 V in, 3 A); its enable (`3V3_EN`) is pulled up to `VSYS` by the module's `R67`.
  The board feeds `VSYS` (`J1-H1` pin 2) from `+5V_LED_LOGIC` and leaves `3V3_EN` (pin 4) open, and takes `+3V3` from the module's `3V3` pin (pin 5) for everything else.
- USB VBUS reaches `VSYS` through the module's 1N4148, so our 5 V never reaches a USB host, and the module's USB-C can power the logic on its own (see [Powering the board while flashing](#powering-the-board-while-flashing)).
- Typical draw is about 400-500 mA; Wi-Fi transmit peaks add a few hundred mA. Main-board Wi-Fi transmit power is capped at 15 dBm.
- **The logic now needs the 5 V supply** (or USB). With 12 V on and 5 V off, the TMC2209 has VM but no VIO; its datasheet holds the logic in reset with the bridges off below the VIO threshold. Check it on the bench.

**Encoder supply.** All 7 encoder headers feed the KY-040 pull-ups from `+3V3`, never 5 V, because CLK/DT/SW go straight
to 3.3 V-only inputs (ESP32-S3 GPIOs and the TCA9555).

**Panel ESD protection.** Each of the 21 panel signal lines (CLK and DT of the 7 encoders, SW of the 6 encoders that have one, plus `TAP_BTN`) has a 1 kΩ series resistor and a
PESD3V3S1UL TVS to GND on the connector side. Each encoder header's `+3V3` pin has a 100 Ω series resistor so a shorted panel wire
can't pull the rail down. Connector-side nets carry a `_J` suffix (`ENC_CLK_J`).

### Mains input and power-on

- **Supply:** one **Mean Well RD-85A** (5 V 8 A / 12 V 4 A, 88 W, usable 10 A and 5 A within 88 W) behind a fused, switched IEC inlet.
  Do not buy the RD-85B (24 V). Wiring and the 5 V trim are in [HARDWARE_OVERVIEW.md](../HARDWARE_OVERVIEW.html#the-supply-mean-well-rd-85a).
  Separate LRS-75-5 and LRS-35-12 supplies also work and give the ring more current.
- **Inlet fuse and switch:** slow-blow (T-type), about T3.15 A at 120 V or T2 A at 230 V (RD-85A cold-start inrush is 50 A at 230 V). Switch rated 10 A or more.
  If it still nuisance-trips, add an NTC inrush limiter in the live line after the switch.
- **12 V rail:** use a regulated 12 V supply; if adjustable, keep it between 12 and 13 V. `D5` clamps at about 24.4 V, below the TMC2209 (29 V) and `C8`/`C11` (35 V).
- **Never plug or unplug `J-PWR-5V`, `J-PWR-12V`, the motor (`J3`), the ring cables (`J5`, `J-LED-SIG`) or a plug-in module with power on.** An unplugged-live motor
  makes a spike that can destroy the TMC2209, and the ring cable carries up to about 7 A.
- **Rail order:** `+3V3` comes from the 5 V rail (through `D33` and the module's buck). `R23` keeps the TMC2209 disabled through boot. The 12 V rail can arrive at any time; with no 5 V the TMC2209's logic has no VIO and stays in reset.
- **Ring at power-on:** `R26` and `R62` hold data and clock low while the ESP32 boots, so the ring keeps whatever it shows at power-on (SK9822s power up dark).
- **Quick off-on:** `R27` bleeds the 12 V caps (rail under about 1 V in about 2.5 s). Wait about 3 s before switching back on.
- **Safety:** bond earth to any metal case or PSU chassis, sleeve all mains terminals, keep mains creepage away from the low-voltage board. If Ethernet is flaky, suspect supply common-mode noise first.

### Connectors (Main Board)

| Ref | Part | Pins |
|---|---|---|
| `J1-H1` / `J1-H2` | ESP32-S3-ETH socket, real `H1`/`H2` rows (1x20 each) | 17 of 20 and 12 of 20 wired: GND, +3V3, LED data/clock, TMC UART RX/TX, ENABLE, DIR, STEP, encoder pins, I2C, tap button; see [Firmware pinout](#firmware-pinout) |
| `J2-MODE` / `J2-MOTOR` | TMC2209 two-row socket (1x08 each) | `J2-MODE`: EN to ENABLE, MS1/MS2/CLK to GND, PDN (both pins) to TMC_UART_RX, STEP, DIR. `J2-MOTOR`: VM to +12V_MOTOR, GND x2, coils A2/A1/B1/B2, VIO to +3V3 |
| `J3` | NEMA17 motor (JST-XH 4-pin) | 1 A+, 2 A-, 3 B+, 4 B- (pins 1+2 one coil, 3+4 the other); matches StepperOnline 17HS08-1004S (black, green, red, blue); silkscreen A+ A- B+ B- |
| `J5` | LED ring power (JST VH 4-pin, vertical, B4P-VH) | 1-2 `+5V_LED_RING`, 3-4 GND; pin-for-pin with the ring board's `J1` (B4PS-VH) through a VHR-4N cable, SVH-41T-P1.1 crimps, 16-18 AWG |
| `J-LED-SIG` | LED ring signal (JST XH 5-pin, `B5B-XH-A`) | 1 `LED_DATA_OUT`, 2 GND, 3 `LED_CLK_OUT`, 4 GND (5 V, through 33 Ω `R63`/`R64`), 5 `NTC_RING_J` (the ring thermistor: `D34` ESD clamp, `R65` 10k 1% pull-up to +3V3, then `R66` 1k and `C16` 100 nF to GPIO3); straight through to the ring's `J2` with an XHP-5 cable |
| `J-ENC-MAIN` / `-HUE` / `-SAT` / `-VAL` | Encoder headers (1x05) | **pin 1 +3V3, 2 SW, 3 DT, 4 CLK, 5 GND** (silkscreen V, S, D, C, G) |
| `J-ENC-EXP1`-`EXP3` | Expansion encoder headers (1x05) | Same pin order, through the I2C expander. `EXP3` has CLK and DT only |
| `J-BTN-TAP` | Tap tempo button (1x02) | GND, TAP_BTN |
| `J-FAN` | 4-wire **12 V** fan (keyed 1x04, KK254) | 1 GND, 2 +12V, 3 tach (through `R59` to expander port 0 bit 6), 4 PWM (drain of `Q6`). Do not fit a 5 V fan |
| `J-PWR-5V` | 5 V input (Mini-Fit Jr 2x2) | pins 1, 3 `+5V`; pins 2, 4 GND; ahead of the fuses |
| `J-PWR-12V` | 12 V input (JST XH 2-pin, `B2B-XH-A`, 3 A) | pin 1 +12V, pin 2 GND; a different family from `J-PWR-5V` so the plugs can't be swapped |

There is no direction-change button: the speed encoder ramps through zero and reverses. OSC `/directionChange` covers remote use.

The ESP32-S3-ETH and TMC2209 sockets follow the modules' real pinouts, so the modules plug in directly. The TMC2209 module has only 2 GND pins;
`DIAG`/`VREF`/`INDEX` aren't brought out. Each connector's `Value` property in the schematic lists exactly which pins are wired.

**Module orientation** (check against the silkscreen; a wrong orientation mirrors the pins, and a reversed TMC2209 destroys it):
- **ESP32-S3-ETH:** RJ45 side up, USB-C/RJ45 end at the board's top edge; overhangs the edge by about 16 mm.
- **TMC2209:** StepStick orientation rotated 180 degrees from the usual drawing: EN and VM at the bottom (panel-header edge), EN column on the right, VM on the left. Silkscreen `EN` and `VM` mark pin 1.

**Panel wire colours:** Main encoder blue, Hue red, Saturation green, Value yellow, buttons orange, GND black.

### Test points

Thirteen probe points, each silkscreened with what it carries, on copper of its own net (`testpoints.kicad_sch`, `TP1` to `TP13`; not in the BOM or placement files).
The three GND loops take a scope-ground clip; the rest are pads for a probe or a hook. None is under a plug-in module.

| Label | Net | Where |
|---|---|---|
| GND (three loops) | `GND` | top, right of the `J1-H1` socket; top left beside `F1`; beside `EN` |
| 12V | `+12V_MOTOR` | left, beside `D1` |
| 12V F1 | `+12V_MOTOR_F1` | right of `D1`, after `F1` |
| 3V3 | `+3V3` | right of the ESP32-S3-ETH socket |
| 5V | `+5V_LED_RING` | left, above `J5`, after `Q5` |
| DAT 3V3 | `LED_DATA_3V3` | right of the module: GPIO18, the ring data before `R18` |
| SCL, SDA | `I2C_SCL`, `I2C_SDA` | SCL below DAT 3V3; SDA at the right edge |
| EN | `ENABLE` | beside `R23` (low = TMC2209 on) |
| DAT, CLK | `LED_DATA`, `LED_CLK` | in the LED block right of the module: 3.3 V data and clock at the `U3`/`U5` inputs |

`STEP`, `DIR` and the TMC2209 UART lines run only under the plug-in modules, so they have no pad: probe them on the module's own pins.
`kicad_mainboard/tools/add_test_points.py` places the pads and records why each spot was chosen.

### I2C GPIO expander (`U1`, TCA9555)

The main, hue, value and saturation encoder buttons and the expansion headers go through `U1` (address `0x20`, A0-A2 to GND) because `J1` has no spare GPIOs.
Bus: SDA GPIO17, SCL GPIO16, `R21`/`R22` 4.7 kΩ pull-ups to `+3V3`, `~RESET` tied high.

TCA9555PWR (TSSOP-24, [C465732](https://www.lcsc.com/product-detail/C465732.html); UMW C42420608 is an alternate). The firmware also drives an MCP23017 at the same address (older boards, the breadboard): port 0 is its port A, port 1 its port B.

- Buttons: `P0_0` hue, `P0_3` main encoder, `P0_5` value, `P1_5` saturation. Fan tach on `P0_6`.
- Expansion encoders: `EXP1` SW/DT on `P0_1`/`P0_2`, CLK on `P1_6`; `EXP2` SW/DT/CLK on `P1_3`/`P1_2`/`P1_4`; `EXP3` CLK/DT on `P1_1`/`P1_0`.
- `P0_4`, `P0_7` and `P1_7` are spares (inputs, not brought out). `~INT` is not connected.
- Ports A and B are inputs with pull-ups (`GPPUA`/`GPPUB = 0x7F`). The firmware polls them in one transaction for the three buttons and the tach, and **does not read the expansion encoders yet**.

## Firmware pinout

Defined in [`src/pins.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/pins.h).

| GPIO | Signal | Notes |
|---|---|---|
| 46 | `stepPin` | TMC2209 STEP (strapping pin, low at reset) |
| 0 | `enablePin` | TMC2209 ENN, active low (strapping pin; `R23` holds it high so the driver is off through boot) |
| 48 | `dirPin` | TMC2209 DIR |
| 9-14 | ETH PHY reset/IRQ/CS, SPI | Onboard W5500, fixed by the module |
| 21 | `tapBtnPin` | Tap-tempo button (also drives the onboard RGB LED, so only sampled after boot) |
| 38/39 | `encoderPinA`/`B` | Main (speed) encoder CLK/DT (its push button is on the expander, `P0_3`) |
| 1/40 | `hueEncoderPinA`/`B` | Hue encoder (button on the expander) |
| 3 | `RING_NTC_PIN` | Ring temperature (ADC1_CH2): `J-LED-SIG` pin 5 through `R66`/`C16`, pulled up by `R65` |
| 43/44 | `satEncoderPinA`/`B` | Saturation encoder (UART0 pins; boot log on GPIO43; button on the expander) |
| 41/42 | `valEncoderPinA`/`B` | Value/brightness encoder (button on the expander) |
| 47/15 | `tmcUartTxPin`/`tmcUartRxPin` | TMC2209 single-wire UART (TX joined to RX through 1 kΩ) |
| 18/2 | LED engine `dataPin`/`clockPin` | LED ring data and clock (SPI3 for SK9822; RMT on 18 for WS281x), through `U3`/`U5` to `J-LED-SIG` |
| 45 | `fanPwmPin` | Fan PWM, 25 kHz, through `Q6`/`R57`; `R58` pulls the gate low (strapping pin) |
| 17/16 | `i2cSdaPin`/`i2cSclPin` | I2C to `U1` |

GPIO4-8 don't reach the header; GPIO33-37 are reserved for the module's octal PSRAM; GPIO19/20 are the native USB used for flashing and serial.
The three strapping pins used as outputs (0, 45, 46) are driven only after boot. GPIO3 (the ring NTC input) is a strapping pin only for the JTAG source, and only when an eFuse selects it (not burnt), so `R65`'s pull-up at reset changes nothing.

**Boot straps:**
- **GPIO0** must be high at reset or the chip enters download mode. `R23` (1 k to `+3V3`) holds it high, which also leaves the TMC2209 disabled through power-on, a crash or a reset.
  Press the module's BOOT button only with the motor stopped (it shorts GPIO0 and would enable the driver).
- **GPIO45** must be low or VDD_SPI goes to 1.8 V. The `Q6` gate pull-down `R58` keeps it low.
- **GPIO46** (STEP) is read only for boot mode and ROM messages; STEP has no pull-up, so it stays low.

GPIO43/44 double as U0TXD/U0RXD. `Serial` runs over native USB, but the ROM still prints its boot log on GPIO43 at reset; a closed encoder contact can short that for a few ms, which the pin tolerates.

## OSC API

Default listen port `3335` (set on the [config page](#web-config-api)), on Ethernet and/or Wi-Fi. Both links share one UDP socket and one set of
subscriptions, so OSC, the config page, `/log` and `/update` answer on both.

**Wi-Fi** is optional and runs alongside Ethernet as a DHCP station. It tries the network set on the config page first, then up to 4 built-in
networks from `wifi_defaults.h` (gitignored; copy `wifi_defaults.example.h`). Each gets up to 15 s and a rejected one is skipped at once;
after a full pass it waits 15 s and restarts from the first. With no networks, Wi-Fi is off.

- Wi-Fi modem sleep is off for latency; Ethernet is still the lower-jitter link for tempo sync.
- Both links can be on one subnet; replies and `/tap` use whichever interface lwIP picks.
- The Wi-Fi image is about 1.11 MB, so the project builds with `PartitionScheme=app3M_fat9M_16MB` (see [Building / flashing](#building--flashing)).

### Incoming

Numeric arguments may be float32, int32 or float64; NaN/inf, other types and empty messages are ignored.

| Address | Arg | Effect |
|---|---|---|
| `/flash`, `/pulse`, `/pulsediv` | any | Ignored (`onFlashGone()`, one log line): the global beat flash is gone; each preset's punch (`punchstyle=flash` for the old look) hits on the beat. |
| `/beat` | int, beat index in the bar (0 = downbeat); no argument also works | One beat, while the failover has chosen an OSC tempo source. Anchors the beat clock (`/status` `beatPhase` and `beatInMeasure`) and so keeps punch on the beat. Doesn't change tempo. Ignored while the tap is the tempo source. |
| `/measure` | float, bar position in beats (about 30 a second, wraps to 0 on the downbeat) | Sets the beat phase from the bar position. It doesn't count beats; `/beat` does. While the failover has chosen an OSC tempo source. |
| `/bpm` | float, 20-500 | Primary BPM source. Takes over immediately. |
| `/composition/tempocontroller/tempo` | float 0.0-1.0 | Backup BPM source, mapped to 20-500 BPM. Takes over only if `/bpm` isn't fresh, or if already active. |
| `/scaleEncoder` | float 0.0-1.0, wraps | Emulates the main encoder; each 0.0125 of wrap-aware delta is one detent (40 per turn). |
| `/scaleZero` | any | Sets `speedScale` to 0 (stops the motor) and resets the emulated encoder. |
| `/home` | any | Sets `speedScale` to the stored home speed (factory 1.0) and resets the emulated encoder. |
| `/directionChange` | any | Toggles direction (250 ms debounce). While moving, slows to the smooth-motion floor, then reverses; the driver stays on. |
| `/hue` | float, wraps into [0,1) | |
| `/saturation` | float, clamped [0,1] | |
| `/value` | float, clamped [0,1] | The ring's master brightness. |
| `/colourtemp` (or `/colortemp`) | float/int kelvin, 2000-10000 | The ring's colour temperature: 6500 neutral, lower warmer, higher cooler. Runtime only. |
| `/presetmode` | float or int | `0` selects preset 1 (the user colour); it used to choose colour mode, which is gone, and `1` does nothing (see the [User Guide](../USER_GUIDE.html#presets-and-the-knobs)). `/wledmode`, its old name, also works. |
| `/preset` | float or int, 1 to the highest preset | Selects the preset; rounded and clamped to the LED engine's presets. |
| `/palette` | float or int, 0 to the highest palette | Selects the palette (0 = the preset's own); same rules as `/preset`. |
| `/fxspeed` | float or int, -16 to 16 | The effect speed in EXP2 clicks (x 2^(v/8): a quarter to four times the preset's own, 0 its own); rounded and clamped (`lightSetSpeed()`). Until reboot. |
| `/look` | string | A look in the preset format, its keys alone or a whole line (number and `name=` ignored), run in place of the selected preset's until a preset is picked (`ledLiveLine()`; `lightSetPreset()` calls `ledLiveClear()`). Keys left out take the format's defaults. An unreadable string is logged and ignored. |

### Outgoing

| Address | Arg | When |
|---|---|---|
| `/tap` | `1` | Subnet broadcast to port `3336` on each connected link, on every tap-button press or `/live` Tap, whatever the active BPM source. |
| `/tapbpm` | float BPM | Same broadcast when a tap sets a new tempo (from the second tap in a 15 s window), while no OSC tempo source is fresh. |

## Web config API

`http://<device-ip>/` on port 80 (a separate `WebServer`, run from `oscTask()` on core 0).

| Route | Method | Effect |
|---|---|---|
| `/` | GET | Config page with tabs in one form (one **Save & Reboot**): **Status**, **Network** (hostname, Ethernet, Wi-Fi, OSC port), **Defaults** (starting BPM, starting colour, colour temperature), **LEDs** (the LED engine and its preset list), **Motor & fan** (speed limit in RPM and the slow-speed floor slider, both applied and saved at once; reverse direction; fan settings), **Password**. Usage notes are behind (i) tips (`TIP()` in `web_theme.h`, a CSS-only `<details>`). The tab is kept in the URL fragment (`#network`, `#defaults`, `#motor`, `#security`, ...; the old `#show` and `#colour` open Defaults). |
| `/save` | POST | Validates and saves fields to flash (`Preferences`), then reboots. |
| `/maxspeed` | POST | `?rpm=<1-187.5>[&save=1]`: the speed limit, applied at once; `save=1` also keeps it (prefs `maxspeed`, steps/s), written once the motor is stopped. Same-origin checked. |
| `/fan` | POST | `?en=0\|1&lo=<C>&hi=<C>&min=<pct>[&save=1]`: fan temperature range (20 <= lo < hi <= 100), minimum speed, on/off. Same-origin checked; `save=1` persists once the motor is stopped. |
| `/setmin` | POST | `?v=<full-steps/sec>[&save=1]`: live smooth-motion floor. Applies at once; saved only with `save=1` and only once the motor is stopped. Same-origin checked. |
| `/update` | GET / POST | Firmware upload (see [Updating firmware over the network](#updating-firmware-over-the-network)). Disabled until a password is set. |
| `/log` | GET | Log page with Live, Clear and Save .txt controls. |
| `/log.txt` | GET | Last ~12 KB of the log as plain text. |
| `/log/clear` | POST | Empties the log buffer. Same-origin checked. |
| `/about` | GET | The About page: what the unit is, the firmware build (from `/status` `build`), the copyright and the MIT License. Last in the menu's Help list. |
| `/docs/USER_GUIDE.html`, `/docs/HARDWARE_OVERVIEW.html`, `/docs/FAQ.html` | GET | The three HTML documents served by the unit (gzipped into `src/docs_data.h`, about 230 KB of flash), behind the same password. `/docs` redirects to the User Guide. |
| `/live` | GET | Phone-sized page: BPM and source, RPM, speed, direction, Start/Stop/Slower/Faster/Reverse/Tap/Set BPM, hue/saturation/brightness/colour-temperature sliders. Polls `/status` every 0.7 s. |
| `/leditor` | GET | The LEDitor page (it was called the simulator): a live drawing of the ring (`src/ledsim.cpp`, built when `LED_SIM_PAGE` is defined in `pins.h`). Its picture is `/leditor/frame?full=1`, the presets and palettes as written (no hue shift, saturation or brightness; colour temperature in). |
| `/leditor/map` | GET | JSON `[[angleDeg, radiusMm], ...]` for the 178 LEDs in chain order (from `led_map.h`). |
| `/leditor/frame` | GET | 536 bytes: RGB per LED in chain order, the latest frame as sent (after the brightness and colour temperature but before the current limits, which only the ring is held to, 8 bits; `?full=1` gives it before the brightness too), then the platter's angle as a little-endian 16-bit fraction of a turn, counter-clockwise from above, counted from the motor's steps since switch-on (the page turns its edge markers by it). |
| `/leditor/preset` | GET | `id=N`: preset N as its line of text; 404 if not defined. |
| `/leditor/stream` | GET | The same 536-byte frames one after another on one connection that stays open, `fps` a second (5-25, 12 if not given; the pages ask for 15), `full=1` as for `/leditor/frame`: the pages' pictures. One connection rather than one per frame, so a request lost on a busy network can't stall the picture (it did for about 3 s, under Art-Net), and the frames don't queue with the other requests. Sent from `oscTask` without waiting (`ledSimStreamService()`, `MSG_DONTWAIT`); a browser that stops taking frames for 5 s is dropped, and at most 3 streams run (a new one ends the oldest). The pages fall back to polling `/leditor/frame` where there is no stream, and their requests give up after 1.5 s. |
| `/backup` | GET | Backup and restore (`src/backup.cpp`, format in `src/backupfile.h`, PC-tested): `GET /backup/file?what=looks\|all[&wifi=1]` is the backup as text in sections (`[network]`, `[settings]`, `[led]`: the stored preference keys as key=value; `[presets]`, `[palettes]`: the two files' lines); `POST /backup/restore?parts=...` with the file as a text/plain body checks every chosen part, then restores it (a settings part replaces its keys: absent ones are removed, back to factory, except `wpass`), and replies JSON; network, settings or led restart the unit. The admin password is never exported. |
| `/leditor/frame` (preview) | GET | `pv=1` keeps the editor's preview going for 3 s more, `line=<preset line>` sets what it shows, `stop=1` ends it. The preview rides on the frame requests because the server handles one connection at a time. `POST /leditor/preview` also ends it (sent as the page closes). |
| `/leditor/save` | POST | `line=<preset line>`: replaces that preset in the table at once (no restart); the file is rewritten from the table by `ledService()` when the motor is stopped. Same-origin checked. |
| `/leditor/palettes` | GET | JSON `{"free":<first empty user slot or -1>,"palettes":[{"id","name","label","user","defined","edited"},...]}` for palettes 3-18. |
| `/leditor/palette` | GET | `id=N` (3-18): JSON `{"id","name","label","user","edited","stops":["rrggbb",...]}`, the palette's colour stops as in use (none for an empty user slot); 404 for any other number. |
| `/leditor/frame` (palette preview) | GET | With `pv=1`, `pal=<name> <rrggbb> ...` makes the preview show that palette with those colours; `pal=-` goes back to the saved ones. Ends with the preview. |
| `/leditor/palsave` | POST | `line=<palette> <rrggbb> ... [name=<name>]` (1-16 colours; the name only for user1-user8): those colours for that palette at once; `/ledpalettes.txt` is rewritten by `ledService()` when the motor is stopped. Same-origin checked. |
| `/leditor/palreset` | POST | `id=N`: built-in palette N back to its factory colours, or user slot N emptied; `id=0`: every built-in palette (user slots kept). Same-origin checked. |
| `/netmon` | GET | The network input monitor (the Status tab's Art-Net / sACN box): `on` (receiving), `shown` (the artnet effect is running), `first`, `single`, `has` (packets for the ring arrived in the last 2.5 s), `packets` (used), `seen` (per protocol and universe: `proto`, `uni`, `ip` of the last sender, `count`, `ageS`, `used`, `ours`) `other` (non-DMX packets: `count`, last Art-Net `op`, `ip`, `ageS`) and `artpoll` (ArtPoll received: `count`, the last poller's `ip`, `ageS`, and `replies`, the ArtPollReply packets sent; replies only while receiving is on). The Art-Net and E1.31 sockets are open whenever the unit has an address, so it reports packets even with receiving off. |
| `/peers` | GET | The turntables on the network, for the menu bar's list: `searching` (an mDNS search is running), `ageS` (of its answers; null before the first) and `units`, this one first, then by name: `host`, `ips` (one per link), `osc` (port, null from older firmware), `build` (null likewise), `self`. A search (about 2 s, in the background) starts when the answers are over 20 s old; `?fresh=1` starts one anyway. Units announce `_http._tcp` with the instance name *Uncle Magic's Liquid Turntable* and TXT keys `osc` and `build`. |
| `/names` | GET | JSON for the live page: `presets` (number to name, from the preset list) and `palettes` (names by number). |
| `/status` | GET | JSON: `bpm`, `source` (`osc`/`tempo`/`tap`), `oscBpmAgeS`, `tempoCtlAgeS`, `beatsPerRev`, `tempoRpm`, `tempoCapped`, `maxBpm`, `maxRpm` (the speed limit in force), `speedScale`, `homeScale`, `direction`, `running`, `rpm`, `hue`/`saturation`/`value`, `colourTempK`, `lightMode` (`colour`/`preset`), `preset`, `palette`, `fxSpeed` (the effect speed, -16 to 16 as EXP2 counts it), `look` (the running look as preset keys: the live look, or the preset's with its own palette), `lookLive` (a look set from the live page or OSC `/look` is running), `presetMax`, `paletteMax`, `eth`/`wifi`/`rssi`, `chipTempC`/`chipTempMaxC`, `ringTempC`/`ringTempMaxC` (null without a reading), `ringSensor` (`ok`/`open`/`shorted`/`none`), `ringLimitMa` (the ring limit in force), `fanPct`, `fanTach` (`turning`/`stopped`/`none`), `white` (the live page's white background over every preset), `bench` (no motor driver at start-up: the ring's temperature sensor is ignored), `oscPort` (the OSC listen port; the live page's heading shows it after the address), `uptimeS`. |
| `/wifi` | GET / POST | Wi-Fi setup page: link status, a network name (with the networks seen when the setup access point started) and password; saving writes them (`cfg` `wssid`/`wpass`) and restarts. Same-origin checked. Served on every link, and the target of the setup access point's captive-portal redirect. |
| `/leds` | GET | Redirects to the settings page's **LEDs** tab (`/#leds`), which shows what is running (output, frame rate, estimated current, limiter, Art-Net), the engine settings form, the preset file editor. |
| `/control` | POST | `?a=<action>[&v=<value>]`, same-origin checked, replies with `/status`. Actions: `start`, `stop`, `faster`/`slower` (+-5%), `reverse`, `tap`, `bpm` (20-500), `hue`/`sat`/`val` (0-1), `ctemp` (2000-10000), `speed` (-2 to 2: `speedScale` itself; 1 is in tempo), `maxrpm` (1-187.5: the speed limit until restart), `white` (0/1: every preset's dark parts white, until restart), `colour` (`rrggbb`: sets hue and saturation, leaves brightness), `mode` (0 colour, 1 preset), `preset` (1-top), `palette` (0-top), `fxspeed` (-16 to 16: the effect speed as EXP2 counts it, x 2^(v/8), 0 the preset's own; until restart), `look` (preset keys: run that look until a preset is picked, as OSC `/look`). |

**Password.** HTTP Basic auth, user `admin`. While none is set every page is open; set one on first use (8+ characters, stored in NVS).
Then every page needs it, and `/save` and `/update` refuse cross-site posts. OSC is not password-protected.

**Forgot the password, or saved a bad static IP?** Hold the tap-tempo button while powering on, for 5 seconds. That clears the password and
returns the network to DHCP; other settings are kept.

**Persisted fields:** static IP/gateway/mask (`0.0.0.0` = DHCP), hostname, Wi-Fi name and password, OSC port, starting colour (`#rrggbb`, default white),
switch-on colour temperature (default 6500 K), starting BPM, reverse motor direction, password; saved without a reboot: the speed limit (`/maxspeed`), the slow-speed floor, and the fan settings.

`microsteps` is fixed at 32 in firmware and is not configurable (see [TMC2209 configuration](#tmc2209-configuration)).

## Design notes

### BPM source failover

Priority order: `/bpm` (OSC) then the tempo-controller OSC feed then the local tap-tempo button. `bpmEverReceived` and
`tempoControllerEverReceived` flags separate "never arrived" from "arrived at `millis()==0`".

**Beats follow the failover.** `/beat` and `/measure` count while the failover has chosen an OSC tempo source (`/bpm` or the tempo controller), and are ignored while the tap is the tempo source. The gate is a flag that `setBpmSource()` sets whenever the failover changes the source, so it doesn't look at who sent a message. A change of source clears the beat clock. Two senders can't be told apart this way: if both send `/beat` at once, both count, so send beats from one place at a time.

**Beats keep the tempo alive.** Pulse sends `/bpm` only when the tempo changes, so a steady tempo would time out after `bpmTimeout` (60 s). A beat from the chosen sender refreshes that sender's freshness stamp, so the tempo stays on it while beats keep arriving. When the beats stop, the usual timeouts apply.

Tempo sources set tempo only. `/bpm`, the tempo controller, the tap button and `/live`'s BPM field change BPM and nothing else. Starting, stopping and trimming the
platter (`speedScale`) is left to the encoder (short press recalls home speed, 1 s hold stores the current speed as home, 5 s hold restores the factory home of 1.0),
OSC `/scaleEncoder`/`/scaleZero`, and `/live`'s buttons. The platter boots stopped. A stale source just leaves the last BPM in force.

### Speed ramping and the smooth-motion floor

[`motion.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/motion.h) (`motion::step()`) holds the control law with no Arduino headers, so it is unit-tested on a PC. `loop()` calls it once per pass:

1. `rampedSpeed` chases `defaultSpeed` (the BPM-derived target) at a wall-clock rate (`bpmRampSeconds = 1.5 s` to cross 0 to `maxSpeed`).
2. `|speedScale|` goes through a deadzone with hysteresis (enter 0.01, exit 0.02).
3. The magnitude is `|speedScale|`'s 0-1 range remapped proportionally onto `[smoothMinSpeed, rampedSpeed]`. `smoothMinSpeed` is the floor in full-steps/sec (default 2.0, about 0.6 RPM, tunable live on the Motor & fan tab). Interpolation and StealthChop make low speeds smooth, so the floor is a feel setting, not a fixed threshold.
4. The result is slewed at the same rate, so no input can jump the platter (about 0.9 s from rest to 10 RPM).
   - **Start:** begins at the floor (at least 1 full-step/s), not zero.
   - **Reversal:** slows to the floor, flips, climbs the new way; the driver stays on.
   - **Stop:** glides to the floor (about 1.5 s from full speed), then the driver is disabled.
   - The time step is capped at 50 ms (`kMaxDt`) so a slow `loop()` pass can't cause one large jump.

### TMC2209 configuration

- `microsteps = 32` with `intpol(true)`: the driver interpolates to a 256-level waveform at 1/8 the step rate. `maxSpeed`'s default (1813.3 steps/s = 17 RPM) is derived for 32 microsteps;
  recompute it (`motorFullStepsPerRev * microsteps * RPM / 60`) if that changes.
- `TMC_RMS_CURRENT_MA = 800`, set only by this constant (`GCONF.I_scale_analog` is cleared, so the carrier's trimpot is ignored).
- `pdn_disable(true)` and `mstep_reg_select(true)` are required so UART-written registers take effect.
- `checkTmcHealth()` runs every 5 s: detects UART loss, a driver logic-supply reset (re-applies config), and overtemperature or short-to-ground faults. Logs only on state changes.

### Dual-core split

| Task | Core | Job |
|---|---|---|
| `loop()` | 1 | Speed control, encoders and buttons, TMC2209 health checks. |
| `oscTask()` | 0 | OSC pumping, config web server, `checkTapBroadcast()`. |
| `wifiTask()` | 0 | Walks the Wi-Fi candidate list and reconnects. |
| `mdnsTask()` | any | Once, after the first address: checks the hostname is free, announces the name, exits. |
| Arduino event task | any | `onNetEvent()` (link and Wi-Fi events). |
| Step timer ISR | n/a | Toggles STEP from a hardware timer. |

- **Loop supervision:** `loop()` bumps a heartbeat; `loopMonitorTask()` (core 0) restarts the chip if it stops for **3 s**, after switching the driver off and stopping the step timer.
  The backstop is the ESP-IDF task watchdog on `loop()` (configured 5 s, measured about 12 s on the bench). `R23` keeps the driver disabled until `setup()` runs again.
  The next boot logs `Reset reason: LOOP STALL` or `TASK WATCHDOG`. To test, define `WDT_TEST_HANG_MS` (for example 20000) at the top of the sketch, then remove it.
- **Logging:** each task builds its own line and emits it whole on the newline, so tasks can't interleave mid-line.
- **Shared state** (`BPM`, `speedScale`, `bpmSource`, `hue`/`saturation`/`hsvValue`, `direction`) is guarded by a `portMUX_TYPE` spinlock (`stateMux`); `loop()` reads `speedScale` and `direction` once per pass as one snapshot.

### Presets and the knobs

The ring always runs a preset ([`presetmode.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/presetmode.h), [`lighting.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/lighting.cpp)); colour mode is
gone (2026-11-15). The VAL knob steps `lightPreset` through 1..`lightPresetTop()`, wrapping, until its button switches
it to the master brightness (`valKnobPreset`), and back; EXP1 steps `lightPalette` through 0..`lightPaletteTop()` (its
button: 0), EXP2 the effect speed (`lightSpeedClicks`, its button: 0). HUE and SAT are always the hue shift and
saturation scale that `ledfx::adjustColours()` applies to every rendered frame (HUE button: shift 0; SAT button: white on
and off). Palette 1, `usercolour` (formerly `unit`, palette 2), is one colour, `userRgb`, set by `/control?a=colour`; preset 1 shows
it. None of it is remembered across a restart. Also reachable from `/control` (`preset`, `palette`, `colour`, `hue`,
`sat`, `val`), OSC and the live page. The LED engine reads it all every frame, so there is nothing to send or coalesce.

### Wi-Fi setup without Ethernet

[`src/netsetup.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/netsetup.cpp), decisions in [`src/setupap.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/setupap.h) (PC-tested, `tests/test_setupap.cpp`).

- **Setup network serves `/wifi` only:** a request whose local address is 192.168.4.1 (`fromSetupNetwork()`) gets the
  Wi-Fi page and nothing else; `authorized()` redirects every other route there and `/update` refuses the upload
  (`setupap::apPathAllowed()`, tested). The network's password is shared by every unit, so it must not open the controls.
- **Setup access point** `LiquidTurntable-XXXX` (last two MAC bytes), WPA2 password `turntable`, at 192.168.4.1, with a
  catch-all DNS server and redirects for the phones' captive-portal probes (`/generate_204`, `/hotspot-detect.html`,
  `/connecttest.txt`, ...) to `/wifi`. It starts once, 60 s after boot, if no link has an address, or at once after the
  TAP hold at power-up (`checkPasswordResetButton()`, which also clears the password and static IP), for 15 minutes.
  It stops when a link has had an address for 2 minutes with no station joined. While a phone is joined, `wifiTask()`
  holds off its station attempts, whose scans would knock the phone off. Runs from `oscTask()` on core 0 with the web server.
- **Serial command** (USB, `serialConsoleService()` from `loop()`): `wifi <name> [password]` (quotes for spaces),
  `wifi` for status, `wifi -` to forget. Saves `cfg` `wssid`/`wpass` and restarts.

### LED engine (the standard LED driver)

This chip drives the ring itself. **On by default**, set for the SK9822 ring: data GPIO18, clock GPIO2,
colour order RBG, current field 31 with a 36.6 mA per-LED limit, 4.5 A ring limit, 2 MHz. User-facing description: [User Guide, "The LED engine"](../USER_GUIDE.html#the-led-engine).

**Settings.** Settings page, **LEDs** tab (NVS namespace `led`); saving reboots. `setup()` calls `ledLoadSettings()`
and `ledEngineBegin()`. `lightPresetTop()`/`lightPaletteTop()`
give the engine's preset and palette counts to the knobs, `/control`, OSC and `/status`.
Hardware: GPIO18 -> `R18` -> `U3` -> `R63` -> `J-LED-SIG` pin 1 (data) and GPIO2 -> `R61` -> `U5` -> `R64` -> pin 3 (clock).
An older SKC6812RV (WS281x) ring can still be run by choosing **WS281x** on the **LEDs** tab; it needs its data on `J-LED-SIG` pin 1.

**Structure.** Arduino-free and PC-tested: [`src/ledout.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/ledout.h) (wire byte orders, current limiter, WS281x and
SK9822 frames), [`src/ledfx.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/ledfx.h) (palettes, tempo tracker, effects),
[`src/ledpreset.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/ledpreset.h) (preset file format, built-in presets), [`src/artnet.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/artnet.h) (ArtDmx and
E1.31 parsing, universe mapping, takeover) and [`src/led_map.h`](https://github.com/scoobiekw/LiquidTurntable/blob/main/src/led_map.h), generated by
[`tools/gen_led_map.py`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tools/gen_led_map.py) from `kicad_led_ring_offset/LEDRing.kicad_pcb` (angle and radius per LED in
chain order; the chain is followed through the DIN/DOUT nets, not assumed from the reference numbers; `--check` says whether
the header is current). Glue: `src/ledengine.cpp` (render task, presets on FAT, sockets, `/leds`) and `src/leddriver.cpp`.

- **Render task** on core 0, every 10 ms: snapshot of the shared controls under `stateMux`, then the preset
  (`ledpreset::resolve()` with the palette override, the user colour as palette 1), the hue shift and saturation
  (`ledfx::adjustColours()`), master brightness (VAL, eased over
  about 60 ms; each preset's punch hits on the beat inside `render()`), colour-temperature gains, the
  current limiter, encode, send.
- **Timing.** `ledfx::trackTempo()` free-runs at `BPM` and, while the beat clock is fresh, pulls a tenth of the phase error
  per frame toward `beat::phase()`. Effect phase is accumulated per frame from the speed (turns per bar, per beat, or per
  platter turn from `appliedStepsPerSec` / 6400), so a speed change never jumps.
- **Output.** WS281x: RMT TX channel with DMA, 10 MHz ticks (0 = 0.3/0.9 us, 1 = 0.6/0.6 us), bytes encoder, the buffer
  sized for the whole frame so it is encoded once per frame and the RMT/DMA interrupts are few; if no DMA channel is free
  it falls back to 192-symbol ping-pong refills (logged). SK9822: SPI3 (SPI2 is the W5500's) with DMA at 4 MHz: 32-bit zero
  start frame, `0xE0 | field` plus three colour bytes per LED, a 32-bit zero reset frame (so an SK9822
  latches now, not on the next frame), then max(4, n/16) bytes of `0xFF`. The field is per LED (`encodeSk9822Hd()`): the
  smallest, up to the configured one, that the LED's brightest channel fits in, with the PWM values raised to match, so
  a dim LED keeps up to about 13 bits (31 x 255 steps) instead of 8. The SK9822's field sets the drive current, not a
  slower PWM, so this does not flicker on camera (an APA102 would). Both drivers are created from the render task, so
  their interrupts are on core 0, away from the 1 MHz step ISR on core 1. Byte order is a setting (GRB for SKC6812RV;
  SK9822 default RBG).
- **Brightness depth.** The frame is rendered in 8 bits, then the brightness and colour temperature are applied into
  16 bits (`Rgb16`); the limiter and the encoders work from that. VAL and the pulse brightness are lightness (how bright
  it looks): `lightToLevel()` applies the CIE 1931 curve, so the knob's 100 clicks are even steps to the eye (half the knob
  is 18 % of full light, the first click 0.11 %). Easing (about 60 ms) is in lightness too. WS281x output is rounded to 8
  bits, so it steps at the bottom of the knob.
- **Current limiter.** Per-LED model: `maPerLed` at full white split evenly over the channels and linear in the value, plus
  `idleMaPerLed`; the frame is scaled as a whole (rounded down, so never over) to stay under `capMa`. Defaults 36 mA, 0, 4500 mA.
- **Palettes:** eight of the ten built-in palettes (rainbow, stripes, party, ocean, lava, forest, cloud, heat) are
  FastLED's tables (MIT), copied into `ledfx.h` as `kNamedPalettes`, so no LED library is needed; the other two,
  `redbluewhite` (2; it was 1 until 2026-11-15, when the user colour took 1) and `ember` (11), are three colour stops
  each (`kRedBlueWhite`, `kEmber`). `redbluewhite` used to be `colours`, a loop through each preset's `c1`-`c3`:
  `palette=colours` still reads as `redbluewhite`, `c1`-`c3`
  are still checked but unused, and `colours` with exactly ember's three colours (the old built-in preset 5) reads as
  `ember`, so a stored list keeps its look. Sampling (LINEARBLEND-style, wrapping) and everything else are in `ledfx.h`
  too, so they are tested on the PC.
- **Width and drift** (`Look::width`, `Look::drift`; preset keys `width=`, `drift=`, written only when not the defaults):
  width is the lit share for spiral (the exponent of the arm's raised cosine, 16 to 0.25, 2 at 128) and noise (the
  brightness layer's threshold); 128 renders exactly as before the key. Drift moves `Motion::origin`, the angle every
  effect measures from, in turns per unit, so a wipe's start, a sweep's palette layout and a palette's seam travel.
- **White background** (`Look::white`; preset key `bg=white`, written only when set): `render()` mixes each LED
  towards white instead of towards off (`shade()`, a lerp from white at level 0 to the colour at level 1) for the
  effects with dark parts (sweep, segments, spiral, pulse, noise, ripples, sparkle, strobe). It happens before
  brightness and colour temperature, so the white is the colour-temperature white at the VAL level, and the current
  limits apply as usual.
- **Ripples, sparkle, strobe** (`FX_RIPPLES`, `FX_SPARKLE`, `FX_STROBE`). Ripples: `count` raised-cosine rings across the
  radius at `(radius - phase) x count`, width as the spiral's arms, intensity fading them towards where they go.
  Sparkle: each LED has a fixed random offset into the phase (`hash01()` from the noise hash); at each whole turn of
  `turns + phase + offset` it lights with probability `0.02 + 0.6 x intensity` and fades as `(1 - f)^k` (width sets k),
  so it is stateless and runs backwards with a negative speed. Strobe: `Motion::strobeAt` is the platter's position
  against the pattern's own rotation (`+ dPlatterTurns - speed x unit`); each change of `floor(position x count)` resets
  `strobeAge`, and the ring is lit while `strobeAge < strobeHoldMs(width)` (4-40 ms).
- **Look keys added with them** (each written to a preset line only when not its default): `paint` (`Paint`: the
  effect's own colours, or by angle, radius, arm or along a sweep's tail), `punch` (a beat envelope `env = (1 -
  beatPhase/0.5)^2`: the picture dimmed by `0.75 x punch x (1 - env)`, and the effects whose intensity or width is the
  lit share widened by `0.6 x punch x env`), `radial` (palette, wipe, segments, sweep measure along the radius instead
  of round the ring), `steps` (the rendered phase is `phase + perBeat x (smoothstep(0, 0.15, beatPhase) - beatPhase)`:
  still through the beat, a quick jump at its start; not for platter units or bounce), `every` and `inward` (pulse),
  `churn` (noise: its time is now `Motion::noiseZ`, accumulated at `churn/100` of the old rate, so at 100 it matches
  the old `beats x 0.125` exactly). The sweep takes `count` heads and the pulse `count` rings.
- **Crossfade and the live look** (`ledengine.cpp`): a change of preset or palette keeps the old look running with a
  copy of `Motion` and blends it out over `kFadeMs` (500 ms). A live look (`ledLiveLine()`: the live page's effect
  settings, `/control?a=look`, OSC `/look`) replaces the preset's until `lightSetPreset()`; the palette override still
  applies. The LEDitor preview wins over both.
- **Noise effect** (`FX_NOISE`): our own 3D gradient noise (`noise3()`, hashed lattice gradients, quintic fade, z periodic
  over `kNoiseZPeriod` cells) sampled in polar form, after Animartrix's idea but none of its code (that is CC BY-NC).
  Each LED samples on a circle round a fixed point (its angle times `count`, minus the phase) at a depth of its radius
  plus time; the circle shrinks with `count`, so blobs keep their size. Colour and brightness are two layers drifting in
  opposite directions, so the field changes shape rather than flows. Time is `Motion::noiseZ`, half a cell a bar
  (times `churn/100`), kept within the noise's z period, so there is no jump.
- **Presets** in `/ledpresets.txt` on the `ffat` partition (formatted on first mount). Up to 64, one per line (format in
  `ledpreset.h`); the 22 built-ins are written on first boot. The LEDs tab is part of the settings page's one form: `/save` calls
  `ledFormCheck()`, which parses the whole preset text first and refuses the save with the line number if any line is
  bad, then `ledFormSave()` writes the `led` settings and, if the list changed, the file, just before the restart.
- **Palettes** 2-11 (the built-in ones) are editable from the `/leditor` page's palette editor (`palstore.h`, PC-tested),
  and 12-19 (`user1`..`user8`) are slots its **Save as new** fills, each with an optional name (23 characters). Each
  is 1-16 colour stops, spread evenly over the engine's 16 entries with a looping blend (16 stops are the entries as
  they are, which is how the factory FastLED tables are kept). `/ledpalettes.txt` holds a line per *changed* built-in
  palette or filled slot, `<palette> <rrggbb> ... [name=<name>]`; a built-in palette without one is the factory one, a
  slot without one is empty (drawn as `redbluewhite`). `ledPaletteTop()` (the EXP1 knob, `/palette`, the live page's list) is
  11 or the last filled slot. Edits are in use at once (the
  render task reads an expanded table swapped under `ledMux`) and written by `ledService()` when the motor is stopped.
- **Art-Net / E1.31** (setting, off by default): UDP 6454 and 5568 on lwIP sockets, polled from the render task; E1.31
  multicast groups 239.255.x.y are joined on each link's address. Universes U and U+1 (setting, default 1): LEDs 1-170 and
  171-178, RGB. **Layout** (settings `art1`, `artgrid`): two universes (the chain, as above), one universe, or the grid.
  The grid (`artgrid`) is the ring as one 31 x 15 rectangle, cells 6.35 x 12.7 mm so every LED is on its own
  (`artnet::gridCellOf()`, made once from the LED map), 1395 channels as one run over universes U to U+2
  (`artnet::applyGrid()`; a cell can straddle two universes), for Resolume (`tools/gen_resolume.py`: the fixture and an
  Advanced Output setup in `docs/fixtures/resolume/`). One universe (`art1`): universe U only, 170 elements; eight chain-adjacent pairs on the outer
  edge share one (`artnet::kSinglePairFirst`: D1+D2, D3+D4, D5+D6, D83+D84, D95+D96, D173+D174, D175+D176, D177+D178). The look's `hflip` / `vflip` mirror the received picture (x to -x, y to -y in the LED map's frame, as the pages draw it) before it turns: each LED's source place is mirrored after the turn back, and as the ring is symmetric both ways and kNetReachMm (12 mm) is under the 12.7 mm spacing, a mirrored place takes exactly one LED's colour. The ring shows the network's frame only while the running look's effect is `artnet` (`FX_ARTNET`, built-in preset 23): `ledfx::render()` draws it from the last frame received (held when nothing arrives), turned by the look's rotation (resampled from the LEDs within `kNetReachMm`) and punched like any pattern. Unticked, the setting `art` ignores what arrives and hides the effect from the lists and the VAL knob. As sent (no brightness, temperature or flash) unless **HSV on Art-Net** (setting, `arthsv`, off by default) is ticked: then `adjustColours()` with the hue shift and saturation, and the eased brightness, act on it; never temperature or flash; the limiter always applies. Priority and ArtPoll replies are not implemented.

## Building / flashing

```bash
arduino-cli compile --fqbn esp32:esp32:esp32s3:PSRAM=opi,FlashSize=16M,PartitionScheme=app3M_fat9M_16MB,CDCOnBoot=cdc,USBMode=hwcdc LiquidTurntable.ino
arduino-cli upload -p <port> --fqbn esp32:esp32:esp32s3:PSRAM=opi,FlashSize=16M,PartitionScheme=app3M_fat9M_16MB,CDCOnBoot=cdc,USBMode=hwcdc LiquidTurntable.ino
```

`sketch.yaml` sets this FQBN as the default, so `arduino-cli compile .` in this folder works.

**The usual build is `tools/build.ps1`** (Windows PowerShell): it compiles, keeps the firmware in `build/` and moves the previous build to `build/archive/<date>_<commit>/` (the newest 10 are kept). A failed build leaves `build/` alone. `-Upload` (and `-Port`, default `COM3`) then flashes those same files over USB.

```powershell
powershell -ExecutionPolicy Bypass -File toolsuild.ps1 -Upload
```

`build/` then holds `liquidTurntable_YYYY_MM_DD_HHMM_firmware.bin` (the distributable: the app, named with the build's date and time), `LiquidTurntable.ino.bin` (the same app, for `/update`), `.merged.bin` (everything, flashed at 0x0), the bootloader and partition images, the `.elf` (to decode a crash's backtrace) and `build_info.txt` (the commit, with `+changes` if the tree wasn't clean).

**A release candidate is published** with `-Publish` (a plain build never is): the distributable goes to the web server (`tools/publish_firmware.py`, the docs upload's login in `tools/publish.local.json`; folder `firmware_remote` there, by default `firmware/liquidturntable` beside the docs) as `archive/liquidTurntable_YYYY_MM_DD_HHMM_firmware.bin`, `archive/index.html` lists the archive, newest first, and `latest.json` names it for the unit's Status tab and `/update` page to compare with their own build (the browser fetches it; `.htaccess` there lets other origins read that one file), and `latest.html` starts the newest build's download (from HTTPS: a download started from the unit's plain-HTTP page is blocked by Chrome). The unit's `/update` page links to both (https://kennedy-williams.net/unclemagic/firmware/liquidturntable/). The build's name and commit are compiled in (`src/fw_version.h`, written by the script, git-ignored) and shown on `/update`. `-Publish` builds only a clean commit that is on GitHub, and refuses anything else before compiling; a failed upload doesn't stop the flash.

- `PSRAM=opi,FlashSize=16M` match the module's octal PSRAM and 16 MB flash.
- `PartitionScheme=app3M_fat9M_16MB` gives two 3 MB OTA slots (the image is about 1.11 MB). In the Arduino IDE: Tools, Partition Scheme, "16M Flash (3MB APP/9.9MB FATFS)".
  The partition table is written only by a USB flash, never by `/update`; the boot log warns if the image was built with a smaller scheme.
- **`CDCOnBoot=cdc,USBMode=hwcdc` is required:** otherwise `Serial` takes UART0 on GPIO43/44, which are the saturation encoder pins. In the IDE: Tools, USB CDC On Boot, Enabled, and USB Mode, Hardware CDC and JTAG.

Libraries: `ArduinoOSC` (`ArduinoOSCETH.h`; its `OscEther` also serves Wi-Fi), `TMCStepper`, and the ESP32 core's `ETH`/`WiFi`/`WebServer`/`Preferences`/`Update`.


### Building in WSL

`tools/build.ps1` compiles in WSL (Ubuntu) when arduino-cli is set up there, and with the Windows arduino-cli otherwise (`-Windows` forces that; `-Distro` picks another WSL distribution). Flashing always uses the Windows arduino-cli. Set it up once, from this folder (about 7.3 GB, nearly all of it the ESP32 core; the same arduino-cli, core and library versions as CI):

```powershell
wsl -d Ubuntu -- bash tools/setup_wsl_build.sh
```

Why: every `#include` makes the compiler probe about 400 ESP32 include folders. A failed lookup costs about 90 us on Windows and 3.5 us in WSL, and arduino-cli redoes its library scan (a preprocessor run per file, one after another) whenever a file's `#include` lines change. Measured: that rescan took about 11 minutes on Windows (Defender exclusions made no difference) and 61 s in WSL; an ordinary build 60 s on Windows, 26 s in WSL. The binaries differ only in the source paths compiled into log and assert messages.
### First boot

A new or factory-reset unit uses **DHCP**. Find it by any of:

- **`http://liquidturntable.local/`** (mDNS; Windows 10+, macOS, iOS, Linux with Avahi; Android varies).
- The router's client list, looking for `liquidturntable`.
- The USB log at 115200 baud: connect the module's USB-C (the board must also be externally powered, see [Powering the board while flashing](#powering-the-board-while-flashing)). It prints "ETH got IP: ..." and the mDNS name.

**Several turntables on one network:** the name can be changed on the config page (letters, digits, hyphens). At start-up each unit checks whether its name is taken and
if so uses `liquidturntable-1`, `-2`, ... up to `-9`; the log says so. Numbering depends on power-up order, so give each unit its own hostname to keep names fixed.

Then set a web UI password, and a static address if wanted (or reserve one in the router). OSC senders need the board's IP, or the `.local` name where supported.

### Updating firmware over the network

After the first USB flash, updates go over Ethernet or Wi-Fi with the board on its normal supply:

1. Set a web UI password (once).
2. Build: `tools/build.ps1` (or `arduino-cli compile --fqbn esp32:esp32:esp32s3:PSRAM=opi,FlashSize=16M,PartitionScheme=app3M_fat9M_16MB,CDCOnBoot=cdc,USBMode=hwcdc --output-dir build LiquidTurntable.ino`)
3. Upload `build/LiquidTurntable.ino.bin` (**not** `.merged.bin`) at `http://<device-ip>/update`, or:
   `curl -u admin:<password> -F "firmware=@build/LiquidTurntable.ino.bin" http://<device-ip>/update`

During the upload the motor stops and the driver is disabled. A failed or 60 s stalled upload resumes on the old firmware; success reboots into the new image.

**Rollback:** a new image stays unconfirmed until it has run 30 s with Ethernet or Wi-Fi up. A crash or reboot before that returns to the previous firmware. If it runs but never gets an IP, it reverts at the next reboot.
`/log` reports both "unconfirmed" and "was rolled back".

**Still needs USB:** the first flash, recovery from a confirmed build that breaks networking, and any partition-table change.

### Powering the board while flashing

The ESP32-S3-ETH's USB-C **powers the logic** (ESP32, Ethernet, expander, encoders, TMC2209 VIO) through the module's own diode and regulator, so flashing and
web-page work need nothing else. The motor needs the 12 V supply and the ring the 5 V supply.
With both USB and the 5 V supply connected the 5 V supply wins (about 4.7 V on `VSYS` against USB's 4.3 V after the module's 1N4148), and nothing flows back into the USB host.

**The LED buffers** (`U3`, `U5`) and the module's `VSYS` run from `+5V_LED_LOGIC`, fed from `+5V_LED_PSU` through `D33`. `D33` drops about 0.3 V; keep the 5 V supply at 5.1 V (the SK9822's limit is 5.3 V).

### LED engine setup

- Nothing to flash: the LED engine is part of this firmware and on by default for the SK9822 ring.
- On `/leds`, check **LED type** SK9822, **Data GPIO** 18, **Clock GPIO** 2, **Colour order** RBG, **SK9822 current** 31, **mA per LED** 54, **Limit per LED** 36.6 mA, **Limit for the whole ring** 4500 mA.
- The 22 built-in presets are written to `/ledpresets.txt` on first boot; edit them on the **LEDs** tab.

## Testing

PC-side unit tests need no hardware:
- [`tests/test_motion.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tests/test_motion.cpp): the speed control law (start, tempo change, stop, reversal, deadzone, floor and cap, plus a 400,000-step randomized invariant run).
- [`tests/test_colour.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tests/test_colour.cpp): HSV/RGB, hex handling, colour-temperature gains.
- [`tests/test_quadrature.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tests/test_quadrature.cpp): the encoder decoder (`src/quadrature.h`).
- [`tests/test_ledout.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tests/test_ledout.cpp), [`tests/test_ledfx.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tests/test_ledfx.cpp), [`tests/test_ledpreset.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tests/test_ledpreset.cpp), [`tests/test_artnet.cpp`](https://github.com/scoobiekw/LiquidTurntable/blob/main/tests/test_artnet.cpp): the LED engine (byte orders, limiter, WS281x/SK9822 frames; ring map, palettes, tempo tracker, every effect, flash; preset file; Art-Net/E1.31 parsing and takeover).

Run `tests/run_tests.sh` (g++ or clang++) or `tests\run_tests.bat` (Visual Studio Build Tools) after any change to `motion.h`, `colour.h` or `src/quadrature.h`.
Network, web UI, TMC2209 and the ring can only be checked on the board.

**CI** (`.github/workflows/ci.yml`, every push and pull request): *Unit tests and documents* (`tests/run_tests.sh`, and `python docs/build_docs.py --check`, which fails if the HTML or
`src/docs_data.h` is out of date with the Markdown) and *Firmware compiles* (ESP32 core 3.3.11, ArduinoOSC 0.6.0, TMCStepper 0.7.3, without `wifi_defaults.h`).

## Board notes

- **Mainboard PCB:** 100 x 100 mm, two layers, four M3 holes, **1 oz copper** (JLCPCB's default). The ring current is held to 4.5 A by the LED engine and the 5 V side has a 7.5 A fuse.
- **Layout:** the panel strip along the bottom edge holds the seven encoder headers, `J-BTN-TAP`, their protection cells and the lines to the processor and expander, in the order
  MAIN, VAL, TAP, EXP3, EXP2, SAT, EXP1, HUE from left to right. `kicad-cli pcb drc --schematic-parity --refill-zones`: 0 violations, 0 unconnected, 0 parity issues.
  `kicad_mainboard/tools/route_sockets.py` and `microroute.py` are the Freerouting-based routing tools.
- **Measured module dimensions:** ESP32-S3-ETH `H1`/`H2` row spacing 17.78 mm, TMC2209 rows 15.24 mm.
- **LED ring current path (4.5 A held, 7.5 A fused):** copper pours, not traces. A full B.Cu ground plane carries the return; F.Cu pours 12-18 mm wide carry `+5V_LED_PSU` and `+5V_LED_RING`
  from `J-PWR-5V` through `Q5` to `J5`. All +5V legs stay on F.Cu so the ring current never crosses a via. IPC-2221 (external, 1 oz): the narrowest point, 6.5 mm, carries about 9.2 A at a 10 C rise and 12.5 A at 20 C, both above the 7.5 A fuse.
- **Power-path simulation:** at 2 oz the ring +5V path was about 1.4 mOhm of copper and the ground return 1.2 mOhm; at 1 oz about twice that, about 13 mV at 4.5 A. 12 V motor path about 50 mOhm at 1 oz (0.1 V at 2 A).
- **Silkscreen:** designators are visible except on crowded parts. Encoder, tap and expansion headers show short names (MAIN, HUE, SAT, VAL, EXP1-3, TAP) and a letter per pin
  (V=+3V3, S=SW, D=DT, C=CLK, G=GND; `x` for `J-ENC-EXP3`'s unconnected SW). `J3`'s labels (A+, A-, B+, B-) sit inside its outline, pin 1 (A+) at the bottom.

## Heat and ventilation

Estimated heat in the enclosure (these figures were made for an earlier 14 x 17 x 2 in box of 1/2 in birch; the current box is 6 mm birch, about 13.3 x 10.7 x 2.7 in inside, and has not been re-estimated); none measured yet:

| Source | Heat |
|---|---|
| Stepper motor (0.8 A RMS per coil) | about 3-4.5 W |
| TMC2209 | about 0.6 W |
| 3.3 V electronics plus the module's regulator and `D33` | about 2.2 W |
| `D1` | about 0.3 W |
| LED ring | about 3.9 W per amp of ring current |

A closed box sheds about 0.9 W/K, the ring board about 0.56 W/K. At a 110 F (43 C) room a sealed enclosure holds an average ring current of about 2 A (about 3 A with generous vents) with the
ring board near 75 C. High brightness for hours needs forced air: 6-15 CFM, one slow 120 mm fan. Estimates are about +-50%.

- **Measure:** the Status tab, `/status` and the log (every 5 minutes, warning above 80 C) report the ESP32-S3's on-die temperature, a few degrees above nearby air. Run the real ring brightness for two hours with a
  thermocouple on the ring's back and an IR thermometer on the acrylic.
- **Limit first:** keep the LED engine's limit at 4500 mA (the **LEDs** tab), about 4.5 A of ring current.
- **Layout:** a 120 mm fan fits best in the bottom panel, with filtered intake low and exhaust slots high on the far wall. An aluminium heat plate under the ring (1/8 in 6061-T6 on a thermal pad, `enclosure/ring_plate.dxf`) lowers its temperature; see `enclosure/MOTOR_MOUNT.md`.
- **Fan header `J-FAN`** (bottom-left of the board): a keyed 4-pin header for a **4-wire 12 V PWM** fan, at most 0.5 A, powered from `+12V_MOTOR` after `F1` and `D1`, so it runs whenever 12 V is on.
  **A 5 V fan would be damaged.** GPIO45 drives `Q6` (2N7002, signal inverted). With the pin floating (reset, crash, no firmware) **the fan runs at full speed** via its own PWM pull-up.
  The tach (open collector, 2 pulses per rev) goes through `R59` (4.7k) to the expander's `P0_6`; the firmware reads it every ~20 ms, enough to tell turning from stopped (Status tab, `fanTach`, log warning). Use a true open-collector tach.
- **Fan choice (checked 2026-10-05):** ARCTIC P12 PWM PST (120x25, 12 V, 0.1 A, 200-1800 rpm, about 6-10 USD) or Noctua NF-P12 redux-1700 PWM (0.08 A, about 16 USD). Keep the minimum speed at 20% or more so the tach check
  doesn't report a stall. Not suitable: two-wire fixed-speed fans and 5 V fans. Test the fail-safe once: with the firmware stopped the fan must run at full speed.
- **Ring temperature and current derating** (`src/ringtemp.h`, PC-tested; `src/ringsense.cpp`): a 10k NTC on the ring
  (Murata NCP18XH103F03RB, B 3434 K) on `J-LED-SIG` pin 5, read on GPIO3 (ADC1) through a 10k pull-up every 2 s and
  smoothed. Fan first: the ring's fan demand rises from its minimum at 45 C to 100% at 60 C, and the fan runs at the
  higher of the chip's and the ring's demands. Then current: above 60 C the ring limit falls linearly to 1500 mA at
  75 C (down at up to 400 mA/s, up at 50 mA/s); open sensor = full fan and 3000 mA, shorted = the floor. Settings on the
  LEDs tab (NVS `rtfan`, `rtstart`, `rtfull`, `rtmin`, `rtfault`). `RING_NTC_PIN` (3) is defined in `pins.h` for the
  current board, which has the sensor (`TH1` on the ring, `R65`/`R66`/`C16`/`D34` on the mainboard). On an older board, comment it out.
- **Fan control in firmware:** speed follows the smoothed chip temperature, from a minimum (25% default) at or below 60 C to full at or above 78 C; up in steps of 10 points per 2 s, down 2 points at a time.
  The Motor & fan tab's **Cooling fan** box (live) and `POST /fan` set both temperatures, the minimum and on/off (off = full speed). Defaults are guesses until measured.

## Open items

Nothing here is a known defect; these need parts in hand, or are left open on purpose.

**Bench checks:**

- **First full power-up.** The firmware has run only on a bare ESP32-S3-ETH (boot, Wi-Fi, web pages, log, docs); the motor driver, motor, ring, encoders and expander are untested. Confirm in order:
  boot log and address; TMC2209 UART lines in the log ("microsteps confirmed", "current reference is UART"); smooth start, speed-up and stop (about 1.5 s; change `bpmRampSeconds` for another feel); encoders.
- **Boot strapping:** a few power cycles with the TMC module socketed.
- **Presets and the knobs:** turn VAL (presets), EXP1 (palette) and EXP2 (speed); check that the palette overrides the preset's own, that HUE turns the colours and SAT fades them, and that a VAL press switches it to brightness and back.
- **Motor coil pairs and direction:** confirm pairs with a multimeter on a different motor. If the platter turns the wrong way, tick **Reverse motor direction** (or swap one coil's two wires).
- **Encoder step size:** `encoderCountsPerDetent = 4` suits a typical KY-040; if one click moves speed by 0.02 or 0.04 instead of 0.01, set it to 2 or 1.
- **OTA rollback:** upload a build that deliberately crashes in `setup()` and confirm it returns to the old firmware.
- **LED engine** (see [LED engine](#led-engine-the-standard-led-driver)):
  - **STEP jitter:** scope GPIO46 (STEP) at a steady speed with the ring animating (a fast sweep or segments preset) and with Art-Net streaming, against the engine off; trigger on one edge and look at the next edge's spread. Check the log line says "DMA"; without it the RMT refills run from an interrupt (on core 0, but check anyway).
  - **WS281x waveform** after `U3`: 0 about 0.3 us high, 1 about 0.6 us high, 1.2 us per bit; first LED shows the right colour (GRB) and the whole chain updates at about 100 frames a second (the **LEDs** tab).
  - **SK9822 colour order:** pick preset 1 and set the user colour to red, green and blue on the live page and change **Colour order** on the **LEDs** tab until each shows correctly (default RBG); check that a single colour draws about 3.2 A at full brightness (current field 31) and white about 4.5 A (both limits working), and that the last LED updates (end frame length).
  - **Current limit:** full white at full brightness should read about 4.5 A at the ring's supply and the page should show the limiter working; adjust **mA per LED** if the measured draw differs from the estimate.
  - **Low brightness:** turn VAL (pressed, so it is brightness) slowly from 10 % to 0 on preset 1 (a white user colour, then each primary) and while filming: no visible steps or
    flicker, and the colour should hold (an LED's colour can shift a little at the lowest current fields).
  - **Look:** no gamma correction of colours and no crossfade between presets; brightness follows a lightness curve and eases over about 60 ms. Platter-lock direction depends on how the ring faces the platter: use a negative speed if it runs backwards.
  - **Art-Net / E1.31:** from Resolume or similar, unicast and broadcast Art-Net, unicast E1.31 and multicast E1.31 (the W5500's MAC filter may drop multicast: check), and the 2.5 s fall-back to the knobs.
- **mDNS:** `liquidturntable.local` resolved from a Windows 11 PC and the rename test worked; confirm with two real turntables and check phones.

**Before ordering the boards:**

- Order **both boards at 1 oz copper** (JLCPCB's default; the 5 V harness fuse and the LED engine's 4.5 A limit make that safe, see the Hardware Overview, section 6).
- **Ring board** (`kicad_led_ring_offset/jlc_export/`): 360 SMD parts plus two THT (the connectors `J1`, `J2`), about $16-18 of components. The SK9822-A (`C5378730`) has about 18.7k at JLCPCB (enough for about 100 rings).
  Pinout if substituted: pin 1 SDI, 2 CKI, 3 GND, 4 VDD, 5 CKO, 6 SDO (KiCad's APA102 numbering). Re-check `J1` (C157996), `J2` (C157991) and `TH1` (C13564) stock at upload. See the [Hardware Overview](../HARDWARE_OVERVIEW.html#6-the-led-ring-board).
- In JLCPCB's placement preview check `C11` (+ pad is the lower one, next to `C8`) and `U1` (TSSOP-24: pin 1 at the top right, next to the `INT` corner).
- **Connector split and buffer feed:** check the `J-PWR-5V` (C20539147) and `J-PWR-12V` (C158012) footprints against the real parts, that the XH body clears `MH1` and `F1`, and `D33` orientation (cathode toward the top).
  With power on, `+5V_LED_LOGIC` (at `C10`/`C15`) should read about 4.8 V.
- **No overvoltage protection beyond `D32`:** the 5 V and 12 V inputs are different connector families and a harness is metered before it meets the board (Hardware Overview, "Harness build and test"). A 12 V wire in the 5 V plug would not be caught on the board.
  5.5 V must leave it alone. It works only against a supply that limits or trips (the RD-85A does), not a stiff 12 V source. The 5 V fuse is on the +V1 lead, so it does not see a 12 V wire in the 5 V plug.
- **`Q5`:** Siliup SP30P03NK (C41355006; 4.5 mOhm typ, up to about 0.3 W at full white). Check the land pattern against its PDFN5X6 drawing and orientation in the placement preview (pin 1 is the first source pad).
  AON6403 is a drop-in if heat matters more. Apply a reversed 5 V from a 1 A current-limited supply with the ring off and confirm nothing conducts, then check it stays cool at full white. It does not protect against 12 V on a 5 V pin.
- **Power-up with the module:** with only 5 V connected, `+5V_LED_LOGIC` (at `C10`/`C15`) should read about 4.7-4.8 V and `+3V3` (TP `3V3`) 3.3 V; with only 12 V the board should stay dark
  and the TMC2209 disabled. Run `kicad_mainboard/tools/bom_cost.py` before ordering.
- No fuses on the boards: `F1` is a soldered 2 A resettable fuse. The 5 V side's 7.5 A ATO blade fuse is in an inline holder in the harness, at the supply's +V1 terminal (Hardware Overview, "Wiring the RD-85A").
- Optionally review the high-current pours in the KiCad GUI.

**Left open on purpose:**

- **Smaller supply (revisit):** with the ring capped at 4.5 A, a Mean Well **RD-65A** (5 V 6 A / 12 V 3 A, 66 W; some shops
  list it wrongly as 8 A / 4 A) may be enough: about 4.6 A on 5 V and 1.2 A on 12 V (motor). Before switching, check that
  its 5 V trim reaches 5.1 V, its derating at the enclosure's inside temperature, its 12 V cross-regulation at a light
  12 V load, and the inlet fuse and inrush figures. It would also lower the fault current on the 5 V side.

- **Ableton Link** compiles but is on hold: it is GPLv2+ unless Ableton grants a proprietary licence, which would make the whole firmware GPL.
- **The expansion encoders** (`J-ENC-EXP1`-`3`): EXP1 picks the palette and EXP2 the effect speed; EXP3 is only logged.

## Repo layout

```
LiquidTurntable.ino                Firmware sketch: setup() and loop() only
src/                               Firmware modules (each .cpp has a header comment saying what it owns):
  state.h / state.cpp                Globals shared between modules; pins.h has every pin
  motor.cpp                          Step-timer ISR, ENN, TMC2209 bring-up and health checks
  panel.cpp / quadrature.h           Encoders (one shared ISR), main encoder button (on the expander), TCA9555 expander; quadrature.h is PC-tested
  tempo.cpp / osc.cpp                BPM bookkeeping and tap tempo / OSC handlers, /tap broadcast, core-0 task
  net.cpp                            Ethernet, Wi-Fi, mDNS naming
  web.cpp / ota.cpp / config.cpp     Web pages and /control, firmware update and boot status, persisted settings
  lighting.cpp / monitor.cpp         Presets, palette, user colour, effect speed; fan, chip temperature, loop() stall monitor
  netsetup.cpp / setupap.h           Wi-Fi setup access point (/wifi, captive portal) and the serial `wifi` command
  ledengine.cpp / leddriver.cpp      In-firmware LED engine (render task, presets on FAT, Art-Net, /leds) and its RMT/SPI drivers
  ledout.h / ledfx.h / ledpreset.h / artnet.h   LED engine logic, PC-tested; led_map.h is generated by tools/gen_led_map.py
  palstore.h                         Editable palettes: colour stops, their spread over 16 entries, /ledpalettes.txt (PC-tested)
  docs_data.h                        Generated: the HTML documents, gzipped, served at /docs/
motion.h                           Platter speed control law (PC-testable)
colour.h                           HSV/RGB/colour-temperature conversions (PC-testable)
tests/                             Unit tests (run_tests.sh / run_tests.bat)
tools/gen_led_map.py               Generates src/led_map.h from the LED ring board (--check: is it current?)
docs/                              USER_GUIDE, HARDWARE_OVERVIEW and FAQ (.md source, .html built), diagrams/, screenshots/, build_docs.py
  index.html                         Documentation index page (hand-written; edit it when a document is added or renamed)
  files/                             Copies of every file the docs link to, including the diagrams (made by sync_files.py; never edit them)
                                     sync_files.py also writes an index.html into every docs folder so a folder URL never answers Forbidden
  sync_files.py                      Refreshes docs/files/ and checks that docs/ links stay inside docs/
  BREADBOARD_GUIDE.html              Breadboard prototyping guide, generated by breadboard/build_breadboard_guide.py
  breadboard/                        Its generator, drawing toolkit and the schematic pin map (pinmap.json) it is checked against
  presets/                           Pictures of the built-in LED presets (sheet + animated WebP), made by make_preset_images.py from the firmware's own effect code
enclosure/                         Draft motor mount plate and box layout (OpenSCAD, STL, DXF, renders, notes); not built yet
  tinkercad/                         STL and SVG files of the case and mount for Tinkercad; export_stl.py regenerates and checks them
.github/workflows/ci.yml           CI: unit tests, docs up to date, firmware compiles
wifi_defaults.example.h            Template for the gitignored wifi_defaults.h
README.md / README_DETAILED.md     This short reference / the full design discussion
CHANGELOG.md                       Dated history of design and firmware changes
kicad_mainboard/
  Mainboard.kicad_sch              Schematic, source of truth (root index sheet)
  power/controller/motor/led/panel_io/testpoints.kicad_sch   The six function sheets
  Mainboard_power.kicad_sym, sym-lib-table        Project rail symbols and their registration
  Mainboard.kicad_pcb              PCB layout, routed, 0 DRC violations
  Mainboard_schematic.pdf, Mainboard_render_top.png, Mainboard_render_bottom.png   Exports and renders
  erc_report.rpt, drc_report.rpt   Latest ERC/DRC runs
  fp-lib-table, lib.pretty/        Project-local footprints
  tools/                           build_jlc_assembly.py (BOM/CPL, re-run after any layout change), bom_cost.py, add_test_points.py, route_sockets.py, microroute.py
  jlc_export/                      Gerbers, drill, BOM/CPL (SMD-only and full assembly); see its README and ASSEMBLY_COMPARE.md
kicad_led_ring_offset/
  LEDRing.kicad_sch / .kicad_pcb   Ring schematic and routed PCB (178x SK9822-A, offset/brick matrix), 0 DRC violations
  fp-lib-table, LEDRing.pretty/    Project footprint for the SK9822-A
  LEDRing_schematic.pdf, LEDRing_pcb.pdf, erc_report.rpt, drc_report.rpt
  tools/                           build_jlc_assembly.py, bom_cost.py
  jlc_export/                      Gerbers, drill, CPL, BOM, ready to order from JLCPCB
```

The ring board lives here so this repo holds every part of the physical build. Two earlier comparison layouts (square grid and true hex, never fully routed) stay in the sibling
[MegaMagicTurntable](https://github.com/scoobiekw/MegaMagicTurntable) repo.
