Generated page. Written from IdaMilk/forklift-crash-detector at commit 6fb630d on 2026-07-28.
Forklift Crash Detector
What is it?
A proof-of-concept impact detection system for warehouse forklifts. Each forklift carries a Seeed Studio XIAO ESP32-S3 with a LIS3DHTR accelerometer; when an impact is detected, the device POSTs a waveform payload over WiFi to a FastAPI server that persists events and serves a dashboard.
Ten units, per the bill of materials.
Purpose
Forklift impacts damage racking, product and occasionally people, and they are systematically under-reported — the operator who clips a rack has every incentive not to mention it.
Instrumenting the truck removes that dependency. The waveform matters as much as the count: it distinguishes a genuine collision from a hard set-down or a bump over a threshold, which is what makes the data credible enough to act on.
How it Works
[ESP32-S3 × 10] ── WiFi HTTP ──▶ [FastAPI server] ──▶ [SQLite]
LIS3DHTR @400Hz POST │
rolling baseline /api/events dashboard +
ring buffer /api/heartbeat waveform review
offline queue /api/forklifts
The firmware samples the accelerometer at 400 Hz into a ring buffer while maintaining a rolling baseline. When a reading exceeds the threshold relative to that baseline, the device has the preceding samples already captured — so the payload contains the lead-up to the impact, not just the moment it was noticed. Sampling continuously and keeping only what matters is the standard approach here, and the right one.
An offline queue handles the WiFi dead spots any warehouse has: events are held on the device and sent when coverage returns, rather than lost.
Heartbeats let the server distinguish "this forklift had no impacts" from "this forklift stopped reporting" — without them, a dead unit looks like a safe one.
API
| Endpoint | Purpose |
|---|---|
POST /api/events | Impact event with waveform |
POST /api/heartbeat | Device liveness |
GET /api/forklifts | Fleet status |
The server also serves the HTML dashboard and renders waveforms for review.
Hardware
| Part | Role |
|---|---|
| Seeed Studio XIAO ESP32-S3 | Microcontroller with WiFi |
| Grove Base for XIAO | Carrier board |
| Grove 3-Axis Digital Accelerometer (LIS3DHTR) | Impact sensing |
All three connect with a single Grove I2C cable — no soldering, which matters for a ten-unit build maintained by non-specialists.
Tech Stack
| Layer | Technology |
|---|---|
| Firmware | C++ / Arduino via PlatformIO |
| Server | Python, FastAPI |
| Database | SQLite |
| Dashboard | Server-rendered HTML |
| Tests | pytest |
Documentation
Better documented than most of the organisation:
| Document | Covers |
|---|---|
docs/ARCHITECTURE.md | System design |
docs/SETUP.md | Deployment |
docs/TUNING.md | Impact threshold tuning |
docs/CAMERA_SETUP.md | Camera integration |
ROADMAP.md | Planned work |
docs/TUNING.md is the one that matters operationally — threshold tuning is the difference between catching real impacts and drowning in false positives from ordinary rough floors.
Operations
Proof of concept, not production. Impact thresholds need tuning per site, and WiFi coverage across the warehouse determines how much the offline queue is exercised.
forklift.db is committed to the repository. For a proof of concept that is convenient — it ships with sample data — but it means test event data is in git history, and the same file being the live database in a deployment would be a mistake worth avoiding.
Repository
| Repository | IdaMilk/forklift-crash-detector |
| Primary language | Python (server), C++ (firmware) |
| Files | 67 |
| Last activity | 2026-05-12 |
| Status | Proof of concept |
One of only two Python projects in the organisation, alongside Ninja-Wazuh Dashboard, and the only one with embedded firmware.