MustafaMulla29/rp2040-bldc-motor-controller-new

docs/connectors-and-firmware.md

# Connections and firmware

| Part | Connection / function |
|---|---|
| J19 PWR | USB-C PD source advertising the selected 5/9/15/20 V at ≥2 A; board requests 2 A, defaults to 9 V |
| J1 DATA | Computer USB data cable; communication and 5 V logic power only |
| J10/J11/J12 | U/V/W motor phases, each via one purchased 3.5 mm female / 4 mm male rigid adapter |
| SW4 | Motor power ON/OFF; OFF also clamps driver ARM |
| SW3 | ARM request button; firmware must require deliberate re-arm after faults |
| RV1 | Onboard speed request potentiometer |
| LED1 | RGB status LED beside ARM; red / green / blue driven independently |
| SW1 / SW2 | BOOTSEL / RESET |
| TP1–TP16 | Flat 1.5 mm SWD, PD, driver and bus probe pads with 2.5 mm courtyards; no purchased parts |

J8, J13, J15 and J16 are removed. No battery or external temperature probes are required.

## PD provisioning

Set SW4 OFF and disconnect the motor. Power J19 from a **5 V-only source** and connect J1 DATA to the computer. Run `firmware/provision_pd.py`, remove all power, reconnect the same 5 V-only sources and run `verify_pd_boot.py`. Only after successful cold-start verification attach a PD source. The factory-default STUSB4500 NVM must not be used unreviewed: it may contain higher-voltage profiles.

`power_manager.py` is PD-only diagnostic firmware that keeps SPEED and ARM low. It verifies the selected profiles and accepts `voltage 5`, `voltage 9`, `voltage 15` or `voltage 20` over the MicroPython USB DATA console. Set SW4 OFF, wait until VMOTOR is below 1 V, then enter the command. It requires 250 ms of a stable, matching explicit contract. Unsupported/missing profiles, I²C failures, fallback 5 V and an energized motor bus leave drive OFF. Runtime settings do not write NVM; cold power-up restores 9 V. Host tests cover invalid voltage, PD loss, mismatch, insufficient current, switch OFF, faults and overcurrent. Tests are not hardware measurements.

RP2040 GPIO0/1: MCT I2C; GPIO2: SPEED; GPIO3: ARM; GPIO4: nFAULT; GPIO5: FG; GPIO6: PD_OK2_N; GPIO8: ARM button; GPIO9: DATA VBUS detect; GPIO22/23: PD I2C; GPIO24: PD alert; GPIO10/25/18: red/green/blue status LED. ADC26/27/28/29: input voltage / motor-bus voltage / input current / speed knob. GPIO7/12 are unused after charger removal.

Motor-specific MCT8329A configuration, usable motor-control firmware and USB commands remain to be completed and tested. Driver internal thermal shutdown does not establish external MOSFET temperature limits.

## Configurable revision and limits (trial, 16 October 2026)

STUSB4500 has three sink PDO slots, not four. PDO1 remains the mandatory 5 V / 0.5 A fallback; runtime PDO2 contains the selected 5, 9, 15 or 20 V / 2 A request. PDO3 is inactive and mirrors PDO2. POWER_OK2 and the existing hardware ARM clamp remain in use. The explicit 5 V PDO2 case must be verified on real STUSB4500 hardware: a Python bus model is not proof of its policy-engine negotiation. The manufacturer describes POWER_ONLY_ABOVE_5V in terms of an explicit PDO2/PDO3 contract, despite the bit's name.

RDO operating current must equal the 2 A request; RDO maximum current reports the source's capability and can be higher (for example, 3 A). Reject capability mismatch and an unverified voltage. A charger that lacks the requested profile is not silently treated as ready.

R11 and R30 are now 220 kΩ with 15 kΩ lower resistors. Both ADC conversions use 235/15, not 115/15. Calibrate the ADC reference and dividers with a meter before load testing. The input shunt measures the motor feed, not the always-on logic branch. Provisional motor-feed limits are 0.8 A at 5 V and 1.5 A at 9/15/20 V. They are input-current limits, not winding phase-current ratings. Logic/PD consumption must be measured and included in the 2 A source budget.

These limits are currently implemented only in the tested `motor_permitted()`
policy helper. The diagnostic console does not call it to control a motor: it
holds SPEED and ARM low throughout. A motor application must integrate the
calibrated voltage/current checks, driver configuration, user controls and fault
latching before these limits can be described as enforced during operation.

The original example motor stays on the assembly. Higher settings are for suitably rated motors and validated driver tuning; the connector diameter does not determine a motor's voltage rating. There is no continuous voltage slider and no automatic maximum-voltage selection.

5 V cannot deliver the same load through every compliant cable: USB Type-C permits up to 0.75 V cable-loop drop at a cable's rated current. Even a low-loss PCB cannot recover voltage already lost in the cable. The motor must stop before its supply falls below the driver's operating minimum. A regulated boost stage would be a different redesign if a guaranteed 5 V load across worst-case cables is required.

Sources: [STUSB4500](https://www.st.com/resource/en/datasheet/stusb4500.pdf),
[MCT8329A](https://www.ti.com/lit/ds/symlink/mct8329a.pdf),
[USB Type-C cable requirements, section 3.4.3](https://www.usb.org/sites/default/files/USB%20Type-C%20Spec%20R2.0%20-%20August%202019.pdf).

## RGB status indication — 17 October 2026

LED1 is a TOGIALED TJ-S1615SW6TGLCCSRGB-A5 (JLCPCB C273611), a
1.6 x 1.5 mm common-cathode RGB LED. Pin 1 is green, pin 2 blue, pin 3 red,
and pin 4 ground. GPIO25 -> R47 -> green, GPIO10 -> R48 -> red,
and GPIO18 -> R49 -> blue. All three resistors are 1 kohm / 1%.
The LED uses the 3.3 V GPIO supply and needs no separate power converter.
The MCU pins start as inputs; status_led.py initializes all channels LOW.

Current diagnostic-firmware meanings:
- Blue: starting, waiting for a valid PD contract, or requesting a new voltage.
- Green: the selected PD contract has passed the existing checks. Motor remains OFF.
- Red: a command, I2C, provisioning or register-verification error.
- Off: software stopped by Ctrl-C, or no powered/running indicator firmware.

These indications do not claim motor readiness or physical motor operation.
Motor-run indication can be added when the motor application is implemented.
At 3.3 V, 1 kohm gives low indicator currents (typically around 1 mA red and
sub-mA green/blue); brightness depends on LED forward voltage and must be checked
on the prototype. The datasheet's green/blue 3.6 V maximum is specified at 20 mA;
this design does not attempt to drive the LED at 20 mA. Even with an LED short,
a 3.465 V supply and 990-ohm resistor limit each channel to 3.5 mA.
Allow up to 10.5 mA extra on the 3.3 V rail for an all-channel short case;
normal firmware lights only one colour at a time. This does not resolve the
existing 5 V motor-supply limitation.

[Manufacturer datasheet](https://www.lcsc.com/datasheet/C273611.pdf).