Getting Started

Hardware

• Raspberry Pi Pico W (recommended) or plain Pico — the W adds WiFi; a plain Pico works fine over USB serial
• Micro-USB cable — for power, firmware upload, and serial communication
• Pinewood derby track with lane finish sensors and a start gate switch
• Wiring to connect the track's sensors to the Pico's GPIO header pins (jumper wires, breakout board, or whatever suits your connector)

Software

• Chrome or Edge (desktop) — required for both RallyLab and the Pico Debug Console (Web Serial API)
• MicroPython firmware — the Pico W runs MicroPython; you'll install it once

If your Pico W already has MicroPython installed, skip to step 3.

1. Download the latest MicroPython UF2 for the Pico W from micropython.org.
2. Hold the BOOTSEL button on the Pico W, then plug in the USB cable. A drive named RPI-RP2 appears on your computer.
3. Drag the .uf2 file onto the RPI-RP2 drive. The Pico reboots automatically and the drive disappears — MicroPython is now installed.

The firmware lives in the firmware/ directory of the RallyLab repository. You can upload it using the Pico Debug Console in your browser, or with a command-line tool like mpremote.

Option A: Pico Debug Console (browser)

1. From the Operator Console, click the "Open" menu and select "Pico Debug Console".
2. Click Connect and select your Pico from the serial port picker.
3. Switch to the Files tab.
4. Click "Load from GitHub" — this downloads all firmware files from the repository and writes them to the Pico automatically. Alternatively, click "Upload" and select the .py files from the firmware/ directory yourself (multi-select is supported).
5. Click Restart Firmware to soft-reset the Pico.

Option B: mpremote (command line)

Install mpremote with pip, then copy all firmware files to the Pico:

