Circuit-to-code map¶

Which part of the rig each piece of this firmware talks to, through which board connector and schematic block, over which nets and GPIOs, and which protocol verbs and events the host sees for it. Generated by tools/circuit_code_map.py from the rig's component registry (atlas/components.yaml) and the board's records (kicad/board-manifest.yaml, kicad/board.yaml); do not edit, change those and run the script. GPIO numbers are the board's as built at v1.0 (src/BoardPins.hpp carries the same numbers with their history).

By part¶

Spur gear pair¶

Driving gear on the motor shaft, driven gear on the lever axis. The mirrored station has its own driven gear. The gear ratio is the number the firmware's angle scaling depends on.


Firmware	`src/Conversions.hpp`
Note	gear ratio and microsteps per lever degree live here

Stepper motor¶

The motor that presents, parks and homes the lever through the gear pair. Rated 0.6 A per phase; the firmware runs it below that.


Board connector	`J1102`
Schematic block	`tmc5130` in sheet `motor_encoder_switch`
Nets and GPIOs	`TMC_SPI_CIPO` GP4, `TMC_SPI_COPI` GP7, `TMC_SPI_SCK` GP6, `~{TMC_CS}` GP2
Firmware	`src/TmcMotion.hpp`, `src/MotionSetup.hpp`, `src/TmcSpi.hpp`, `src/TmcRegisters.hpp`
Protocol	`HOME`, `MOVETO`, `ARM`, `STOP`, `ev TARGET`, `ev HOMED`
Proved by	`examples/TMC5130Communication`, `examples/MotionAndHoming`, `docs/motion-bringup.md`

Lever-axis encoder¶

Optical kit encoder. Its A and B channels reach the board's encoder input and are counted by the TMC5130A, not by the RP2040; the firmware reads the count over SPI.


Board connector	`J1103`
Schematic block	`quadrature_encoder_input_5v_sn74lvc2g17` in sheet `motor_encoder_switch`
Firmware	`src/TmcMotion.hpp`, `src/Conversions.hpp`
Protocol	`STATUS (angle)`, `ev TARGET`
Proved by	`examples/MotionAndHoming`, `docs/motion-bringup.md`

Limit switch¶

Subminiature basic switch with a lever actuator at the positive end of travel. The firmware homes against it and uses it as the hardware stop for negative motion through the driver's reference input.


Board connector	`J1601`
Schematic block	`limit_switch_debounced_input_vertical` in sheet `motor_encoder_switch`
Firmware	`src/MotionSetup.hpp`, `src/TmcMotion.hpp`
Protocol	`HOME`, `ev HOMED`
Proved by	`examples/MotionAndHoming`

Magnetic particle brake¶

On the lever axis behind the gear. The board's current sink drives its coil from 0 to about 49 mA to set the resistance the mouse feels while the lever is released.


Board connector	`J1801`
Schematic block	`brake_current_sink_0_49ma_dac80501` in sheet `brake_torque_sensor`
Nets and GPIOs	`BRAKE_ISENSE` GP27, `DAC_SCL` GP17, `DAC_SDA` GP16, `~{BRAKE_FAULT}` GP13
Firmware	`src/BrakeTorqueHw.hpp`, `src/BrakeTorqueBackend.hpp`, `src/DAC80501Device.hpp`
Protocol	`BRAKE`, `ev RELEASED`, `~BRAKE_FAULT in the fault mask`
Proved by	`examples/BrakeAndTorque`, `docs/brake-torque-bringup.md`

Reaction torque sensor¶

350 ohm bridge, 1.5 mV/V, 5 in-oz, at the rear of the lever axis. The board excites it, amplifies it, samples it at 1 kHz and puts a copy on the torque BNC. The left station reads a pull negative where the right reads positive.


Board connector	`J2001`
Schematic block	`torque_bridge_0_3v3_ina821` in sheet `brake_torque_sensor`
Nets and GPIOs	`TQ_SPI_CIPO` GP12, `TQ_SPI_COPI` GP11, `TQ_SPI_SCK` GP10, `TQ_CAL_EN` GP18, `TQ_CONVST_CS` GP15
Firmware	`src/BrakeTorqueHw.hpp`, `src/ADS8689Device.hpp`, `src/BoardCalibration.hpp`
Protocol	`TQ`, `STATUS (torque)`, `ev TOUCH`, `ev PULL / PUSH`
Proved by	`examples/BrakeAndTorque`, `docs/brake-torque-bringup.md`

By firmware file¶

File	Parts it touches
`src/ADS8689Device.hpp`	Reaction torque sensor
`src/BoardCalibration.hpp`	Reaction torque sensor
`src/BrakeTorqueBackend.hpp`	Magnetic particle brake
`src/BrakeTorqueHw.hpp`	Magnetic particle brake, Reaction torque sensor
`src/Conversions.hpp`	Spur gear pair, Lever-axis encoder
`src/DAC80501Device.hpp`	Magnetic particle brake
`src/MotionSetup.hpp`	Stepper motor, Limit switch
`src/TmcMotion.hpp`	Stepper motor, Lever-axis encoder, Limit switch
`src/TmcRegisters.hpp`	Stepper motor
`src/TmcSpi.hpp`	Stepper motor

Files that touch no rig part and are not listed: the protocol codec and state machine (src/Protocol.hpp, src/ProtocolBoard.hpp), the power sequencing (src/PowerSequence.hpp, src/SafeState.hpp), the self test and the pyControl link; the architecture page places them.