PRD v0.1 (baseline)

PACE — Power, Actuation, & Control Electronics

How to read this document. Everything marked MEASURED is backed by a bench run or a commit in the existing repos and is cited. Everything marked PROPOSED is a recommendation in this draft that has not been agreed. Requirement rows carry a status of Met / Partial / Open against the current hardware (PACE Racer V1R2) and firmware (v0.1.0+, branch feat/bench-campaign). Open questions are collected in §15.

1. Executive summary

PACE is a family of open, instrumented power-and-motion electronics for assistive mobility and robotics platforms. Its first and currently only production-track component is the PACE Racer V1R2, a 1 kW-class field-oriented-control (FOC) BLDC motor driver built around an ESP32-S3 and a TI DRV8353 gate driver, with three-phase low-side current sensing, an off-board magnetic encoder, hall inputs, four on-board thermal zones, and Ethernet via a WIZnet W5500 on the expansion header.

The Racer has been taken through a full characterization campaign on a magnetic-particle-brake dyno. Headline results MEASURED:

• 1049.5 W bus power at 483 rpm / 16.1 N·m, 78 % system efficiency, on the stock 0.20 V VDS over-current threshold (2026-08-27).
• 400.1 ± 0.75 rpm speed hold through a closed-loop 2 → 10 → 2 N·m torque staircase.
• Three commutation modes validated on one board: encoder-commutated (MT6701), hall-commutated (calibrated table), and sensorless (flux-linkage observer with I/f start and current-decay handoff).
• Ethernet and FOC coexist: speed regulation unchanged under saturating bidirectional traffic; RTPS/DDS telemetry delivered at up to 485 Hz against a 10 Hz target (~48× margin).

The second ecosystem node, ATOS Bridge Comms (ABC), is a plain-ESP32 Ethernet/USB-UART bridge board with a LAN8720A PHY, currently at draft-layout + bring-up stage.

This PRD (a) captures the current state of both boards, the firmware, and the bench so that the next revisions are specified against evidence rather than memory; (b) defines the ecosystem the boards belong to — the shared conventions for power, comms, safety, and telemetry that make a PACE node a PACE node; and (c) proposes a roadmap from "one validated driver" to "a family of interoperable nodes on a wheelchair-class mobility platform".

2. Background and motivation

2.1 The application

The reference application is the MEBot family of mobility-enhancement robotic wheelchairs (repos MeBot/, mebot-power-testing/). The current-generation MEBot drive path uses a commercial R-Net power module and a Teensy/Raspberry Pi control stack; the MEBot 3.0 README documents an in-progress design change "switching the rnet module to in-house-design … controller for controlling the main wheels". PACE is that in-house design, generalized.

Concretely, the drive requirement that fell out of MEBot is: a wheelchair hub-motor drive (NineBot S class, 15 pole pairs, 48 V) that can be commanded over a real network, instrumented at control-loop rate, and characterized on a dyno — none of which the R-Net module allows.

2.2 Why build rather than buy

2.3 What has been proven so far

The campaign timeline, reconstructed from git history and bench notes:

3. Vision and ecosystem definition

3.1 Vision statement

PACE is the electronics layer that lets an assistive-mobility platform be a robot. Every PACE node speaks the same network, reports the same telemetry, obeys the same safety envelope, and can be characterized on the same bench — so a wheelchair, an exoskeleton joint, or a research rig can be assembled from nodes rather than re-engineered each time.

3.2 The three pillars

The acronym is the product taxonomy. Each pillar is a class of node with a shared contract (§3.3).

3.3 What makes a node a PACE node PROPOSED

These are the ecosystem-level contracts. They are what this PRD adds beyond the individual board specs. Each is expanded into requirements in §12.

1. Common bus voltage class: 48 V nominal (36–54 V operating) for actuation-class nodes; 5 V / 3.3 V logic derived locally. Bench today assumes exactly 48 V.
2. Common network: Ethernet (100BASE-TX) as the primary command/telemetry fabric; RTPS/DDS as the wire protocol so ROS 2 hosts subscribe natively. UDP/CSV and the USB console remain as bench/debug paths.
3. Common telemetry schema: every node publishes a NodeStatus topic (identity, uptime, faults, temperatures) and a node-class topic (for Racer: the FOC snapshot — mode, id, iq, iqref, vd, vq, aerr, rpm_*, flux, t0–t3).
4. Common safety envelope: (a) layered protection — software plausibility/slew filters that never trip, a software soft-trip that unloads gently, and a hardware latch as last resort; (b) "gentle by default" — no fault response may itself inject a torque or current transient larger than the fault it is responding to; (c) a network-independent local thermal guard.
5. Common bring-up contract: every board ships with a bringup firmware that prints a pass/warn/fail CSV, and a README with the pin map.
6. Common tooling: every node is characterizable on the PACE bench (§10) through the same bench_mcp interface.
7. Common identity: MAC derived from the MCU eFuse (W5500 has no burned MAC); hostname pace-<class>-<serial> PROPOSED.

