Settings¶
Every feature of WiCAN is a component with its own settings document. One set of routes reads, writes, describes, backs up and restores all of them.
| Route | Method | What it does |
|---|---|---|
/api/settings |
GET | Lists every component with its document version, whether it is running on fallback defaults (degraded) and whether a saved change waits for a reboot (pending_reboot). |
/api/settings/<name> |
GET | One component's current document, plus degraded and pending_reboot. Passwords and keys read as "". |
/api/settings/<name> |
PUT | Replaces the whole document. Validated first: a rejected document answers 400 with the reason and nothing is saved. Accepted = persisted, waiting for the submit. |
/api/settings/<name>/schema |
GET | The JSON Schema of that document: field names, types, ranges, enumerations, defaults. The web interface builds its forms from it. |
/api/settings/submit |
POST | Ends a batch of PUTs: answers {"reboot":true} and reboots when any PUT changed something, {"reboot":false} and stays up when nothing changed. |
/api/settings/backup |
GET | The whole configuration as one document, passwords included. Treat the file as sensitive. |
/api/settings/backup |
POST | Restores a backup, all or nothing: every component is validated first (older documents are migrated), 400 with per-component errors otherwise. Unknown components are skipped and reported. Reboots when something changed. |
/api/settings/factory_reset |
POST | Wipes the settings partition to factory defaults. Needs {"confirm":"factory-reset"}, 400 otherwise and nothing happens. Files under /data, the SD card and the Bluetooth bonds are untouched. Reboots. |
The model¶
GET /api/settings/<name>and keep the document.- Change the fields you want and
PUTthe whole document back. The device checks it and answers 400 with a message if a value is out of range. - Repeat for other components if needed.
POST /api/settings/submit. The device reboots once for all the changes together; the answer tells you whether it will.
A document that was PUT but not submitted shows "pending_reboot":true on its next GET. The two helper fields degraded and pending_reboot are read-only; a PUT that echoes them back is fine, they are stripped.
curl http://192.168.1.23/api/settings/led_manager
curl -X PUT -H "Content-Type: application/json" -d @led.json http://192.168.1.23/api/settings/led_manager
curl -X POST http://192.168.1.23/api/settings/submit
Passwords
A GET shows "" where a password or key is stored. Send "" back and the stored value stays. Send a new value and it is replaced. The only route that returns secrets is the backup.
The components¶
{
"components": [
{
"name": "log_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "dev_status_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "restart_tracker",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "external_storage",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "filesystem",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "http_server_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "wifi_manager",
"version": 7,
"degraded": false,
"pending_reboot": false
},
{
"name": "obd_gate",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "obd_chip",
"version": 3,
"degraded": false,
"pending_reboot": false
},
{
"name": "ble_manager",
"version": 4,
"degraded": false,
"pending_reboot": false
},
{
"name": "socket_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "websocket_manager",
"version": 2,
"degraded": false,
"pending_reboot": false
},
{
"name": "log_sinks",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "bridge_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "can_manager",
"version": 2,
"degraded": false,
"pending_reboot": false
},
{
"name": "j1939",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "uds_manager",
"version": 2,
"degraded": false,
"pending_reboot": false
},
{
"name": "script_engine",
"version": 2,
"degraded": false,
"pending_reboot": false
},
{
"name": "led_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "rtc_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "imu_manager",
"version": 3,
"degraded": false,
"pending_reboot": false
},
{
"name": "battery_monitor",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "mdns_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "mqtt_manager",
"version": 2,
"degraded": false,
"pending_reboot": false
},
{
"name": "mqtt_can",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "vpn_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "iperf_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "sleep_manager",
"version": 4,
"degraded": false,
"pending_reboot": false
},
{
"name": "usb_host_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "usb_acm_cli",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "espnetlink",
"version": 2,
"degraded": false,
"pending_reboot": false
},
{
"name": "j2534_server",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "ble_http",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "cmdline_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "button_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "interface_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "event_manager",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "autopid",
"version": 8,
"degraded": false,
"pending_reboot": false
},
{
"name": "ha_webhooks",
"version": 2,
"degraded": false,
"pending_reboot": false
},
{
"name": "data_destinations",
"version": 1,
"degraded": false,
"pending_reboot": false
},
{
"name": "data_logger",
"version": 2,
"degraded": false,
"pending_reboot": false
}
]
}
Each name is a settings document you can GET and PUT. The important ones for a user:
| Component | What it holds |
|---|---|
wifi_manager |
WiFi mode, the access point, your networks and their trust, fallbacks |
ble_manager, ble_http |
Bluetooth LE on or off, passkey, bonding, PHY and advertising, the HTTP tunnel |
mqtt_manager, mqtt_can |
the MQTT broker, the topic prefix, CAN over MQTT gates |
autopid |
the vehicle data loop: on or off, standard and custom PIDs, trouble code scanning |
data_destinations |
cyclic pushes to MQTT, HTTP endpoints and ABRP |
data_logger |
the SD card logger: formats, rotation, what to log |
sleep_manager |
sleep and wake voltages, delays |
can_manager, j1939, uds_manager, j2534_server |
the native CAN bus, the J1939 listener, the UDS terminal, the PassThru server |
usb_host_manager, usb_acm_cli, espnetlink |
the USB connector and the accessories on it |
led_manager, button_manager |
the LED's idle colour, the button |
event_manager |
the Automate rules and timers |
interface_manager |
which radio wins when two want to be up |
log_manager, log_sinks |
log levels and where logs go |
A document and its schema¶
wifi_manager as the bench device returns it (secrets blank):
{
"mode": "sta",
"sta_ssid": "WICAN_TEST_AP",
"sta_password": "",
"sta_trusted": true,
"hostname": "",
"sta_auto_reconnect": true,
"sta_max_retry": -1,
"sta_ip_mode": "dhcp",
"sta_static_ip": "",
"sta_static_netmask": "255.255.255.0",
"sta_static_gw": "",
"sta_dns": "",
"fallback1_ip_mode": "dhcp",
"fallback1_static_ip": "",
"fallback1_static_netmask": "255.255.255.0",
"fallback1_static_gw": "",
"fallback2_ip_mode": "dhcp",
"fallback2_static_ip": "",
"fallback2_static_netmask": "255.255.255.0",
"fallback2_static_gw": "",
"fallback3_ip_mode": "dhcp",
"fallback3_static_ip": "",
"fallback3_static_netmask": "255.255.255.0",
"fallback3_static_gw": "",
"fallback4_ip_mode": "dhcp",
"fallback4_static_ip": "",
"fallback4_static_netmask": "255.255.255.0",
"fallback4_static_gw": "",
"fallback5_ip_mode": "dhcp",
"fallback5_static_ip": "",
"fallback5_static_netmask": "255.255.255.0",
"fallback5_static_gw": "",
"fallback1_ssid": "ESPNetLink_894A5D",
"fallback1_password": "",
"fallback1_trusted": true,
"fallback2_ssid": "ESPNetLink_457FED",
"fallback2_password": "",
"fallback2_trusted": true,
"fallback3_ssid": "",
"fallback3_password": "",
"fallback3_trusted": true,
"fallback4_ssid": "",
"fallback4_password": "",
"fallback4_trusted": true,
"fallback5_ssid": "",
"fallback5_password": "",
"fallback5_trusted": true,
"ap_ssid": "",
"ap_password": "",
"ap_channel": 6,
"ap_max_connections": 4,
"ap_auto_disable": false,
"ap_ip": "192.168.0.10",
"ap_hidden": false,
"ap_bandwidth": "ht20",
"ap_auth": "auto",
"power_save": "none",
"sta_roam_interval_s": 300,
"wifi_ram_profile": "lean",
"wifi_static_rx": 10,
"wifi_static_tx": 8,
"wifi_cache_tx": 32,
"cli": true,
"degraded": false,
"pending_reboot": false
}
The schema says what each field may hold. A client that reads it can build a form or validate before sending:
{
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"off",
"sta",
"ap",
"apsta"
],
"default": "apsta"
},
"sta_ssid": {
"type": "string",
"maxLength": 32,
"default": ""
},
"sta_password": {
"type": "string",
"maxLength": 64,
"default": ""
},
"sta_trusted": {
"type": "boolean",
"default": true
},
"hostname": {
"type": "string",
"maxLength": 32,
"default": ""
},
"sta_auto_reconnect": {
"type": "boolean",
"default": true
},
"sta_max_retry": {
"type": "integer",
"minimum": -1,
"maximum": 1000,
"default": -1
},
"sta_ip_mode": {
"type": "string",
"enum": [
"dhcp",
"static"
],
"default": "dhcp"
},
"sta_static_ip": {
"type": "string",
"maxLength": 15,
"default": ""
},
"sta_static_netmask": {
"type": "string",
"maxLength": 15,
"default": "255.255.255.0"
},
Backup and restore¶
curl http://192.168.1.23/api/settings/backup > wican-backup.json
curl -X POST -H "Content-Type: application/json" --data-binary @wican-backup.json http://192.168.1.23/api/settings/backup
The backup holds every component as {version, data} plus the device's identity. A restore validates everything before it writes anything, migrates documents from an older firmware, and reboots when the restored settings differ from the running ones. The file contains the WiFi and broker passwords: keep it private.
Factory reset¶
curl -X POST -H "Content-Type: application/json" -d "{\"confirm\":\"factory-reset\"}" http://192.168.1.23/api/settings/factory_reset
Only the settings partition is wiped. Vehicle tables, scripts and other files under /data, the SD card and the Bluetooth bonds stay. The device comes back with the factory access point password and opens Quick Setup.