aws-solutions-library-samples · larsll · Mar 11, 2026 · Mar 20, 2026
diff --git a/leaderboard-timer/README.md b/leaderboard-timer/README.md
@@ -2,17 +2,42 @@
 
 The DeepRacer timer is an automated timing solution which is used together with the leaderboard & timekeeper system used during DeepRacer events.
 
-### Important
+### Important Updates (v2.0)
 
-Please note that the most recent release of Raspberry Pi OS "Bookworm" is currently not supported due to changes in the way the GPIO is handled, please use "Bullseye" (Legacy) for the RPi operating system.
+**Broad Raspberry Pi Support**
+
+- Compatible with all Raspberry Pi models: RPi 1/2/3/4/5, Zero W, Zero 2W, Compute Modules
+- Uses `node-libgpiod` (libgpiod character device interface) on all modern installs — unaffected by the kernel 6.x sysfs GPIO renumbering
+- Automatic fallback to `rpi-gpio` for pre-kernel-6.x systems (not recommended)
+- Recommended Raspberry Pi OS Bookworm or newer. Ubuntu will work, but installation script might need some manual tweaking. Older Raspberry Pi OS may also work.
+
+**Enhanced Timing Accuracy:**
+
+- Server-side timestamps capture exact trigger time (eliminates network latency)
+- Per-sensor debounce tracking (configurable, default 2 seconds)
+- Improved reliability and logging
 
 ## Hardware Requirements
 
