README.md
# F1C100S Linux NEMA 17 stepper controller
> RELEASE 0.4.56: software-adjustable current, based on published 0.4.55.
> Nominal common peak current: 0β396 mA/phase, configurable while disarmed.
> New PCB and matching MCU firmware must be used together; R_ISET_210 stays DNP.
> The 42.3 mm four-layer outline, mounts, USB locations, top bulk capacitor and
> motor/cable assembly are unchanged. 155 warnings remain visible: 151 inherited
> plus four audited whole-net width diagnostics; dedicated new routes are 0.15 mm.
> Not fabrication-qualified. Frozen pre-publication evidence retains its original
> local/unpublished labels; registry publication and the publication receipt
> establish the uploaded version.
A 42.3 Γ 42.3 mm, four-layer, double-sided board combining Linux networking
with an independent real-time stepper drive. It targets the StepperOnline
17HS13-0404S1: a 42 mm NEMA 17 motor rated 0.40 A/phase, not arbitrary motors
that happen to share the same frame.
## Status
### Release 0.4.56: software-adjustable current
MCP4725 on the existing motion-MCU I2C bus supplies the DRV8825 reference.
Boot zero/readback, disarmed-only configuration, fault shutdown and settling
interlocks are implemented and tested. No EEPROM writes are used. Reset requests
396 mA; zero cannot arm. See firmware/PROTOCOL.md for the new commands.
This does not extend the motor-current ceiling or qualify a 1.5 A NEMA17.
All 24 validation stages pass; 29 board and 32 module tests pass. Read
reports/software-current-acceptance.json and verification.json for qualification
gaps, including bench calibration and actual rear-motor fastening.
### Historical release 0.4.55: clean schematic sheets
The overview explains power, Linux, independent motion timing, the stepper
drive, telemetry and the two USB roles. Each circuit sheet uses the same title,
page footer, local functional headings and short notes. Clock/reset support is
beside the processor unit it serves; regulator input/output capacitors read
left to right; coil-current channels are matched; Ethernet support and supply
banks are grouped. Detached explanatory cards have been removed.
Native symbols, ports and schematic wires are generated normally. A strict
regression test compares **every** non-schematic hardware/electrical record
with the frozen 0.4.54 circuit in `baseline/circuit.json`. The PCB layout and
routing were not changed. All prior fabrication/first-article qualifications
below remain open; inherited warnings are not hidden or cleared by this work.
### Historical changes
### Release 0.4.54: top-side bulk capacitor and explained schematic
The schematic now has a "Start Here" system overview and explanatory section
cards on all twelve circuit sheets. The four reported style issues are fixed:
horizontal fuse/diode alignment, USB-gate box width and padding, and centering
the Ethernet crystal between its load capacitors. Check with
`npm run check:schematic-style:current`; this pins the website-compatible
analysis engine to 0.0.82 rather than the old analyzer embedded in this CLI.
`C_VM_BULK` retains its 22 Β΅F / 50 V CA55-D050M226TE100 selection and polarity,
but is assembled on TOP. The shorter SMB TVS occupies its former underside
area. The blocking diode, two nearby current-filter passives, temperature-alert
resistor, debug-bias resistor and optional PD-voltage resistor have explicit
local placement changes.
The 42.3 mm outline, four mounting holes, both USB-C ports, Ethernet, motor
connector, driver, complete motor/cable assembly, BOM, source nets and firmware
are unchanged. The prior long ADC-detour experiment was rejected, not installed.
The normal build replays the fully imported copper and retains the placement
signature guard. Fresh emitted-copper snapshots are
`routing/bulk-top-emitted-physical.json` and `routing/physical-copper.json`.
The immutable `routing/review-emitted-physical.json` remains the actual baseline
for comparison, not the current board. Run `bun scripts/validate-rishabh-review.mjs`
for the full regression suite. Current checks retain all 151 inherited native
warnings; no errors or additional warnings are suppressed.
The low-current regulator feed was rerouted; its DC drop and switching-noise
behavior still belong in first-article measurements. Software continuity/DRC
checks do not qualify regulator transients, analog accuracy or EMC.
### Release 0.4.53: both USB-C ports on top
Both unchanged TYPE-C-31-M-12 connectors now occupy the top face at the north
edge, at the original 14 mm center spacing. The 42.3 mm square, four mounting
holes, motor/cable assembly, driver position, schematic and electrical
connections remain unchanged. Seven small passives were moved to the
underside; the bulk USB-rail capacitor is in the freed connector area.
The power-port contact escapes are 0.35 mm and join real 0.80 mm top-side
trunks. The visible D/PD labels are now on top.
The historical 0.4.53 evidence is in `reports/usb-top-record-regression.json`,
`reports/usb-top-protected-copper.json`, and `reports/usb-top-validation.json`.
Release `0.4.53` contains this revision; website-build verification is recorded separately in the publication receipt. Previous reports remain historical and
must not be mistaken for checks of this revision's circuit hash.
The fabrication-qualification gaps described below are not cleared by this
placement change.
Previous release `0.4.52` improved on `0.4.51` by restoring 96 missing rounded-lead solder-paste apertures and removing paste from four bare SWD test pads. All electrical, copper, placement, mounting, schematic and CAD records are unchanged.
**Not fabrication-approved.** The included manufacturing process specifies paid four-layer epoxy-filled/copper-capped vias; it is not fabricator acceptance. Thermal-pad stencil/reflow, buck feedback layout, USB/Ethernet stackup/return paths, actual motor rear fastening/harness and first-article testing remain open.
The fresh stock check covers five boards; inventory is not reserved. Current evidence is in `reports/fab-stencil-regression.json`, `reports/stencil-artwork-audit.json` and `reports/stencil-prepush-comparison.json`. Earlier reports retain their original circuit hashes and local/unpushed labels as history; publication metadata establishes the uploaded version.
## Features
- F1C100S runs Linux; W5500 supplies SPI Ethernet. Linux sends motion commands,
not individual STEP pulses.
- STM32G030 generates timed STEP/DIR, handles watchdog/local faults, and can
be programmed by the F1C100S using ROM-UART boot/reset control.
- DRV8825 is the actual two-phase bipolar stepper driver. An MCP4725 lets the
motion MCU select **0β396 mA nominal peak/phase**, default 396 mA, while
disarmed. Both phases share this limit. `R_ISET_210` must remain DNP; fitting
it invalidates the software's nominal-current conversion.
- HUSB238A requests **15 V / 3 A USB-PD** by default; fitting the DNP 13.3 kΞ©
`R_PD_12V` option selects 12 V. A PD request is not a qualified PCB current
rating. A 5 V-only source is unsuitable for operating this motor.
- A filtered divider measures raw PD voltage. The MCU also reads a
level-shifted PD gate-valid indication: a contract/switch status proxy, not
an independent measurement of downstream rail power-good.
- Two inline 0.30 Ξ© shunts and INA241B1 amplifiers provide signed coil-current
telemetry, separately from the DRV8825 regulation shunts. Nominal scaling is
**3 V/A**, centered at **VDDA/2** (about 1.65 V). These filtered samples are
not calibrated RMS readings or a replacement protection loop.
- WS2812B addressable RGB status LED with AHCT buffer, TMP102 temperature
sensor, and MOSFET-driven magnetic buzzer are controlled by the motion MCU.
The unchanged USB-C connector types share the north edge, both on top, at 14 mm center spacing. Simultaneous fit of actual cable overmoulds is not yet physically verified. `J_USB_PWR` is power-only. `J_USB_DATA` supports Linux USB gadget
and ROM FEL. Host VBUS supplies attach-detection/ESD bias, **not** the system
rail. A TS3USB31E hardware data gate disconnects USB when host VBUS is absent,
including during ROM FEL. USB attach timing and signal integrity still need
bench verification. There are no SPI/IΒ²C expansion headers; these buses are
used internally. Compact SWD pads are for factory/recovery access.
## User workflow
1. Inspect the unpowered board and check shorts. Program the matching STM32
firmware using the documented factory boot configuration, without a motor.
2. Apply a suitable PD source. Measure negotiated voltage, logic rails and
DRV8825 VREF; verify the default-disabled bridge and PD-loss hardware gate.
3. Install a complete F1C100S Linux image/application. The device-tree fragment
and example client alone are **not** a complete bootable product.
4. Verify coil pairs and harness polarity; connect the motor. Test low-speed
motion and missed-heartbeat, driver-fault and temperature shutdown with a
current-limited supply and the motor safely restrained.
5. Calibrate both current channels and test switching noise, USB, Ethernet,
power transients and temperatures before regular use.
Firmware is experimental, not safety-certified. It requires explicit arm,
checks PD voltage/status and disables/latches the drive on relevant faults.
The read-only `--current` command does not arm, move or refresh the watchdog.
Consult the protocol and validation files for exact behavior and procedures.
## Harness and mounting
`J_MOTOR` is **JST-PH, 2.00 mm pitch**:
| Pin | Connection | 17HS13-0404S1 lead |
|---:|---|---|
| 1 | B+ | Red |
| 2 | Bβ | Blue |
| 3 | Aβ | Green |
| 4 | A+ | Black |
Confirm coil pairs with an ohmmeter, not just colors. The current motor listing
describes a **2.54 mm harness connector**, which does not directly mate with
this PCB. Use a verified adapter or PH pigtail with four insulated splices,
as described in `motor-harness.md`. The rendered cable illustrates an adapted
harness; it does not prove the supplied cable directly plugs in.
Four 3.5 mm holes use a 31 mm square pattern. Keepouts accommodate nominal
**5.5 mm ISO 4762 M3 socket heads, no washers**, and nonconductive motor-side
spacers up to 5 mm OD. The modeled motor-to-PCB gap is 6 mm. Motor and PCB
remain square-aligned, with the cable outlet facing J_MOTOR. The hole pattern
does **not** establish usable rear threads on the actual motor. Check its
rear endbell, engagement depth and required bolt length. Reuse of supplied
screws is **not confirmed**; spacers/longer through-bolts may be needed.
## Fabrication and checks
All real vias are **0.30 mm drill / 0.45 mm pad, L1βL4 through-vias**; none
are blind or buried. Board thickness is explicitly 1.6 mm. The motor-area VM
bridge is 0.80 mm on outer layers; winding/shunt current paths are at least
0.30 mm on outer layers. Fine-pitch breakouts have separate constraints.
These geometric checks do not qualify RMS current or temperature rise.
Ordinary SMT-land/drill intersections are cleared. The 17 intentional
thermal-pad/drill records still require approved stencil/opposite-face
processing. `manufacturing-process.json` now specifies epoxy-filled,
copper-capped through vias on both faces (a paid four-layer option), with
explicit order remarks. That specification is not fabricator acceptance.
Tenting alone does not establish filled/capped via-in-pad. Rounded signal
lands have explicit paste artwork; stencil thickness, thermal-pad paste
volume and the double-sided reflow process still require assembler CAM review.
Warnings remain visible and need individual assessment. Local CLI style
checks are not a fresh website AI schematic analysis.
Run `npm run build`, `npm run typecheck`, `npm run check:schematic-style`,
`npm run check:shorts`, `npm run check:continuity`, independent copper/drill,
Kelvin/mechanical/solder audits, board/module/firmware tests, fresh JLCPCB
stock/catalog checks and `npm run verify`. Assembly export deliberately
fails closed while stock or process approval is missing; do not weaken it.
Install `requirements-routing.txt` in the audit Python environment. After a
fresh Gerber preview export, run `scripts/audit-stencil-artwork.py`; it checks
every populated SMT land and independently parses the restored rounded lead
apertures from the actual paste Gerbers. It does not approve paste volume or
the assembly process. `reports/fab-stencil-regression.json` records the local
stencil fix and the unchanged electrical/mechanical baseline.
## Supporting files
On the website, open the [Files tab](https://tscircuit.com/shibosoftwaredev/f1c100s-linux-nema17-stepper-controller#files)
and select these paths. Relative Markdown file links do not reliably resolve
as package files on the website.
- `motor-harness.md`: cable, termination and polarity checks.
- `hardware-validation.md`: first-article measurements and acceptance tests.
- `firmware/PROTOCOL.md`: Linux-to-MCU protocol.
- `firmware/stm32/README.md`: firmware build, flashing and boot options.
- `firmware/motor-control.py`: example Linux client.
- `reports/round12-fix-status.json`: current local review evidence.
## Local software-current revision β not published
This isolated work adds MCP4725 current control on the motion MCU's existing
I2C bus. `--set-current-ma 200` configures a nominal 200 mA peak/phase while
disarmed without moving; `--current-ma 300` selects the limit for a move.
The supported nominal range is 0β396 mA, not a higher-current motor upgrade.
Read `firmware/PROTOCOL.md` for the mandatory DAC readback/settling interlock,
fault behavior and matching hardware/firmware requirement. `R_ISET_210` stays DNP.
The published baseline remains v0.4.55. Historical publication receipts above
describe that baseline, not this new hardware. Use the matched new PCB and MCU
firmware together; flashing this firmware alone does not add a DAC to an old
board. Settings are volatile; reset restores the requested 396 mA default.
Run `scripts/validate-software-current.mjs` with `ROUTING_PYTHON` set to the
audit environment. It checks actual emitted copper, original source/placement/
copper contracts, all-layer shorts, drills, schematic style, stock/catalog,
solder/paste artwork and tests. `reports/software-current-acceptance.json`
is the final hash-bound receipt.
Native warnings remain visible: 151 inherited plus four new whole-net width
diagnostics. Those four select old 0.12 mm rail/ground paths; every dedicated
DAC supply/address/bypass path is independently verified at 0.15 mm. No native
check or requested width was disabled. Physical hardware tests/current calibration,
thermal/stencil/reflow approval, signal integrity and actual motor fastening
still require qualification. This is not fabrication approval.