3.4 Naming convention PROPOSED

PACE <Name> V<major>R<rev> — e.g. PACE Racer V1R2. Major = electrical architecture change; Rev = layout/BOM iteration on the same architecture. Firmware tags follow semver (v0.1.0 today) and record the hardware revision they were validated on.

4. Goals and non-goals

4.1 Goals

4.2 Non-goals (for this PRD cycle)

• Medical-device regulatory submission (IEC 60601, ISO 7176-14). PACE is a research/pre-production platform; §17 lists what a later cycle would need.
• Consumer-grade enclosure, ingress protection, or connectorization.
• Wireless (Wi-Fi/BLE) as a control path. The ESP32-S3 radio is available but out of scope for control; it may be used for bench convenience only.
• Multi-axis synchronization / EtherCAT-class determinism. DDS best-effort at hundreds of Hz is the target.
• Battery chemistry / BMS design (belongs to the future P-pillar).

5. Users and personas

6. Ecosystem architecture

6.1 Reference topology PROPOSED, built from current parts

                 ┌────────────────────────────────────────────┐
                 │  Host (ROS 2 / Mac / Pi)                    │
                 │  - DDS participant(s)                       │
                 │  - telem_sub, monitor.py, bench_mcp          │
                 └───────────────┬────────────────────────────┘
                                 │ 100BASE-TX
                 ┌───────────────┴────────────────────────────┐
                 │  Ethernet fabric (switch or point-to-point) │
                 └──┬───────────────┬───────────────┬─────────┘
                    │               │               │
        ┌───────────┴───┐   ┌───────┴───────┐   ┌───┴──────────────┐
        │ PACE Racer #L │   │ PACE Racer #R │   │ ATOS Bridge Comms│
        │ (A-pillar)    │   │ (A-pillar)    │   │ (C-pillar)       │
        │ ESP32-S3      │   │ ESP32-S3      │   │ ESP32 + LAN8720A │
        │ DRV8353       │   │ DRV8353       │   │ UART/USB bridge  │
        │ W5500 (SPI)   │   │ W5500 (SPI)   │   │ RMII Ethernet    │
        └──┬────┬───┬───┘   └──┬────┬───┬───┘   └───┬──────────────┘
           │    │   │          │    │   │           │ UART
        motor enc halls     motor enc halls     legacy / R-Net / Teensy
           │                   │
        ┌──┴───────────────────┴──┐
        │ 48 V bus (P-pillar TBD: │
        │ today = bench PSU)      │
        └─────────────────────────┘

6.2 Layering

6.3 Execution model on a Racer node MEASURED

• Sampling ISR — CPU0, fired at MCPWM timer peak (TEP = the null vector on this board), one ADC conversion per 50 µs PWM period (20 kHz), phases A/B alternating, C reconstructed. Integer-only. Runs the glitch-filter stack and the soft-trip check, then notifies the FOC task.
• FOC task — CPU1, high priority, woken per sample. Clarke → Park → 2× PI → inverse Park → SVPWM → set_pwm; also the observer, handoff state machine, speed loop; publishes a seqlock snapshot.
• Stream task — CPU0, 10 Hz CSV, DRV fault poll (5 s), trip reports, Hi-Z coast handshake.
• Network tasks — lwIP, RTPS writer(s), UDP sink. lwIP must not be pinned to CPU0.
• Console — CPU0, line-based over USB-serial-JTAG.

Design rules that fell out of the campaign and now bind the ecosystem:

1. MCPWM ISR priority 2 (not 0, not 3) — 0 loses to SPI/I2C/Ethernet and produces late samples; 3 starves console, telemetry and watchdog while driving.
2. 32 KB instruction cache + FOC task in IRAM — 2.2–3.0× UDP transmit ceiling.
3. Telemetry task must have a real priority; at priority 0 it starves ~25 % under saturating traffic.
4. Never toggle a debug GPIO on an ADC-adjacent pin of the unit being sampled.