-**NOTE:** At this time the Raspberry Pi 5 is not supported for automated timing due to changes in the way the GPIO is connected. Please review this [issue](https://github.com/aws-solutions-library-samples/guidance-for-aws-deepracer-event-management/issues/14) for updates.
+### Supported Devices
+
+- Raspberry Pi 5 / Compute Module 5
+- Raspberry Pi 4 / Compute Module 4
+- Raspberry Pi Zero 2W
+- Raspberry Pi Zero W
+- Raspberry Pi 3 / Compute Module 3
+- Raspberry Pi 1 / Zero / Compute Module 1 (ARMv6)
+
+**Performance Notes:**
+
+- **Pi 5 & Pi 4**: Excellent performance, handles multiple simultaneous connections easily
+- **Pi Zero 2W**: Good performance, quad-core processor, recommended upgrade from Zero W
+- **Pi Zero W**: Works well for single timing station, limited by single-core processor
+
+All models provide accurate timing - the performance differences mainly affect WebSocket connection handling and system responsiveness.
 
 ### Required
 
-- Raspberry Pi 4 / Zero W (known to work)
 - 2x Sound Sensors [Variant 1 - Youmile (preferred)](https://www.amazon.co.uk/Youmile-Sensitivity-Microphone-Detection-Arduino/dp/B07Q1BYDS7/ref=sr_1_1_sspa?crid=YZ2AA2SUOG67&keywords=sound+sensor&qid=1655970264&sprefix=sound+sensor%2Caps%2C84&sr=8-1-spons&psc=1&smid=A3BN2T8LLIRB5S&spLa=ZW5jcnlwdGVkUXVhbGlmaWVyPUExMU5PTFY5WTlKTk8wJmVuY3J5cHRlZElkPUEwODEwNzkzM1ZCVU42MDdJQTdVUSZlbmNyeXB0ZWRBZElkPUEwNzMzMTg2MzNISEdLSjhINDRHNCZ3aWRnZXROYW1lPXNwX2F0ZiZhY3Rpb249Y2xpY2tSZWRpcmVjdCZkb05vdExvZ0NsaWNrPXRydWU=) / [Variant 2 - WaveShare](https://www.waveshare.com/sound-sensor.htm)
 - 2x [Pressure sensor](https://www.amazon.co.uk/gp/product/B07PM5PTPQ)
 - 2X 1.5m, two core flat wire between sound sensor and pressure sensors
@@ -58,12 +83,18 @@ To install the Raspberry Pi (RPi) OS on an SD card the recommended approach is u
 
 Once installed choose the one of the following images based on the RPi being used.
 
-- RPi 4 : Raspberry Pi OS (Other) -> Raspberry Pi OS Lite (64-bit)
-- RPi Zero W : Raspberry Pi OS (Other) -> Raspberry Pi OS Lite (32-bit)
+**Recommended OS: Raspberry Pi OS Bookworm (or newer), 32-bit or 64-bit**
+
+| Device                  | Recommended OS                               |
+| ----------------------- | -------------------------------------------- |
+| RPi 5 / CM5             | Raspberry Pi OS (64-bit) - Bookworm or later |
+| RPi 4 / CM4             | Raspberry Pi OS (64-bit) - Bookworm or later |
+| RPi Zero 2W             | Raspberry Pi OS (64-bit) - Bookworm or later |
+| RPi Zero W / Zero / CM1 | Raspberry Pi OS (32-bit) - Bookworm or later |
 
 ![Raspberry Pi Imager - Choose OS & Storage](./docs/images/pi_imager_os.png)
 
-**Note:** Screen shot is for an RPi Zero W
+**Note:** Bookworm ships with Linux kernel 6.x, which is required for the `node-libgpiod` GPIO library used by the timer. Bullseye and earlier are not recommended.
 
 Once you've selected your OS click on settings to configure the advanced settings.
 
@@ -73,7 +104,7 @@ Here you can set the device hostname, password, enabale SSH and (optionally) con
 
 For the username we recommend you use: `deepracer` as this is the expected value used in the service definition.
 
-**Important:** The [service-definition/deepracer-timer.service] is configured to expect the RPi username to be `deepracer`, if you use a different username you will need to change the following lines for the `WorkingDirectory` and `ExecStart` paths and also the `User` before running `service-setup.js`
+**Important:** The [service-definition/deepracer-timer.service] is configured to expect the RPi username to be `deepracer`. The activation script updates these automatically, but if you are setting up manually with a different username you will need to edit the following lines:
 
 ```
 WorkingDirectory=/home/deepracer/deepracer-timer
@@ -84,6 +115,44 @@ User=deepracer
 
 Once the SD card has been written, eject it from your computer, insert into the RPi and boot it up.
 
+### Node.js Installation
+
+The timer requires **Node.js 18 LTS** or later. The DREM activation script installs Node.js v18.20.8 automatically. To install it manually:
+
+```bash
+# Install Node.js 18 LTS
+curl -fsSL https://deb.nodesource.com/setup_18.x | sudo -E bash -
+sudo apt-get install -y nodejs
+
+# Verify installation
+node --version  # Should show v18.x.x
+npm --version
+```
+
+### Time Synchronization (Important for Accuracy)
+
+For accurate timing, ensure your Raspberry Pi's clock is synchronized with NTP:
+
+```bash
+# Check NTP status
+timedatectl status
+
+# If NTP is not active, enable it
+sudo timedatectl set-ntp true
+
+# Verify synchronization
+sudo systemctl status systemd-timesyncd
+```
+
+The timer now captures timestamps on the device itself (not in the browser), which eliminates network latency from timing measurements. However, accurate time synchronization ensures consistency across multiple timing sessions and with other systems.
+
+**Network Latency Considerations:**
+
+- The timer captures the exact moment the GPIO triggers using high-precision timestamps
+- These timestamps are sent to the browser along with the lap event
+- Network latency only affects display updates, not the actual lap time measurements
+- Typical latency: 10-50ms on local network, negligible impact on timing accuracy
+
 ### DeepRacer Timer Service
 
 Go to `Device Management -> Timer activation` in DREM, select a fleet and enter a hostname for the RPi and click `Generate`
@@ -92,8 +161,10 @@ Clicking on the `Copy` button copies the activation script to your clipboard, SS
 
 This process has been tested on:
 
-- Pi Zero W
-- Pi 4
+- Pi Zero W (32-bit OS)
+- Pi Zero 2W (64-bit OS recommended)
+- Pi 4 (64-bit OS)
+- Pi 5 (64-bit OS, Bookworm)
 
 If you get an error with the service you can check the status of it using
 
@@ -149,12 +220,95 @@ There is an `.stl` file to print out the sensor box choose the right `.stl` file
 
 ![TimerBox](./docs/images/timerbox.png)
 
+## Configuration
+
+Configuration is done by editing the `config` object near the top of [timer.js](timer.js).
+
+After editing, restart the service:
+
+```bash
+sudo systemctl restart deepracer-timer.service
+```
+
+### Configuration Options
+
+- **dremUrl**: The DREM server URL (set automatically during activation)
+- **port**: HTTP/WebSocket server port (default: 8080)
+- **gpio.sensor1**: BCM GPIO number for first sensor (default: 17, physical pin 11)
+- **gpio.sensor2**: BCM GPIO number for second sensor (default: 27, physical pin 13)
+- **gpio.debounceMs**: Debounce time in milliseconds per sensor (default: 2000)
+
+### Adjusting Debounce
+
+If you experience:
+
+- **Missed laps**: Decrease `debounceMs` (e.g., 1500ms)
+- **False triggers**: Increase `debounceMs` (e.g., 3000ms)
+
+The debounce is applied per sensor independently, preventing a sensor from triggering multiple times within the configured window.
+
+### GPIO Pin Mapping
+
+The default configuration uses:
+
+- **Sensor 1**: GPIO17 (Physical pin 11)
+- **Sensor 2**: GPIO27 (Physical pin 13)
+
+These match the hardware setup described in this guide. Only change these if you've wired the sensors to different GPIO pins.
+
+## Troubleshooting
+
+### Check which GPIO library is being used
+
+View the service logs to confirm `node-libgpiod` loaded successfully:
+
+```bash
+sudo journalctl -u deepracer-timer.service -f
+```
+
+Look for lines like:
+
+- `Using node-libgpiod (modern GPIO library - requires kernel > 6.x)` — expected on all Bookworm installs
+- `Using rpi-gpio (legacy GPIO library - requires kernel < 6.x)` — only on very old OS images, not recommended
+
+### Timing accuracy verification
+
+The timer logs each lap with:
+
+- Timestamp in milliseconds
+- GPIO pin that triggered
+- Per-sensor lap count
+
+Example log output:
+
+```
+15: Lap triggered - GPIO17 at 1709845234567 (2024-03-07T16:13:54.567Z)
+```
+
+### Common issues
+
+**No laps detected:**
+
+1. Check sensor calibration (see Calibration section)
+2. Verify GPIO connections
+3. Check service status: `sudo systemctl status deepracer-timer.service`
+
+**Multiple laps from single trigger:**
+
+1. Increase debounce time in config
+2. Check pressure sensor placement
+
+**WebSocket connection issues:**
+
+1. Verify Pi is accessible on port 8080
+2. Check firewall settings: `sudo ufw status`
+
 ## Developers
 
 When updating the code please create a new `leaderboard-timer.zip` file to make this easier to setup - Thank you.
 
 From the parent directory:
 
 ```
-zip -r website/public/leaderboard-timer.zip leaderboard-timer -x "*.git*" -x "*node_modules*" -x "*stl*" -x "*.DS_Store"
+zip -r website/public/leaderboard-timer.zip leaderboard-timer -x "*.git*" -x "*node_modules*" -x "*stl*" -x "*.DS_Store" -x "*package-lock.json"
 ```
diff --git a/leaderboard-timer/package.json b/leaderboard-timer/package.json
@@ -1,14 +1,20 @@
 {
   "name": "summit-timer",
-  "version": "1.0.0",
-  "description": "",
+  "version": "2.0.0",
+  "description": "DeepRacer automated timing solution with Raspberry Pi 5 support",
   "main": "timer.js",
   "author": "",
   "license": "ISC",
   "dependencies": {
-    "http": "0.0.1-security",
     "http-proxy": "^1.18.1",
-    "rpi-gpio": "^2.1.7",
-    "ws": "^8.5.0"
-  }
-}
+    "ws": "^8.19.0"
+  },
+  "optionalDependencies": {
+    "node-libgpiod": "^0.6.0",
+    "rpi-gpio": "^2.1.7"
+  },
+  "engines": {
+    "node": ">=18.0.0"
+  },
+  "recommendedNode": "20.x LTS"
+}