PhotoCar — Complete Build & Wiring Guide

1. Bill of Materials & Specs

2. Parts — Reuse, Buy & Budget

Conservative list including the small wiring and mounting parts that usually get missed. Buy the genuine Raspberry Pi from a trustworthy listing; save money on generic wiring, housings, heat-shrink, standoffs, fuse holders, and buck converters — never by removing the Pi fuse, undersizing the 5 V regulator, or powering the Pi from the MD25HV 5VO.

Reuse from the existing car

Buy / add

Optional add-ons

3. System Architecture

High-current drive power and low-current control signals stay on separate paths. The selected battery feeds a main bus, through the E-stop and master switch to a switched bus, which feeds both the MD25HV power input and the buck converter. The buck powers the Pi at 5 V. The Pi commands the MD25HV with three signal wires: PWM, DIR, and a shared GND.

4. Control Wiring — Pi to MD25HV

The MD25HV runs in PWM/DIR mode. Three wires connect it to the Pi: PWM = GPIO18 (physical pin 12), DIR = GPIO23 (physical pin 16), and a shared GND (pin 14). GPIO18 is used because GPIO12 is dead/shorted-to-ground on this board. Pins 12, 14, and 16 are three consecutive outer-row pins, so the whole Pi side is a single 1×3 housing.

MD25HV board — connect here, not there

The MD25HV has more than one control area. Ignore the small manual potentiometer/rocker headers (those were for standalone manual control). For Pi/software control, land on the green control screw terminal silk-screened GND / 5VO / PWM / DIR. Battery power goes to the high-current terminals on the opposite edge: VB+, VB−, and the motor on MA / MB. Match the printed labels on your physical board before powering anything.

5. Power Wiring

The car's power path is: selected battery → main bus → E-stop → master On/Off (DPST) → switched bus → MD25HV power input and buck converter. Negatives return through the Main(−) and Switched(−) bus bars. The buck output powers the Pi at 5 V, which also establishes the Pi–MD25HV common ground through the control cable.

Soldered Y-split harness (positive & negative distribution)

Where the switched bus feeds both the MD25HV and the buck, a clean removable harness is a soldered Y-split rather than soldering directly to fixed components:

1. Cut one trunk wire (from the switched bus / switch output) and two branch wires (MD25HV + buck).
2. Slide adhesive-lined heat-shrink onto the trunk before soldering.
3. Strip enough insulation that the three copper ends overlap mechanically; twist the two branches together, then wrap with the trunk.
4. Solder so it flows through the joint, not just on the outside; let it cool without movement.
5. Cover with the adhesive heat-shrink; add an outer sleeve or cable wrap if the harness will vibrate.
6. Repeat for the negative side. Use heavier wire on the MD25HV branch (motor current) than on the buck branch.

6. Software & Control

The Pi runs motor-control (TypeScript/Node) as the systemd service photocar-ble.service, installed by scripts/provision-photocar.sh. It accepts drive commands over Bluetooth LE (from the PhotoCar tablet/phone app) and a WiFi TCP control port.

Provisioning a fresh Pi — two ways, same result

Both paths end at the same place: the Pi-side provisioner scripts/provision-photocar.sh runs as root, installs packages, writes the PWM overlay, builds the app, installs photocar-ble.service, and reboots once if the boot config changed. It is idempotent — safe to re-run for updates too.

Step 0 — flash the right OS onto the microSD

1. Install Raspberry Pi Imager on any computer with an SD card reader.
2. Choose Device: Raspberry Pi Zero 2 W.
3. Choose OS: Raspberry Pi OS (Bookworm, Debian 12). This matters: the provisioner and its PWM/boot-config handling target Bookworm — do not pick a Trixie (Debian 13) image. If the Imager's default entry says Trixie, go to Raspberry Pi OS (other) and pick a release explicitly labelled Bookworm (the “Legacy” entries once Trixie becomes the default). 32-bit or 64-bit both work on the Zero 2 W.
4. Click the gear / “Edit Settings” before writing and set:
   • Hostname: photorcar (this is what deploy.ps1 and its -Scan mode look for).
   • Username / password: dealermade / the usual password (the provisioner assumes user dealermade exists).
   • WiFi: your SSID + password, and set the wireless LAN country (e.g. US) — without a country the radio can stay rfkill-blocked.
   • Services tab: enable SSH with password authentication.
5. Write the card, put it in the Pi, and power up. First boot takes a couple of minutes (it resizes the filesystem and joins WiFi).

Step 0.5 — SSH into the Pi

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

• Accept the host-key prompt on first connect, then enter the password you set in the Imager.
• If photorcar.local does not resolve (mDNS can be flaky on Windows), find the Pi's IP in your router's client list — or from the PC just run .\deploy.ps1 -Scan, which sweeps the subnet and identifies the Pi by hostname — then ssh dealermade@<ip>.
• Sanity checks once you're in: hostname should say photorcar, and cat /etc/os-release should show VERSION_CODENAME=bookworm. If it says trixie, reflash with the Bookworm image before provisioning.

