PhotoCar master build guide

Know which artifact you are trusting

Three artifacts describe this car and they do not agree. Read this before you crimp anything or run a deploy, because the disagreement is about which header pins carry throttle and direction.

What is on the car and what each thing does

Buy / add

One source, two loads, one shared ground

Selected battery → Main(+) bus → E-stop → master On/Off (DPST) → Switched(+) bus → the MD25HV power input and a fused branch to the buck converter. Negatives return through the Main(−) and Switched(−) bars. The buck powers the Pi through its PWR IN port, and the control cable establishes the one place the two rails meet: a shared ground.

Soldered Y-split harness

Where the switched bus feeds both the MD25HV and the buck, the clean removable answer is a soldered Y-split, not two wires jammed under one screw.

• Cut one trunk wire and two branch wires. Use heavier wire on the MD25HV branch — that one carries motor current; the buck branch carries under an amp.
• Slide adhesive-lined heat-shrink onto the trunk before soldering. Everyone forgets this once.
• Strip enough that the three copper ends overlap mechanically. Twist the branches together, then wrap with the trunk. The joint must hold without solder.
• Solder so it wicks through the joint rather than balling on the outside; let it cool without movement or you get a dull, brittle cold joint.
• Cover with the adhesive heat-shrink, then an outer sleeve wherever the harness will vibrate. Repeat for the negative side.

Three wires, one housing, three consecutive pins

The MD25HV runs in PWM/DIR mode. Three conductors connect it to the Pi: PWM = GPIO18 (pin 12), DIR = GPIO23 (pin 16), and a shared GND (pin 14). Those are three consecutive positions on the outer row, so the Pi side is a single 1×3 housing that cannot seat a column off.

What the car tells you, and the one input that can drive it

Both of these land on the inner (odd) row, at opposite ends of the header, so neither can be confused with the control harness on 12/14/16.

Boot status LED

433 MHz keyfob

The receiver has four wires, in two electrically separate pairs. Red and black are the module's own supply — they power the receiver and the relay coil, and go to pin 2 (5 V) and pin 6 (GND). White and yellow are the two sides of the relay's isolated dry contact: one goes to pin 9 (GND), the other to pin 11 (GPIO17). Because a dry contact is just a symmetric switch, white and yellow are interchangeable — there is no wrong way round. The GPIO is an input with the Pi's internal pull-up, so an open contact reads high and a closed relay pulls it low. Active LOW means “go”, and no module voltage ever reaches the GPIO.

Two paths to the same provisioned Pi

The Pi runs motor-control (TypeScript on Node) as the systemd service photocar-ble.service, installed by scripts/provision-photocar.sh. It takes drive commands over Bluetooth LE from the tablet app and over a plain TCP port on WiFi. Both paths below end at the same provisioner, which is idempotent and safe to re-run.

Step 0 — flash the right OS

• Install Raspberry Pi Imager. Choose Device: Raspberry Pi Zero 2 W.
• Choose OS: Raspberry Pi OS (Bookworm, Debian 12). The provisioner's PWM and boot-config handling targets Bookworm. Do not pick a Trixie (Debian 13) image; if the Imager defaults to Trixie, go to Raspberry Pi OS (other) and pick a release explicitly labelled Bookworm.
• Click gear / Edit Settings before writing: hostname photocar; user dealermade + password; WiFi SSID, password and the wireless LAN country; Services tab → enable SSH with password authentication.
• Write, fit, power up. First boot takes a couple of minutes while it resizes the filesystem and joins WiFi.

Step 0.5 — SSH in

# from any machine on the same WiFi network
ssh dealermade@photocar.local

• If photocar.local does not resolve (mDNS is flaky on Windows), find the Pi in your router's client list, or run .\deploy.ps1 -Scan, then ssh dealermade@<ip>.
• Sanity check: hostname must print photocar, and cat /etc/os-release must show VERSION_CODENAME=bookworm. If it says trixie, reflash before provisioning.

Way 1 — from the PC: deploy.ps1

The only deploy script. It finds the Pi, pins its SSH host key, packages motor-control, uploads, provisions as root, rides out the reboot, verifies the service, and runs the PWM self-test.

$env:PHOTOCAR_PI_PASSWORD = "<pi password>"
.\deploy.ps1

.\deploy.ps1 -Scan                  # sweep the /24 and find the Pi by hostname
.\deploy.ps1 -HostName 192.168.1.66 # target an IP directly
.\deploy.ps1 -DryRunMotor           # provision with PHOTOCAR_REAL_MOTOR=0
.\deploy.ps1 -Audio off             # frees the onboard-audio PWM claim

Requires PuTTY's plink.exe and pscp.exe at C:\Program Files\PuTTY\. It also refreshes PhotoCarTablet/pages-guide/photocar-motor.tar.gz, so pushing the tablet repo republishes the payload for Way 2.

Way 2 — on the car itself, over WiFi, no PC

curl -fsSL https://photocar.userinterfaces.shop/setup.sh -o /tmp/photocar-setup.sh
sudo bash /tmp/photocar-setup.sh

# or, as a one-liner
curl -fsSL https://photocar.userinterfaces.shop/setup.sh | sudo bash