7. Component: PACE Racer V1R2 hardware

7.1 Identity

7.2 Interfaces MEASURED — from BSP and bench notes

7.3 Electrical envelope MEASURED

7.4 Hardware findings that must feed V1R3 / V2 MEASURED → PROPOSED

8. Component: PACE Racer firmware

8.1 Stack MEASURED

• ESP-IDF v6.0.0, C++ with the espp component set (bldc_driver, bldc_motor, mt6701, ethernet, cli, pid, filters, task, timer, …). espp v1.2.0 provides the RTPS engine.
• Repo layout: main/ (board-level demo app), components/pace-racer-board/ (BSP + apps: bringup, example, ethernet, sensorless, halls-sensorless), components/drv8353/, components/lm75adp/, data-reports/.
• Tooling: clang-format via pre-commit, GitHub Actions builds main + examples.
• Version v0.1.0 (+30 commits at the RTPS rerun).

8.2 Feature inventory

8.3 Control modes and state machine MEASURED

All exits — stop, soft trip, flux fail-safe, thermal guard, torque-ceiling revert — go through STOPPING → Hi-Z coast. No braking, no disarm on the software path.

8.4 Firmware requirements delta PROPOSED

See §12 F-series. The principal new work is command ingress, the ecosystem schema, persistent calibration, and a host-facing motion API with watchdog semantics.

9. Component: ATOS Bridge Comms (ABC)

9.1 Identity MEASURED — from KiCad + bring-up READMEs

RMII pin map: REF_CLK GPIO0, MDC 23, MDIO 18, PHY nRST 5, TX_EN/TXD0/TXD1 21/19/22, RXD0/RXD1/CRS_DV 25/26/27.

9.2 Role in the ecosystem PROPOSED

ABC is the bridge between the PACE Ethernet fabric and legacy or serial-only equipment — the MEBot Teensy base, an R-Net controller during migration, a joystick, or a host that only has USB. It should:

1. Present itself on the fabric as a PACE node (NodeStatus, DDS discovery).
2. Tunnel one or more UARTs over UDP/DDS with framing and timestamps.
3. Act as a DHCP server / configuration portal for point-to-point bench links (already does: 192.168.4.1, UDP echo on 3333).
4. Optionally host the network supervisor role: heartbeat monitoring of Racers, e-stop broadcast.

"ATOS" expansion and the exact upstream system it bridges are not recorded in the repos — see §17.

10. Component: Bench, dyno, and characterization tooling

10.1 The stand MEASURED

10.2 Software MEASURED

• bench_lib.py — Board / Psu / Brake / Scope abstractions, ack() with retries, usb_replug(), vm_recover.
• bench_mcp.py — MCP server: bench_status, bench_up/down/arm, bench_brake_set/off, bench_psu_iset, bench_bus_read, bench_torque_read, bench_telemetry, bench_console, bench_usb_replug, bench_vm_recover. Setup + measure only; motion stays in watchdog scripts.
• Campaign scripts: hall recal, power ladder, torque servo, fig4_heatsink.py, fig6_edge.py, fig6_hold.py.
• Reports: bench_report.py → report/figures.html (§1 ident, §2 speed regulation, §3 torque linearity, §4 thermal, §5/6 power & efficiency, §7 the 1 kW chase, §8 load staircase); compile_report.py for the hall campaign; per-run report.md in data-reports/logs/.

10.3 Bench requirements for the ecosystem PROPOSED

• Every PACE node type gets a bench_* profile in bench_mcp (ABC: link/echo/latency; future P-nodes: load-step, ripple — the mebot-power-testing ripple/PSD scripts are the seed).
• The speed campaign (500 rpm loaded ladder, endurance dwell to FET plateau) planned in the bench README is the next Racer dataset; it partially ran on 08-26/27.
• A second Racer on the stand (back-to-back motor/generator) would let regen and bus-transient behaviour be characterized — a P-pillar prerequisite.

11. Component: Host software and telemetry

11.1 Today MEASURED

11.2 Wire facts that constrain the design MEASURED