Way 1 — from the PC: deploy.ps1 (the single deploy script)

• deploy.ps1 is the only deploy script (it replaced the old separate Provision-PhotoCar.ps1). Full end-to-end: discovers the Pi, auto-pins its SSH host key, packages motor-control, uploads, provisions as root, rides out the reboot, then verifies the service and runs the PWM self-test.
• Run from the repo root on Windows: .\deploy.ps1 — or .\deploy.ps1 -Scan to find the Pi on the local subnet, -HostName 192.168.1.66 to target an IP, -DryRunMotor to provision without driving the motor.
• It also refreshes PhotoCarTablet/pages-guide/photocar-motor.tar.gz, so pushing the tablet repo republishes the same payload to the guide site for Way 2.

Way 2 — on the car itself, over WiFi with curl (no PC needed)

The guide site hosts a bootstrap script and the full motor-control payload, so the Pi can fetch and install everything itself. In the SSH session from Step 0.5:

# 1) download the setup script from the guide site
curl -fsSL https://photocar.userinterfaces.shop/setup.sh -o /tmp/photocar-setup.sh

# 2) execute it (root required — it installs apt packages and a systemd service)
sudo bash /tmp/photocar-setup.sh

Or as a one-liner:

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

What the install does, in order:

1. setup.sh downloads photocar-motor.tar.gz from the same site and extracts it to /home/dealermade/photocar-motor.
2. It hands off to scripts/provision-photocar.sh provision — the exact same provisioner Way 1 runs: apt packages (bluetooth bluez nodejs npm build-essential… — the apt step takes several minutes on a Zero 2 W), PWM overlay in config.txt, npm install && npm run build, then installs and enables photocar-ble.service and the boot LED service.
3. On a fresh image the boot config changed, so the Pi reboots itself once (your SSH session drops — that's expected). After the reboot the service starts on its own; when the status LED goes solid green the car is ready to drive.
4. Re-running the same two commands later is safe — it re-downloads the latest payload and updates in place.

Verifying either way

• PWM hardware self-test on the Pi: sudo bash /home/dealermade/photocar-motor/scripts/provision-photocar.sh selftest (looks for the channel reporting enabled). deploy.ps1 runs this automatically at the end.
• Service up: systemctl is-active photocar-ble.service; WiFi control port: ss -ltn | grep 7777.

Service environment (the source of truth for pins)

Boot config line written by the provisioner: dtoverlay=pwm,pin=18,func=2 (GPIO18 reaches the PWM block via ALT5). Reboot once after first adding it.

Boot status LEDs

A single RGB LED module shows boot state: red blinks from the first seconds of kernel boot, then goes out and green comes on solid once the receiver (photocar-ble.service) is up and the car is ready to drive. If the service later stops, it falls back to blinking red. The early blink is the kernel itself — the installer adds dtoverlay=gpio-led,…,trigger=timer lines to config.txt (one reboot required after install), so red blinks long before the OS is up; photocar-bootled.service then takes over and swaps red for green when ready.

Only three legs are wired — R, G, and the common -; the blue leg gets no wire. Pins 35 / 37 / 39 are 3 physically adjacent inner-row header pins, so the harness is a single 1×3 housing (R first, GND last). These pins avoid everything in use: GPIO18 (PWM, pin 12), GPIO23 (DIR, pin 16), GPIO17 (keyfob, pin 11), and dead GPIO12. The module has onboard resistors — no external resistors needed (a bare LED would need ~330 Ω per leg). Common-cathode default (GPIO high = lit); for common-anode modules set PHOTOCAR_LED_ACTIVE_HIGH=0. The firmware's GPIO env vars are comma-separated lists and also drive GPIO9/GPIO11 by default (a second, unfitted LED position) — those pins simply stay unwired.

7. Assembly Steps

8. Bring-Up Checklist

• Selector set, E-stop released, master switch off until checks pass.
• MD25HV power polarity and buck input polarity verified with a meter.
• Buck output set and verified at 5.1 V before plugging the Pi.
• MD25HV 5VO is not connected to the Pi.
• Control wiring: PWM on pin 12 (GPIO18), GND on pin 14, DIR on pin 16 (GPIO23) — one 1×3 — landing on MD25HV PWM / GND / DIR by label.
• Boot config has dtoverlay=pwm,pin=18,func=2 and the Pi has been rebooted since.
• provision-photocar.sh selftest passes (PWM channel reports enabled).
• Wheel lifted off the ground for the first forward/back test; confirm direction, then test STOP and the 1.2 s watchdog.
• If direction is reversed: swap the two motor leads or flip DIR_FORWARD_LEVEL.

Source Notes

Control-side facts (pins, PWM mode, frequency, service env, provisioning) are read from the live firmware in motor-control/ — primarily scripts/provision-photocar.sh and src/MotorController.ts. Part specifications (MD25HV, Pi Zero 2 W, buck, battery, motor, mounting plate, bus/selector/E-stop power chain) are the modeled PhotoCar parts.