Configuration#
Everything you can change, and where. Build-time options live in idf.py menuconfig under OBD Logger Configuration. Run-time options come from files on the SD card and from the BOOT button.
SD card files#
The board writes everything under /sdcard/obd/.
File |
What it is |
|---|---|
|
one row per OBD poll cycle, 88 columns (see below) |
|
one line per model run (see below) |
|
one row per closed 10 s pattern window |
|
raw hex of supported PIDs the firmware has no decoder for |
|
session metadata: adapter, VIN, supported PIDs, trouble codes, counters |
|
the k-means pattern model, kept across drives |
|
Wi-Fi networks to import (you create it) |
|
settings to import (you create it) |
|
up to 8 custom PIDs (you create it) |
|
the time at the last save, so the clock can resume after a power cut |
A new session starts at every power cycle. Everything is flushed to the card at least every 10 seconds (SDLOG_SYNC_PERIOD_S). The newest save line on page 3 shows live whether you can cut the power (main/power_state.c): green “Safe to turn off” once no car data has arrived for 5 seconds, the last of it is on the card and no upload is running, and red “Not safe: logging”, “Not safe: saving” or “Not safe: upload” until then. The AI model runs once per row of car data, so it has stopped by the time the line turns green.
Wi-Fi networks#
Wi-Fi sets the clock and, once the board is paired with the desktop app, carries new drive data to it. The desktop app can write these files for you. To do it by hand, put a file called wifi.csv in /sdcard/obd/ with one network per line:
My Home Wifi,my-wifi-password
-Old Network Name
A line that starts with a minus sign forgets that network. The board imports the file at boot and then deletes it. It keeps up to 8 networks in flash (NVS), and the passwords are stored there in plain text. The ESP32-S3 has a 2.4 GHz radio only. If no network is known, the board writes wifi.example.csv as a template, and Wi-Fi stays off.
The board connects only while parked. It scans, connects, reads the time, stays connected for 30 seconds, disconnects, and tries again every 6 hours. Until the clock has been set it scans every 20 seconds. Once paired with the desktop app, it stays connected while parked and looks for the network again 20 seconds after losing it. It never scans or connects while the OBD link is up. All of these times are settings in the Wi-Fi clock sync menu.
The clock#
The board has no battery for its clock. Every save writes the time to /sdcard/obd/clock.txt. After a power cut the clock resumes from that file, behind by the time the car was off, and the screen shows it in amber until the next Wi-Fi sync corrects it. Each session JSON says where its time came from in the clock field: https (set over Wi-Fi from the time server; sntp in versions before 2.5.0), rtc (kept through a reset), resumed (from the card, an estimate) or unset. Rows also carry uptime_ms, and time_sync in the JSON maps uptime to real time, so a session can be re-timed once the clock was corrected.
Setup over USB with the desktop app#
With the desktop app, the SD card can stay in the board. The app talks to it over the USB cable through an authenticated door (main/usb_door.h), prepares everything itself, and sends the board only finished values to store or apply:
Pairing: the first time, the board shows a 6-digit code on its screen and you type it into the app (3 tries per code, a new code at most every 5 seconds). The app then sends its address, port, certificate and token. Later connections prove themselves with an HMAC of a fresh random challenge, keyed with that token: the app computes this code itself, and the board answers nothing else until it is right. The screen code only pairs: after it, the board accepts PAIR and nothing more.
Wi-Fi networks, the time zone and the settings in the table below.
Reading the session files from the card, so drives can be imported over the cable.
Flashing: the app carries the matching firmware image and Espressif’s
esptool. Flashing keeps the Wi-Fi networks and the pairing, which live in a separate flash partition.
The board refuses all of this while the car link is up. In 2.5.0 the board sends no drive data over Wi-Fi: import drives over the USB cable. Wi-Fi only sets the clock, with one HTTPS request to the time server (time_host in config.json, or Time server on the app’s Board page; default www.google.com, "" for the default). The server’s certificate must chain to a trusted root and name that host, and a time outside 2026 to 2099 is refused.
The card files below (wifi.csv, config.json, custom_pids.csv) still work for anyone who prefers them.
config.json#
Put a file called config.json in /sdcard/obd/ and reboot. The board applies the keys it knows and stores them in flash. It does not delete the file, so remove any wifi entries once they are imported.
Key |
Meaning |
Range |
|---|---|---|
|
pause between polling cycles |
50 to 5000 |
|
poll slow-changing PIDs every N cycles |
1 to 50 |
|
read the warning light and trouble codes every N seconds |
10 to 3600 |
|
screen brightness |
5 to 100 |
|
0 by time of day, 1 dark, 2 light |
0 to 2 |
|
light theme from the start hour until the end hour, local time. The defaults, 6 and 17, give light from 06:00 to 16:59 and dark from 17:00 |
0 to 23 |
|
the board’s local time zone as a POSIX string, for example |
text, 3 to 47 characters |
|
the one HTTPS server the board asks for the time (2.5.0). It must present a valid certificate for this name. |
host name, 4 to 63 characters, no scheme, port or IP |
|
|
text |
|
list of |
|
|
the text of |
|
|
a number you can use to track versions |
Files larger than 4096 bytes and invalid JSON are ignored, and the board logs a warning event.
Custom PIDs#
Create custom_pids.csv next to the other files. The board writes custom_pids.example.csv the first time it runs, with the format. Up to 8 rows are logged as custom_1 to custom_8 and shown on page 3. Each row has a mode and PID, a description, a minimum and maximum, a unit, a formula over the response bytes (A, B, C and so on) and an optional header.
Session CSV columns#
The header is the CSV_HEADER string in main/sdlog.c, 92 columns in this order:
seq,uptime_ms,epoch_ms70 PID columns, from
fuel_sys1_statustoodometer_km, in the order ofOBD_FIELDSinmain/obd_fields.hadapter_voltage_v,mil_on,dtc_count,dtcs,pending_dtcs,permanent_dtcscustom_1tocustom_8fuel_lph_calc,fuel_src,trip_km,trip_fuel_l: the fuel rate in L/h, where it came from (pid,maf,modelor empty), and the drive’s distance and fuel so far. Economy istrip_km / trip_fuel_lin km/Lwindow_seq, the number of the pattern window the row belongs to
Fields the car does not support stay empty. epoch_ms is 0 until the clock has been set. schema/obd_log_schema.json describes the same columns.
Model results file#
sNNNNNN.ml.csv has these columns: window_seq, start_ms, end_ms, model, manoeuvre, p_stopped, p_braking, p_accelerating, p_cruising, est_brake_pressure_bar, est_flywheel_torque_nm, est_fuel_rate_lph, latency_us, queue_ms. The model column holds the first 12 hex digits of the model file’s hash, so every answer can be traced to the exact weights. window_seq counts model runs. To join an answer to the raw rows, use start_ms and end_ms against uptime_ms.