• RTPS 2.2 on the wire, source port 7400, vendor ID 0d25, SPDP announcement 204 B, GUID prefix MAC-derived. Discovery works over a point-to-point cable (multicast is not filtered without a switch).
• Delivery collapses to ~0 above ~485 Hz while pub_fail still reports 0 — publishers cannot detect it; the host must.
• Inbound flood disturbs by packet rate, not bandwidth: RX saturates ~1247 pps at 64 B; late% rises to ~4 % at bidirectional saturation but coalesce stays 1.00.
• micro-ROS on ESP32 speaks Micro XRCE-DDS (needs an Agent), not RTPS — the espp engine was chosen to avoid that.

11.3 Host requirements PROPOSED

• Publish IDL for NodeStatus and RacerTelemetry / RacerCommand; provide a ROS 2 package that maps them to standard message types.
• A single pace-cli that wraps console commands over Ethernet as well as USB so the console wedge is not a blocker.
• A fleet dashboard (per-node status, faults, temperatures) is nice-to-have for the MEBot integration.

12. Requirements register

Status is against Racer V1R2 + current firmware unless noted. Evidence column cites the artifact.

12.1 Ecosystem (E)

12.2 Racer hardware (H)

12.3 Racer firmware (F)

12.4 ABC (B)

12.5 Bench and tooling (T)

12.6 Safety, compliance, and documentation (S)

13. Measured performance baseline

All values MEASURED on Racer V1R2, 48 V, NineBot S hub motor, unless noted.

13.1 Power and motion

13.2 Control-loop integrity

13.3 Network

13.4 Motor identification (for reuse as fixtures)

R = 0.166 Ω/phase (0.332 line-line fit; DMM 0.323), L ≈ 336–395 µH, λpm = 0.026 Wb, Kt = 0.60–0.62 N·m/A, J ≈ 0.106 kg·m², 15 pole pairs. Current-loop gains kp = 0.0568, ki = 54.5 (169 rad/s bandwidth). Known-good encoder offset ≈ 352.5° (mount-dependent).

14. Known issues and technical-debt register

15. Roadmap

15.1 Now → next quarter (Racer hardening) PROPOSED

15.2 PACE Racer V1R3 (layout iteration, same architecture) PROPOSED

• Halls off ADC1 pins with conditioning (H-08).
• Secondary UART console header (H-09).
• Designed-in heatsink / chassis thermal interface (H-06).
• Ethernet still via expansion, but dedicated SPI host if pins allow.
• Calibration EEPROM or NVS convention (H-10).
• Connector spec for wheelchair integration (H-13).

15.3 PACE Racer V2 (architecture change) PROPOSED

• On-board Ethernet (W5500 dedicated SPI or RMII PHY) (H-07).
• Current sensing: simultaneous-sampling external ADC or DRV8353 CSA with S/H, so sampling is decoupled from switching-edge timing (§7.4).
• VM pre-charge / disconnect under firmware control (H-11).
• Dual-motor variant evaluated (one ESP32-S3, two DRV8353) — a wheelchair needs two drives; the RTPS writer budget (~114 µs/writer) and the ISR budget say one MCU can plausibly host two 20 kHz loops only if sampling moves off the SAR ADC. Decision needed (§17).

15.4 Ecosystem PROPOSED

16. Risks

17. Open questions

1. What does "ATOS" stand for, and what does ABC bridge to first — the MEBot Teensy base, an R-Net controller, or a joystick? This sets B-03's framing and baud requirements.
2. Dual-motor architecture: two Racers per chair (works today) vs one V2 board with two drives? Cost/wiring vs the ADC/ISR budget.
3. Ecosystem schema: adopt ROS 2 standard messages where they fit (sensor_msgs/JointState, diagnostic_msgs) or define PACE IDL and map? Recommendation: PACE IDL as the wire truth, ROS 2 mapping package on top.
4. Bus operating range: is 48 V exact, or must Racer operate down to a discharged pack (≈ 36–40 V) and up to charge voltage (≈ 54 V)? Observer kBusVoltage must track the real bus either way — do we add bus-voltage sensing to firmware as a requirement?
5. Heartbeat-loss stop bound: 200 ms is proposed; the clinical/handling requirement should set it.
6. Regen policy: allow regen into the pack (needs P-node/BMS coordination) or dissipate/clamp on the Racer?
7. Encoder strategy at speed: keep MT6701 (low-speed specialist) + halls at speed, or move to a faster interface in V2?
8. Licensing for hardware: firmware is MIT; is pace-racer-hardware CERN-OHL or similar?
9. Who are the external users in the next 12 months (labs, collaborators), and does that change the priority of OTA and documentation?

18. Glossary

19. References

Local paths are relative to /Users/alxchunlin/code-stuff/atdev/.