USB, Wi-Fi and version#

Every function each header declares, with the comment the header gives it. The header’s own opening comment is shown as written in the source.

usb_door.h#

Source: main/usb_door.h

Authenticated setup door on the USB cable, used by the OpenCarMind desktop app so nobody has to open the SD card.

Every line the app reads starts with "OCM1 "; log lines share the cable and are ignored by the app.
  OCM1 HELLO                       -> OCM1 OK HELLO nonce=<32 hex>   (nothing else about the board)
  OCM1 AUTH-HMAC <64 hex>          the door's code, computed by the desktop tools: HMAC-SHA256 of the HELLO nonce keyed
                                   with the paired app's token (one try per HELLO)
                                   -> OCM1 OK AUTH fw=<version> board=<mac> paired=1
Pairing a new computer (someone at the board):
  OCM1 CODE                        shows a 6-digit code on the board's screen for 2 minutes
  OCM1 AUTH-CODE <code>            3 tries per code -> OCM1 OK AUTH pair-only: PAIR is then the only command accepted,
                                   and a successful PAIR opens the session (the computer holds the token it sent)
After AUTH-HMAC (10 minutes idle closes the session):
  OCM1 PAIR <host> <port> <token> <cert PEM in base64>    OCM1 UNPAIR
  OCM1 WIFI-LIST | WIFI-ADD <ssid b64> [password b64] | WIFI-FORGET <ssid b64>
  OCM1 CONFIG <config.json in base64>                      same keys as /sdcard/obd/config.json
  OCM1 LIST                        -> OCM1 D <name> <size> per session file
  OCM1 GET <name> <offset> <len>   -> OCM1 D <base64 of up to 3072 bytes>
  OCM1 MODEL GET                   -> OCM1 OK MODEL active=<ev|rev> available=ev,rev loaded=<0|1> learning=<0|1> run_us=<n>
  OCM1 MODEL SET <ev|rev>          switch the on-board model (unload, load, kept in NVS); same answer as MODEL GET
  OCM1 REV-STATUS                  -> OCM1 D <group> key=value ... (state, fuel, error, phys, cal, life, one iv per interval)
  OCM1 REV-FILLUPS <json b64>      the whole fill-up list: {"rev":n,"entries":[{"id","after","litres","full"} or
                                   {"id","kind":"trip","from","after","l100"}]} -> OCM1 OK REV-FILLUPS rev= cal= used= skipped=
  OCM1 REV-RESET <fuel|phys|cal|all>
  OCM1 REBOOT
Answers end with "OCM1 OK ..." or "OCM1 ERR <reason>". Anything that changes the board or reads the card is refused
while the car link is up.

Function

Comment in the header

void usb_door_start(void);

wifi_sync.h#

Source: main/wifi_sync.h

Function

Comment in the header

esp_err_t wifi_sync_start(void);

Starts the Wi-Fi clock sync: a short station connection to a known network (wifi.csv on the SD card, NVS, or the Kconfig fallback) to set the clock over SNTP. Nothing is sent to or stored on any server. A no-op when no network is known.

bool wifi_sync_connected(void);

bool wifi_sync_connect_now(void);

Try the known networks now instead of at the next scheduled scan (the same scan, connect and clock sync). False when no network was known at boot or Wi-Fi is compiled out.

esp_err_t wifi_sync_start_held(void);

app_main on the S31, in place of wifi_sync_start() (os_hooks.h OCM_WIFI_BOOT_START): loads the saved networks and starts nothing else, no netif, no driver, no Wi-Fi task (the mossREV 2.0.0 boot hold)

uint32_t wifi_sync_clock_refusals(void);

R6 refusals of a clock jump so far this boot (the Health app’s guard counts)

void wifi_sync_started(void);

app_main, right after the start: from now on the functions below may start the radio themselves

bool wifi_sync_up(void);

The owner’s start from the screen (Sync clock now, the Wi-Fi app’s search and join): bring the station up and start the Wi-Fi task, whatever the boot health verdict. False when Wi-Fi could not start (internal RAM) or app_main has not reached wifi_sync_started() yet.

void wifi_sync_boot_release(void);

os.c, once the boot health verdict is formed: the automatic start (the Wi-Fi task and its first clock round), only if os_wifi_may_start(verdict, false) allows it; a no-op when nothing is saved or the owner started it already

int wifi_sync_scan(wifi_seen_t *out, int max);

One active scan, strongest first, hidden networks left out. Waits up to 3 s for the Wi-Fi task to finish a round. Returns the count, or -1 (busy, driving, or the radio could not start).

bool wifi_sync_join(const char *ssid, const char *password, void (*done)(int result, void *ctx), void *ctx);

Join: the Wi-Fi task saves the network (wifi_creds, the WIFI-ADD store and rules; password NULL keeps the saved one), connects once, and on success sets the clock (the normal clock sync). done(result, ctx) runs in the Wi-Fi task with a wj_result_t (wifi_ui_logic.h). A wrong password does not stay saved: a new network is removed again, an old one gets its old password back. False when a join is already waiting (done is not called then).

int wifi_sync_forget(const char *ssid);

Forget a saved network unless the Wi-Fi task holds a pointer into the list (a round running): 1 forgotten, 0 not saved, -1 busy. The screen’s Forget and the USB door’s WIFI-FORGET both go through here.

int wifi_sync_add(const char *ssid, const char *password);

the door’s WIFI-ADD under the round lock: 1 ok, 0 rejected, -1 busy

wifi_creds.h#

Source: main/wifi_creds.h

Known Wi-Fi networks, stored in NVS, imported from /sdcard/obd/wifi.csv (one "ssid,password" per line). They are used
only to set the clock over SNTP (wifi_sync.c). The file is deleted after a successful import so the card does not
carry the password around; NVS holds it in plain text, readable by anyone with physical access to the flash.

Function

Comment in the header

size_t wifi_creds_load(void);

NVS + optional Kconfig fallback + SD import; returns count

size_t wifi_creds_count(void);

wifi_cred_t *wifi_creds_get(size_t i);

wifi_cred_t *wifi_creds_find(const char *ssid);

bool wifi_creds_add(const char *ssid, const char *password);

add or update, persists

bool wifi_creds_remove(const char *ssid);

void wifi_creds_dedupe(const char *good_ssid);

After a successful connection: remove entries that differ from this SSID only by case or spacing (typically a mistyped copy of the same network).

version.h#

Source: main/version.h