pip install mpremote
mpremote cp firmware/*.py :

Reset the Pico to start the new firmware:

mpremote reset

Most pinewood derby tracks have lane finish sensors (normally-open switches that close when a car arrives) and a start gate switch (often a magnetic reed switch that opens when the gate releases). Each sensor wire connects to a GPIO pin on the Pico; the Pico uses internal pull-ups, so a sensor triggering pulls the pin LOW.

The wiring depends on your specific track. Here's what you need to figure out:

1. How many lanes does your track have, and which wire goes to which lane?
2. What kind of start gate switch does it use? A reed switch opens on release (rising edge = race start). A microswitch may work the opposite way.
3. Is there a common ground? Most tracks share a ground wire across all sensors — connect it to the Pico's GND pin.

Use a multimeter in continuity mode to map each sensor to its wire. Trip each lane sensor one at a time and note which wire shows continuity to ground.

Update config.py

Open config.py on the Pico (via the Debug Console's Files tab or mpremote) and set the pin mapping to match your wiring. The file ships with presets you can use as starting points:

• Breadboard (default) — pushbuttons on GP5–GP13, for development without a track
• SuperTimer (dedicated gate) — for tracks with a DA-15 connector where the start gate has its own pin
• SuperTimer (shared pin) — for DA-15 tracks where Lane 2 and the start gate share a wire

The key settings are LANE_PINS (a dict mapping lane number to GPIO number), GATE_PIN, and GATE_INVERT (set True for breadboard buttons, False for a real reed switch). Edit these to match your track and save.

After editing, click Restart Firmware (or run mpremote reset).

Before running a race, verify that every sensor and the start gate are working correctly.

1. Open the Pico Debug Console from the Operator Console's "Open" menu and connect to the Pico W.
2. In the Terminal tab, type info and press Enter. You should see the firmware version, protocol version, and lane count.
3. Type dbg to see a snapshot of all sensor states, WiFi status, and the engine state machine phase.
4. Type dbg_watch to start a live edge monitor. Now trip each lane sensor and the start gate one at a time — you should see a JSON line for each event confirming the correct pin label.
5. Type anything (e.g., state) to stop the watch and return to normal command mode.

With the firmware verified, you're ready to connect the Operator Console to the track controller.

1. Open the Operator Console (operator.html) and load your rally (or load demo data to test).
2. Click the Connect button in the top toolbar.
3. Select the Serial (USB) connection type and pick the Pico W's serial port.
4. The status indicator turns green when connected. The operator console now receives finish times automatically as races complete.

WiFi connection (optional)

For a wireless setup, configure WiFi credentials on the Pico first. In the Debug Console terminal:

wifi_setup MyNetworkName MyPassword

The Pico saves credentials and auto-connects on future boots. Once connected, it starts an HTTP server and advertises itself on the local network via mDNS. You can connect using either the IP address (shown on boot) or the .local hostname.

By default, the hostname is based on the device's MAC address (e.g., rallylab-a1b2c3.local). For race day, you can set a memorable name so it's easy to share:

hostname_set pack42

Now the Pico is reachable at pack42.local. The name is saved and persists across reboots. You can also configure the hostname from the Operator Console's Track Manager dialog when connected via USB.

In the Operator Console, choose WiFi as the connection type and enter the Pico's address — either an IP like 192.168.1.42 or a hostname like pack42.local.

With the track connected, the race flow is fully automatic. The Track Operator at the physical track does two things per heat — everything else happens by itself.

1. Check in participants and start a section from the Operator Console (just like in the Evaluation Guide).
2. The first heat is staged. The audience display shows lane assignments to the crowd.
3. The Track Operator loads cars onto the assigned lanes and releases the start gate.
4. The Pico detects the gate release (rising edge on the reed switch) and starts timing.
5. As each car crosses the finish line, the Pico records its time. When all active lanes have finished (or the timeout expires), it reports the results.
6. The Operator Console receives the times, records the heat, and the audience display updates automatically.
7. The Track Operator resets the start gate (pushes it back down). The Pico detects this, and the next heat stages automatically.
8. Repeat until all heats are complete.

Pico not appearing as a serial port

• Make sure you're using a data USB cable, not a charge-only cable.
• Try a different USB port. Some USB hubs don't enumerate the Pico reliably.
• On Mac, look for /dev/cu.usbmodem*. On Windows, check Device Manager for a new COM port.

Serial port is locked

Only one program can use the serial port at a time. If the Debug Console says "Failed to open", make sure mpremote, another terminal, or another browser tab isn't already connected. Close the other connection and try again.

Lane sensor not triggering

• Run dbg_watch in the Debug Console and trip the sensor manually. If nothing appears, check the physical wiring between the sensor and the Pico GPIO pin.
• Verify the pin mapping in config.py matches your actual wiring.
• Check continuity between the sensor wire and the Pico's GPIO pin with a multimeter.

Gate release not detected

• The start gate uses a reed switch (magnetic). Make sure the magnet is aligned — the switch should be closed (LOW) when the gate is down and open (HIGH) when released.
• Check the GATE_INVERT setting in config.py. Breadboard buttons and reed switches have opposite logic: set True for breadboard buttons, False for the real reed switch.
• Use dbg_watch to confirm you see a gate edge when the gate is released.

Finish times are consistently slow or delayed

Some older tracks have debounce capacitors on the sensor lines (e.g., 10 µF electrolytics wired between each lane signal and ground). These were designed for the original timer hardware but slow down the edge that the Pico needs to see. If your finish times seem 100–500 ms too high across all lanes, capacitors are the likely cause.

• Inspect the cable or connector for small cylindrical capacitors soldered inline.
• Bypass or remove them — the Pico's firmware handles debouncing in software (DEBOUNCE_MS in config.py, default 10 ms).

Race times are missing or wrong

• Run dbg and check the engine.phase. It should be IDLE between races and RACING after the gate opens.
• If a lane shows no time, its sensor may not have triggered. Check wiring for that lane.
• If the race ends by timeout (default 15 seconds), it means one or more active lanes didn't finish. Inspect the lane sensors or reduce the active lane set.

WiFi won't connect

• The Pico W supports 2.4 GHz only — it cannot connect to 5 GHz networks.
• Double-check the SSID and password. Credentials are case-sensitive.
• After running wifi_setup, type dbg to check the wifi section for connection status, IP address, and signal strength (RSSI).