DriftNet Documentation
Everything you need to know about setting up and using your street sensor array.
What is DriftNet?
DriftNet is an array of ESP32 sensor nodes placed along your property line. Each node scans for Bluetooth and WiFi signals from passing devices (phones, wearables, AirTags, cars with Bluetooth, etc.). By detecting the same device at multiple nodes and measuring the time difference, DriftNet calculates:
- Speed — how fast something is moving past your house
- Direction — which way it's going
- Device type — phone, wearable, vehicle, etc.
- Patterns — who passes regularly, what times are busiest
Optional add-ons include a camera (captures photos of passing vehicles), microphone (detects loud noise events), weather correlation, and AI-powered analysis.
Getting Started
You need three things to get DriftNet running:
- ESP32 dev boards — any ESP32 board works (DevKit V1, NodeMCU-32S, Wemos D1 Mini ESP32, etc.). You need at least 2 for speed detection.
- USB power — each node needs power. USB cable to a wall outlet, battery pack, or solar panel.
- WiFi — your home WiFi network. Each node connects to report data.
Minimum setup: 2 ESP32s, 2 USB cables, 2 power sources (outlets/battery packs), and your home WiFi password. That's it.
One-Time Firmware Flash
The firmware needs to be loaded onto each ESP32 once. After that, everything is managed from this dashboard (including future firmware updates over WiFi).
2 Plug the ESP32 into your computer via USB
3 Open a terminal in the firmware/ folder and run: pio run -t upload
4 Done. Unplug it. That board is ready. Repeat for each ESP32.
Same firmware for every node. You don't edit any files or change any settings per board. The firmware is identical on all of them. Each node gets its unique identity through the dashboard setup wizard.
Adding a Node
After the firmware is flashed, here's how you set up each node — entirely from the dashboard and your phone:
1 Plug in the ESP32 where you want it (along your property line, facing the street). The LED will blink rapidly then pulse slowly — that means it's in setup mode.
2 Go to
Nodes and click
"+ Add Node"
3 Name it (e.g., "node-01"), set its position number (0 = first, 1 = second, etc.) and distance from the first node in feet
4 You'll get a 6-digit setup code. Keep this screen open.
5 On your phone, go to WiFi settings and connect to "DriftNet-Setup" (no password)
6 A setup page opens automatically. Pick your home WiFi from the dropdown, enter the password, and enter the 6-digit code
7 Hit "Connect Node". It configures itself and reboots. Reconnect your phone to your home WiFi.
8 Back on the dashboard, the wizard will show "Node is Online!" within about 30 seconds
Setup code expires in 15 minutes. If it expires, just click "Re-setup" on the node to get a new code.
How Many Nodes?
- 2 nodes — minimum for speed detection. Basic but works.
- 4-6 nodes — good accuracy, catches most passes. Recommended starting point.
- 8-12 nodes — high accuracy, very few missed detections. Best for busy streets.
- 12+ — diminishing returns for speed, but useful for very long property frontage.
Space them 8-12 feet apart. Closer = more accurate speed readings. Further = covers more of the street.
Placement Tips
- Mount at waist to chest height (3-5 feet). BLE range is about 30-50 feet.
- Zip-tie to fence posts, porch railings, garden stakes, or tree trunks.
- Keep them dry — a small plastic container (food storage, etc.) with a hole for the USB cable works great.
- The antenna is on the PCB — don't wrap in metal foil. Plastic/wood is fine.
Hardware You Need
Sensor Nodes (Required)
| Item | Recommended | Price | Notes |
|---|
| ESP32 boards |
ESP32-S3-DevKitC-1 (USB-C) |
~$10 ea |
Best BLE 5.0 range + USB-C. Get 8-10 boards. Alternative: ESP32-WROOM-32D DevKit V1 (~$6 ea, Micro-USB, slightly less BLE range). |
| USB cables |
10ft USB-C (or Micro-USB) |
~$8/5-pack |
Match your board's port. 10ft gives enough reach from outlets to mounting points. |
| Power (outlet) |
5V 1A USB wall chargers |
~$12/5-pack |
One per node if you have outdoor outlets or can run extension cords. |
| Power (battery) |
Anker 10,000mAh USB-A pack |
~$20 ea |
~3 days runtime per charge. Swap and recharge. Good for initial testing. |
| Enclosures |
IP67 junction box 3.3"x2.3"x1.3" |
~$10/5-pack |
Drill one hole for USB cable, seal with silicone or hot glue. Keeps rain/snow out. |
| Mounting |
UV-resistant zip ties 12" |
~$6/100-pack |
Attach enclosures to fence posts, porch railings, garden stakes, tree trunks. |
Camera System (Optional)
| Item | Recommended | Price | Notes |
|---|
| Camera computer |
Raspberry Pi 4 (2GB) |
~$55 |
Runs 24/7 on 5W. Also runs the mic service. Alternative: any spare laptop/desktop. |
| Camera module |
Raspberry Pi Camera Module v3 |
~$25 |
12MP, autofocus, wide-angle. Connects via ribbon cable. Points out window toward street. |
| Camera alt |
Logitech C920 HD webcam |
~$50 |
USB webcam option if using a laptop instead of RPi. 1080p, good low-light. |
| RPi power |
Official RPi USB-C power supply |
~$8 |
5V 3A. Don't use a cheap one — RPi is picky about power. |
| RPi storage |
32GB microSD card |
~$8 |
For Raspberry Pi OS. Captures upload to cloud (B2), not stored locally. |
Microphone (Optional)
| Item | Recommended | Price | Notes |
|---|
| USB mic |
Any USB condenser mic |
~$15 |
Plugs into the RPi. Place near a window facing the street. No special model needed. |
| I2S mic alt |
INMP441 I2S MEMS breakout |
~$5 |
Wires directly to an ESP32 (standalone noise node). Tiny. Very sensitive. |
Permanent Outdoor (Optional)
| Item | Recommended | Price | Notes |
|---|
| Solar panel |
6W 5V USB solar panel |
~$15 ea |
Pair with a 3000-5000mAh LiPo battery + charging board for indefinite outdoor runtime. |
| LiPo battery |
3.7V 3000mAh LiPo cell |
~$8 ea |
Used with a TP4056 charging board between solar panel and ESP32. |
| Charge board |
TP4056 USB LiPo charger + protection |
~$6/5-pack |
Solar in, LiPo charge management, 5V out to ESP32. Handles day/night cycling. |
| Outdoor cable |
Outdoor-rated USB extension 15ft |
~$10 ea |
Run power from house outlets to distant nodes. UV-resistant jacket. |
Budget Estimates
Minimum viable (2 nodes, no camera): 2x ESP32 + 2x battery packs + zip ties = ~$58
Recommended (8 nodes + camera + mic): 8x ESP32-S3 + enclosures + power + RPi + camera + mic = ~$225
Full permanent (8 nodes solar + camera): Add solar panels + LiPo + charge boards = ~$330
What NOT to Buy
- ESP32-S2 — has WiFi but NO Bluetooth. Will not work with DriftNet.
- ESP8266 / NodeMCU v2 — no Bluetooth at all. Wrong chip entirely.
- Arduino Uno/Nano — no WiFi, no Bluetooth. Not compatible.
- Metal enclosures — blocks WiFi and Bluetooth signals. Use plastic only.
Board Compatibility
| Board | Works? | Notes |
|---|
| ESP32-WROOM-32D DevKit V1 | Yes | Best tested. Micro-USB. Cheapest option. |
| ESP32-S3-DevKitC-1 | Yes | Recommended. BLE 5.0, USB-C, better range. |
| ESP32-C3-DevKitM-1 | Yes | Works but single-core — slightly less scanning throughput. |
| NodeMCU-32S | Yes | Common and cheap. Micro-USB. |
| Wemos D1 Mini ESP32 | Yes | Compact form factor. Good for tight enclosures. |
| ESP32-S2 | No | No Bluetooth. WiFi only. |
| ESP8266 / NodeMCU v2 | No | No Bluetooth. Wrong chip. |
| Arduino Uno/Nano | No | No WiFi or Bluetooth. |
Dashboard Pages
Live
The speed gun. Shows the most recent pass with a giant speed readout, direction, device type, and a scrolling feed of recent passes. Real-time via WebSocket — no need to refresh.
History
Filter and search all recorded passes. Speed-over-time chart, activity heatmap (busiest hours by day of week), and a filterable table. Supports date range, direction, category, and speed filters.
Regulars
Devices that pass frequently. Click any device to see its full pass history, average speed, and typical times. Label devices with names ("Mike's iPhone", "Blue Tesla") and mark them as known.
Who's Home
Mark devices as "residents" and track who's currently near the array. Shows arrivals/departures timeline. A device is "home" if it's been detected within the last 10 minutes.
Nodes
Sensor array health. Shows each node's status (online/offline), battery, WiFi signal, firmware version. Add new nodes with the setup wizard. Edit, delete, re-provision, or deactivate nodes.
Map
Google Maps satellite view showing node positions and detection coverage zones. Requires a Google Maps API key (set in Settings).
Gallery
Photos captured by the camera service. Searchable by license plate. Each capture is linked to its corresponding pass (speed, direction, device).
Leaderboard
Fastest passes — today, this week, this month, all time. Broken down by category: overall, vehicle, cyclist, pedestrian.
Ask AI
Ask natural language questions about your data. "Anything unusual this week?" "Who are my most frequent passers-by?" Also has CSV export links and the ability to trigger weekly reports on demand.
Settings
Configure everything: location (auto-detect GPS or manual lat/lon), speed limit, noise thresholds, direction labels, report email, map API key.
Camera Setup
The camera service runs on a Raspberry Pi or any computer with a webcam. It connects to DriftNet via WebSocket and captures a photo the instant a pass is detected.
1 Point a camera out your front window toward the street
2 Install dependencies: pip install opencv-python websocket-client requests
3 Run: python camera/capture.py
It will automatically take a photo every time a pass is detected and upload it to the Gallery. Optional: install pytesseract for automatic license plate reading.
Microphone Setup
The noise monitor tracks ambient sound levels and flags loud events (revving engines, honking, music at 2am).
1 Connect a USB microphone to a Raspberry Pi or spare computer
2 Install: pip install pyaudio numpy requests
3 Run: python mic/noise.py
Thresholds are configurable in Settings. Events above the threshold are flagged and shown in the Gallery page's noise events table.
Settings
All configuration is done from the Settings page. No code, no terminal, no config files.
- Location — set your lat/lon for weather and map (or hit "Use My Location" for GPS auto-detect)
- Direction labels — rename "Inbound/Outbound" to "Northbound/Southbound" or whatever matches your street
- Speed limit — the posted limit on your street
- Noise thresholds — dB levels that trigger flags (different for day/night)
- Report email — where weekly summaries go
- Google Maps API key — for the satellite map view
Firmware Updates (OTA)
After the initial USB flash, all future firmware updates happen over WiFi. No need to unplug or reconnect nodes.
- Build new firmware:
pio run (creates a .bin file)
- Upload the
.bin to the API via the Nodes page
- Click "Push Update" — all nodes download and install it on their next heartbeat (within 60 seconds)
Troubleshooting
Node won't connect to WiFi
Hold the BOOT button on the ESP32 for 5 seconds. The LED will flash rapidly and the node resets to setup mode. Connect to "DriftNet-Setup" again and re-enter your WiFi password.
Node shows "OFFLINE" on dashboard
- Check power — is the USB cable connected and the power source on?
- Check WiFi — is your router running? Is the node within WiFi range?
- Factory reset — hold BOOT button 5 seconds, re-provision from dashboard
"DriftNet-Setup" WiFi doesn't appear
The node only creates the setup hotspot when it has no valid config. If it was previously configured, hold BOOT for 5 seconds to clear the config and force setup mode.
Speed readings seem off
- Check node distances in the Nodes page — make sure the distances are accurate
- Ensure node positions are correct (0, 1, 2, 3... in order)
- NTP sync issues can cause timing errors — nodes sync on boot and every hour
Not detecting many devices
Modern phones randomize their Bluetooth MAC addresses. DriftNet uses fingerprinting to track them across nodes, but some devices are harder to fingerprint. This is normal — you'll still catch 80-90% of passing devices.
Setup code expired
Codes last 15 minutes. Click "Re-setup" on the node in the Nodes page to generate a fresh code.
Frequently Asked Questions
Is this legal?▶
DriftNet passively listens for publicly broadcast Bluetooth and WiFi signals on your own property. These signals are broadcast by devices intentionally and are not encrypted communications. Passive scanning of RF signals on your own property is generally legal in the US. The system does not intercept any communication content — it only detects the existence of a signal and measures timing. That said, laws vary by location. If you're concerned, consult a local attorney.
How accurate is the speed measurement?▶
With nodes 10 feet apart and NTP time sync, accuracy is typically within 1-2 mph for vehicles and 0.5 mph for pedestrians. More nodes = more accuracy, because the system averages across multiple node-to-node measurements. The main source of error is NTP clock drift (up to ~100ms), which at 30mph across 10 feet equals roughly 1.5 mph of error.
Can it tell the difference between a car and a person?▶
Yes, by speed and device type. Pedestrians travel 1-4 mph, cyclists 4-15 mph, vehicles 15+ mph. The system also identifies device types from Bluetooth characteristics — an iPhone in someone's pocket vs. a Tesla's built-in Bluetooth are distinguishable.
What about devices that don't have Bluetooth?▶
They won't be detected. A car with no Bluetooth, a cyclist without a phone, or a pedestrian who turned off their phone will be invisible to DriftNet. This system is not 100% traffic counting — it measures what it can see via wireless signals. In practice, the vast majority of people carry a phone.
How long do batteries last?▶
An ESP32 running continuous BLE scanning draws about 130mA. A 10,000mAh battery pack lasts roughly 3 days. A 20,000mAh pack lasts about a week. For permanent installation, use USB wall chargers or 5V solar panels.
What data is stored?▶
Raw detection data (signal captures) is stored for 7 days then automatically deleted. Correlated passes (speed, direction, device type) are stored permanently. Device fingerprints are hashed — the system cannot determine a person's identity from their device signature alone.
Can I use this at a different location?▶
Yes. Change the location in Settings (or hit "Use My Location" for GPS auto-detect). The weather, map, and all other location-dependent features will update. The nodes just need WiFi wherever they are.
What ESP32 boards work?▶
Any ESP32 with WiFi and Bluetooth. The firmware targets the generic "esp32dev" board. Popular choices: ESP32 DevKit V1, NodeMCU-32S, Wemos D1 Mini ESP32, ESP32-WROOM-32. ESP32-S2 will NOT work (no Bluetooth). ESP32-S3 and ESP32-C3 work but may need board setting changes in platformio.ini.
What about rain/snow?▶
ESP32 boards are not waterproof. Put them in a small plastic container (food storage, small tupperware) with a hole drilled for the USB cable. Seal with silicone or hot glue. A small packet of silica gel inside helps with condensation. Bluetooth signals pass through plastic and wood with no issue.
How do I reset a node?▶
Hold the BOOT button (GPIO0) on the ESP32 for 5 seconds. The LED will flash rapidly, then the node clears its config and reboots into setup mode. You'll see the "DriftNet-Setup" WiFi appear again.