Nucleus
The firmware for the OSSM Flagship PCB. It runs the Valence hub, plans the motion and generates the quadrature signal that steers the servo drive.
Built on ESP-IDF. Apache-2.0.
Status
Runs on an ESP32-P4 dev board and bench rigs. The Flagship PCB is still in design (see Hardware). No release yet; when there is one, it will be on Downloads.
Motion timing
- 128msPlan strip
The planner, Kinetic², keeps the next 128 positions in mm, one per 1 ms tick, so a planner solve of up to 128 ms never leaves the output without a plan.
- 4msLease
If the lease is not renewed for 4 ms, the LP core parks itself and counts a lapse. A stalled main core can keep the carriage moving at its last speed for 4 ms at most.
- 128nsEdge spread
Every quadrature edge lands on a 125 ns grid, so timing error stays inside one step and does not add up over a stroke.
- 900msWi-Fi buffer
The client sends motion up to the horizon minus 100 ms ahead, so a shorter Wi-Fi stall doesn't reach the motion.
Details
The planner keeps a strip of the next 128 positions in mm, one per 1 ms tick. Past the end of the strip the steer holds the last position and counts a planner stall.
Every 1 ms tick the steer reads the strip and gives the LP core three things: a velocity, a fence and a lease renewal. The fence is a pair of edge counts that no edge may cross. The lease is a 4 ms timer.
Wi-Fi stalls are covered separately: the client sends segments up to the schedule horizon minus 100 ms ahead, which is 900 ms at the factory horizon of 1000 ms.
The LP core emits A/B quadrature edges, and its signed edge count is the machine's position. Its poll loop is 5 cycles, 125 ns at 40 MHz, and every edge lands on that grid. Measured at a prime edge rate on a Rigol DHO4204, the spread is 128 ns peak to peak and the rounding does not accumulate.
The LP core runs from its own SRAM. While the main cores erased and wrote flash with the cache off, a scope saw 2,156 transitions and 0 illegal ones, so saving settings does not glitch the motor signal.
Chips
- ESP32-P4
Runs everything we wrote: the Valence hub, the WebSocket server, policy and motion.
- ESP32-C6
A Wi-Fi and BLE radio on an SDIO link, running Espressif's stock
esp_hostedimage, so there is no radio firmware to build or flash. You only flash the P4. - CH32V003
A board monitor that runs its own small firmware, programmed by the P4 and carried inside the Nucleus update, so one update covers both chips.
Safety
- Motion control
The only code allowed to command motion. Manual input, scripts, patterns and network sessions submit intents to it, so every safety check lives in one place: homed, commissioned, pause, e-stop, and a clamp to the rail window.
- E-stop
The E-stop input is read first on every 10 ms pass and latches an e-stop in the hub. On the PCB, the same button also cuts motor power in hardware, so an e-stop does not depend on the firmware.
Pairing button Draft
- Press PAIR
Opens a 120 s pairing window.
- Double press
Approves the one pending request for configure access.
- Hold 5 s
Drops every paired client to watch access and ends their sessions.
- Hold while powering on
Config mode: BLE and USB serial only, no Wi-Fi, and the first client to connect gets configure access. Use it to set up a PCB that has no network.
These gestures are drafts and may change. The access tiers are in the Valence docs.
Firmware updates and rollback
An HTTP POST to /ota on port 80, with a token, writes the new image to the idle slot and reboots. The new image is on trial: if its hub task hangs before it proves itself, the watchdog resets the PCB and the bootloader brings back the previous image.
Related
Nucleus is the hub in Valence: it holds the machine's state, and clients such as Phosphor send intents that it clamps and echoes. It plans motion with Kinetic and runs on the Flagship PCB. The same hub code compiles to WebAssembly and runs inside Phosphor as Neutrino, so you can try it without a PCB; see Demos. The diagrams show the whole system, and Components lists every part.
Repo · Valence docs · Hardware · Kinetic · Diagrams · Downloads