• setup.sh downloads photocar-motor.tar.gz and extracts it to /home/dealermade/photocar-motor.
• It hands off to provision-photocar.sh provision — the same provisioner Way 1 runs. The apt step (bluetooth bluez build-essential nodejs npm python3 git x11-xserver-utils) takes several minutes on a Zero 2 W and looks hung. It is not.
• Writes the PWM overlay, adds the user to the gpio i2c spi video render input dialout plugdev groups, then npm install && npm run build.
• Pins the WiFi profile you are connected on to autoconnect-priority 100 and disables autoconnect on every competing profile.
• Installs and enables photocar-ble.service and photocar-bootled.service, runs the PWM self-test, starts the receiver.
• On a fresh image the boot config changed, so the Pi reboots itself once and your SSH session drops. That is expected.

Verifying either way

sudo bash /home/dealermade/photocar-motor/scripts/provision-photocar.sh selftest
systemctl is-active photocar-ble.service
systemctl show photocar-ble.service -p Environment | tr ' ' '\n' | grep -E 'PWM_GPIO|DIR_GPIO'
ss -ltn | grep 7777
journalctl -u photocar-ble.service -f

Service environment

The control protocol

BLE and the TCP port speak the same JSON. On TCP it is newline-delimited both ways on port 7777; on connect the server sends a hello frame with full status, then a status frame after every command and on every state change.

{"cmd":"drive","dir":"forward","throttle":50,"seq":1}
{"cmd":"stop","seq":2}
{"cmd":"ping","seq":3}
{"cmd":"wifiScan"}
{"cmd":"wifi","ssid":"MyNetwork","psk":"secret"}
{"cmd":"shutdown"}

Battery telemetry

Pack voltage is not read from an ADC driver. The service reads plain files named by BATTERY_VOLTAGE_FILE and BATTERY_PERCENT_FILE and parses each as a number. Until you wire an ADC or divider and have something write those files, the app shows:

Car battery voltage is not wired to the Pi yet.
Add an ADC/voltage divider and set BATTERY_VOLTAGE_FILE to show pack voltage.

Pi-side health is real: vcgencmd get_throttled and measure_temp feed under-voltage, frequency-cap and thermal flags into the same status payload, and a CPU temperature at or above 80 °C raises a note. An under-voltage flag on this car almost always means the buck is sagging or set below 5.1 V, not that the pack is flat.

Bench first, harness second, car last

• Bench-test the Pi before it goes near the car. Image Bookworm with WiFi and SSH, provision it with the pin override, pair the tablet on USB bench power, and confirm the PWM self-test passes. A Pi that cannot pass selftest on a bench will not start working once bolted into an enclosure.
• Mount the Pi and buck. Vacuum the enclosure. Mount the Pi on non-conductive standoffs. Keep the 5 V leads short and the Pi's antenna area clear of metal and large bundles.
• Build the fused, switched buck branch. Fuse close to the bus tap, not next to the Pi. Verify buck input polarity, then set the output to 5.1 V with a meter before it ever meets the Pi.
• Build the control harness from 1-pin pre-crimped leads into one 1×3 housing — PWM, GND, DIR in the order pin 12 → 14 → 16. Tug-test each lead; if a crimp backs out, replace that lead rather than re-seating it. Label it before plugging in.
• Build the LED harness as a second 1×3 on pins 35 / 37 / 39, red first, ground last. Never solder wires directly to the header — serviceable connectors are what survive a moving car.
• Land on the MD25HV control terminal only. Green screw terminal, by printed label, ferrules on the wire, 5VO empty. Then check continuity from Pi GND to MD25HV GND with a meter.
• Wire the keyfob relay last — COM to pin 9, NO to pin 11 — and confirm the pin reads inactive at idle.
• First motor test at low throttle with the wheel lifted. Not on the floor, not "just briefly".

Prove one subsystem at a time

• Selector set, E-stop released, master switch off until every check below passes.
• MD25HV and buck input polarity verified with a meter, pack disconnected.
• Buck output confirmed at 5.1 V measured at the Pi end of the cable before the Pi is plugged in.
• MD25HV 5VO confirmed connected to nothing.
• Control wiring confirmed by label: PWM pin 12, GND pin 14, DIR pin 16, landing on PWM / GND / DIR. Count from the outer row.
• Exactly one PWM overlay line in the boot config, reading dtoverlay=pwm,pin=18,func=2, with a reboot since it was added.
• systemctl show photocar-ble.service -p Environment shows PWM_GPIO=18 and DIR_GPIO=23. If it shows 12 and 21, stop and re-provision with the override.
• provision-photocar.sh selftest passes. Remember it stops and restarts the receiver.
• Status LED watched through a full boot: blinking red from early kernel boot, then solid green.
• Wheel lifted. Test forward, confirm direction, then back. If reversed, swap the motor leads at MA/MB or flip DIR_FORWARD_LEVEL — never a control wire.
• Test STOP, then the watchdog: start driving, kill the controller, confirm the motor stops within 1.2 s and the state reads watchdog_stop.
• Test the keyfob with the wheel still lifted, including a second press to unlatch. Confirm the E-stop kills everything from a live drive.
• Only then a low-throttle floor test, followed by a re-check of every exposed fastener and connector.

It is doing something impossible — start here

Every entry is a failure that already happened on this car. Find the symptom, then read the linked section before you re-measure anything.