Serial CLI Documentation

This document defines all Serial CLI commands, message formats, response codes, and settings parameter codes for the Boondock firmware. This documentation is intended for tools that monitor and parse Serial port messages.

CLI Command Format
Settings Commands
Information Commands
File Management Commands
Message Types and Codes
Settings Parameter Codes

CLI Command Format

Input Format

Commands are sent via Serial at 115200 baud
Commands are case-insensitive (automatically converted to uppercase)
Commands are terminated by newline (\n) or carriage return + newline (\r\n)
Maximum command length: 512 characters
Command echo: All commands are echoed back with > prefix

Response Format

Success: <command_line> OK
Failure: <command_line> FAILED or <command_line> FAILED: <error_message>
Empty value: (empty)
Multi-line responses: Multiple lines followed by <command_line> OK

Command Structure

<COMMAND> [PARAMETER] [VALUE]

Settings Commands

HELP / ?

Format: help or ?

Response:

Commands:
  help                Show this list
  show <setting>      Read a setting (alias: get)
  set <setting> <val> Update a setting
  save                Persist current settings
  load                Reload settings from storage
  export              Print all settings JSON (alias: dumpconfig)
  import <json>       Apply settings JSON payload
  config <json>       Apply settings JSON and show changes (waits for DONE)
  pushsettings        Push full settings to API server
  pullsettings        Pull settings from API server and apply
  autoconfig          Quick configure: SSID,PASSWORD[,HOST_IP,HOST_PORT,TIMEZONE_OFFSET,AUDIO_THRESHOLD,MIN_RECORDING_MS,MAX_RECORDING_MS,PRE_RECORDING_MS]
  reboot              Restart the device
  factoryreset        Erase NVS and reboot (factory reset)
  maintenance         Run maintenance tasks on-demand
  makeindex          Reconcile recordings index file
  pushlogs            Upload latest log file to server
  format              Format SD card (delete all files)
  time                Show device time and uptime
  status              Show device status (storage, memory, WiFi)
  ip                  Show IP address
  mac                 Show MAC address (device ID)
  config              Show device configuration (CSV format)
  recordings          Show recording summary
  audiolevel          Show audio level statistics
  errors              Show recent error messages
  settime <time>      Set device time (UTC ISO format: YYYY-MM-DDTHH:MM:SSZ or epoch)
  reconnect           Reconnect WiFi (pauses uploads, keeps recording)
  recover             Reset API endpoints and resume uploads
  sample              Start recording sample (bypasses threshold, uses min/max)
  health ?            Print health metrics JSON
  config ?            Print configuration JSON
File Management (SD card only):
  cd /                Change to root directory
  cd <dir>            Change to directory
  dir                 List files in current directory (alias: ls, list)
  rm <file>           Remove a file (alias: delete, del)
  rm *                Remove all files in current directory
Shortcuts:
  min/max/silence/gain/sense map to their audio fields
  pre maps to the audio.preRecordMs pre-roll window (0 disables pre-roll)
  hostN targets upload.apiHosts[N] (e.g. host0)
  Per-endpoint: upload.apiPorts[N], upload.enabled[N]
  Wi-Fi: ssidN, passN, staticN, ipN, subnetN, gatewayN, dns1N, dns2N
  All commands/aliases ignore case
<command_line> OK

SHOW / GET / READ

Format: show <setting> or get <setting> or read <setting>

Response:
- Success: Value on one line, then <command_line> OK
- Empty: (empty) then <command_line> OK
- Failure: <command_line> FAILED: Usage: show <setting>

Examples:

> show min
5000
show min OK

> show ssid0
MyWiFi
show ssid0 OK

> show invalid
(empty)
show invalid OK

SET / CHANGE / UPDATE

Format: set <setting> <value> or change <setting> <value> or update <setting> <value>

Response:
- Success: <command_line> OK
- Failure: <command_line> FAILED or <command_line> FAILED: Usage: set <setting> <value>

Examples:

> set min 5000
set min 5000 OK

> set ssid0 MyWiFi
set ssid0 MyWiFi OK

> set invalid
set invalid FAILED: Usage: set <setting> <value>

SAVE / STORE

Format: save or store

Response:
- Success: <command_line> OK
- Failure: <command_line> FAILED

LOAD / RELOAD / REFRESH

Format: load or reload or refresh

Response:
- Success: <command_line> OK
- Failure: <command_line> FAILED

EXPORT / DUMPCONFIG / DUMP / READCONFIG

Format: export or dumpconfig or dump or readconfig

Response:
- Success: Full JSON settings on one line, then <command_line> OK
- Failure: {} then <command_line> OK (if no settings)

Example:

> export
{"fw":"1.0.0","cv":1,"w":[{"ss":"MyWiFi","pw":"password123"}],"a":{"sr":8000,"ath":50},"u":{"ah":["api.example.com"],"ap":[443],"en":[true]},"s":{"usc":true,"rsc":true},"t":{"oh":-5},"l":{"sf":true,"se":true},"wtp":8,"mac":"AA:BB:CC:DD:EE:FF"}
export OK

IMPORT / WRITECONFIG / APPLY

Format: import <json> or writeconfig <json> or apply <json>

Response:
- Success: <command_line> OK
- Failure: <command_line> FAILED: missing JSON or <command_line> FAILED: invalid JSON payload or <command_line> FAILED: <error_message>

Example:

> import {"a":{"ath":60}}
import {"a":{"ath":60}} OK

CONFIG (with JSON)

Format: config <json>

Response:
- Success:
Configuring device... ======================================== Configuration Applied Successfully ======================================== Parameters updated: <key> = <old_value> -> <new_value> ======================================== Settings saved to NVS successfully Rebooting device in 2 seconds... ======================================== <command_line> OK
- Failure: <command_line> FAILED: missing JSON or <command_line> FAILED: invalid JSON payload or <command_line> FAILED: <error_message>

Note: After successful config, device waits for "DONE" command or auto-reboots after 2 seconds.

CONFIG ? (Print Configuration JSON)

Format: config ?

Response: JSON config message (see Message Types), then <command_line> OK

AUTOCONFIG

Format: autoconfig <SSID>,<PASSWORD> or autoconfig <SSID>,<PASSWORD>,<HOST_IP>,<HOST_PORT>,<TIMEZONE_OFFSET>,<AUDIO_THRESHOLD>,<MIN_RECORDING_MS>,<MAX_RECORDING_MS>,<PRE_RECORDING_MS>

Response:
- Success:
Configuring device... Saving configuration to NVS... ======================================== Configuration Applied Successfully ======================================== Parameters set: wifi[0].ssid = <SSID> wifi[0].password = <masked_password> ======================================== Type 'DONE' and press Enter to reboot the device ======================================== <command_line> OK
- Failure: Various error messages for invalid parameters

Note: Device waits for "DONE" command or auto-reboots after 2 seconds.

PUSHSETTINGS

Format: pushsettings

Response:
- Success:
Pushing settings to API server... PUSHSETTINGS OK <command_line> OK
- Failure:
Pushing settings to API server... PUSHSETTINGS FAILED <command_line> FAILED

PULLSETTINGS

Format: pullsettings

Response:
- Success:
Pulling settings from API server... PULLSETTINGS OK <command_line> OK
- Failure:
Pulling settings from API server... PULLSETTINGS FAILED: <error_message> <command_line> FAILED

TXPOWER / TX_POWER

Format: txpower or txpower <value> (value: 1-10)

Response:
- Show current:
WiFi TX Power: <value> (ESP32 value: <esp32_value>) <command_line> OK
- Set success:
WiFi TX Power set to <value> (ESP32 value: <esp32_value>) - applied immediately Settings pushed to server <command_line> OK
- Set failure: <command_line> FAILED: TX power must be between 1 and 10 or <command_line> FAILED: Could not save settings

Information Commands

TIME / CLOCK

Format: time or clock

Response:

Device Time: <YYYY-MM-DDTHH:MM:SS.mmmZ>
Epoch: <epoch_seconds>
Uptime: <milliseconds> ms
<command_line> OK

STATUS / INFO

Format: status or info

Response: JSON object with comprehensive status information:

{
  "storage": "SD"|"PS",
  "sd": true|false,
  "sdFree": <percentage>|null,
  "heap": {
    "total": <bytes>,
    "free": <bytes>,
    "used": <bytes>,
    "minFree": <bytes>,
    "FreeBlock": <bytes>
  },
  "psram": {
    "total": <bytes>|null,
    "free": <bytes>|null,
    "used": <bytes>|null
  },
  "record": true|false,
  "upload": true|false,
  "queue": <count>,
  "wifi": {
    "conn": true|false,
    "ssid": "<ssid>"|null,
    "ip": "<ip>"|null,
    "rssi": <rssi>|null
  },
  "uptime": <seconds>,
  "time": {
    "valid": true|false,
    "RTC": true|false,
    "time": "<ISO_time>"|null,
    "epoch": <seconds>|null,
    "uptime": <seconds>
  },
  "recordings": {
    "total": <count>,
    "duration": <ms>,
    "uploaded": <count>,
    "error": <count>,
    "lastEpoch": <seconds>|null,
    "lastTime": "<ISO_time>"|null
  },
  "audio": {
    "currentDb": <dB>,
    "minDb": <dB>,
    "maxDb": <dB>,
    "avgDb": <dB>,
    "currentDynamic": <percentage>
  },
  "api": {
    "dead": true|false,
    "recovery": 0,
    "lastUpload": "<ISO_time>"|null,
    "lastEvent": "<ISO_time>"|null,
    "Events": <count>,
    "Uploads": <count>
  },
  "config": {
    "mac": "<mac>",
    "fw": "<version>",
    "host": "<host>"|null,
    "port": <port>|null,
    "sense": <threshold>,
    "min": <ms>,
    "max": <ms>,
    "silence": <ms>,
    "gain": <dB>,
    "samples": <rate>,
    "pre": <ms>
  }
}
<command_line> OK

IP

Format: ip

Response:
- Connected: <ip_address> then <command_line> OK
- Not connected: Not connected then <command_line> OK

MAC

Format: mac

Response: <mac_address> then <command_line> OK

CONFIG (CSV Format)

Format: config (without ?)

Response:

<host0>,<hostPort>,<macAddress>,<ipAddress>,<minRecording>,<maxRecording>,<silenceThreshold>,<audioThreshold>,<gain>,<sdCardSize>,<sdCardFree>
<command_line> OK

RECORDINGS / RECORDINGSSUMMARY

Format: recordings or recordingssummary

Response:

Recording Count: <count>
Total Duration: <ms> ms
Uploaded Count: <count>
Error Count: <count>
<command_line> OK

AUDIOLEVEL / AUDIOLEVELS / VU

Format: audiolevel or audiolevels or vu

Response:

Current Level: <level>
Current dB: <dB>
Min Level: <level> (<dB> dB)
Max Level: <level> (<dB> dB)
Average Level: <level>
Peak Sample: <sample>
<command_line> OK

ERRORS / ERROR

Format: errors or error

Response:

Last Sequence ID: <seq_id>
Error Count: <count>
[FATAL|ERROR] <message> (seq: <seq_id>)
... (up to 10 errors shown)
... and <remaining_count> more errors
<command_line> OK

SETTIME / SET_TIME

Format: settime <YYYY-MM-DDTHH:MM:SSZ> or settime <epoch_seconds>

Response:
- Success:
Time set to: <YYYY-MM-DDTHH:MM:SS[.microseconds]Z> <command_line> OK
- Failure: <command_line> FAILED: Usage: settime <YYYY-MM-DDTHH:MM:SSZ> or <epoch_seconds> or <command_line> FAILED: Invalid time format or <command_line> FAILED: Invalid epoch time (must be >= 2021-01-01) or <command_line> FAILED: Could not set system time

HEALTH ?

Format: health ?

Response: JSON health message (see Message Types), then <command_line> OK

REBOOT / RESET / RESTART

Format: reboot or reset or restart

Response:

<command_line> OK
REBOOTING

(Device reboots immediately)

FACTORYRESET / FACTORY / FACTORY_RESET

Format: factoryreset or factory or factory_reset

Response:

========================================
⚠️  FACTORY RESET INITIATED ⚠️
========================================
This will erase ALL settings including:
  - WiFi credentials
  - API endpoints
  - Audio settings
  - All device configuration
========================================
Starting factory reset...
Clearing WiFi credentials from NVS...
✓ WiFi NVS cleared successfully
Erasing NVS settings...
========================================
✓ FACTORY RESET SUCCESS
✓ NVS settings erased
✓ WiFi credentials cleared
Rebooting device in 2 seconds...
========================================

(Device reboots after 2 seconds)

MAINTENANCE / MAINT

Format: maintenance or maint

Response:
- Success:
Running maintenance tasks... Settings pushed to server successfully <command_line> OK
- Failure:
Running maintenance tasks... Settings push to server FAILED <command_line> FAILED

MAKEINDEX / MAKE-INDEX

Format: makeindex or make-index

Response:

Reconciling recordings index...
Index reconciliation completed
<command_line> OK

PUSHLOGS / UPLOADLOGS

Format: pushlogs or uploadlogs or pushlog or uploadlog

Response:
- Success:
Uploading latest log file... Successfully uploaded log file: <path> <command_line> OK
- Failure: <command_line> FAILED: SD card not available or <command_line> FAILED: Time not synced, cannot determine log file path or <command_line> FAILED: Log file does not exist: <path> or <command_line> FAILED: Could not upload log file

FORMAT / FORMATSD / FORMATSDCARD

Format: format or formatsd or formatsdcard

Response:
- Success: <command_line> OK
- Failure: <command_line> FAILED: SD card not available or <command_line> FAILED: Cannot open root directory or <command_line> FAILED: Could not remount SD card

RECOVER / RECOVERY

Format: recover or recovery

Response:

Recovering API endpoints and uploads...
Connecting to WiFi...
API endpoints reset - dead endpoints cleared
<warning_or_status_message>
Upload queue: <count> items pending
<command_line> OK

RECONNECT / RECONNECTWIFI / WIFI_RECONNECT

Format: reconnect or reconnectwifi or wifi_reconnect

Response:

Reconnecting WiFi...
Recording will continue, uploads will pause during reconnection
Disconnecting WiFi...
Stopping WiFi...
Starting WiFi...
Connecting to WiFi...
WiFi reconnected successfully: <ip_address>
API endpoints reset
<command_line> OK

SAMPLE

Format: sample

Response:
- Success:
Starting sample recording (threshold check bypassed)... Recording will use default min/max duration settings Sample recording started successfully Recording will stop at max duration or after silence threshold <command_line> OK
- Failure:
FAILED: Recording already in progress <command_line> FAILED
or
FAILED: Could not start sample recording Check storage availability and ensure not already recording <command_line> FAILED

File Management Commands

CD / CHDIR

Format: cd or cd / or cd <directory>

Response:
- Show current:
Current directory: <path> <command_line> OK
- Change success:
Changed to: <path> <command_line> OK
- Failure: <command_line> FAILED: SD card not available or <command_line> FAILED: Directory does not exist: <path> or <command_line> FAILED: Not a directory: <path>

DIR / LS / LIST

Format: dir or ls or list

Response:

Directory: <path>
----------------------------------------
[DIR]  <directory_name>
[FILE] <filename> (<size> bytes)
----------------------------------------
Total: <file_count> files, <dir_count> directories
<command_line> OK

RM / DELETE / DEL

Format: rm <filename> or rm * or delete <filename> or del <filename>

Response:
- Single file success:
Deleted: <path> <command_line> OK
- Wildcard success:
Deleted: <filename> ... (one line per file) Deleted: <count> files Failed: <count> files (if any) <command_line> OK
- Failure: <command_line> FAILED: SD card not available or <command_line> FAILED: Storage not initialized or <command_line> FAILED: Usage: rm <filename> or rm * or <command_line> FAILED: File does not exist: <path> or <command_line> FAILED: Cannot delete directory (use rmdir): <path> or <command_line> FAILED: Could not delete: <path>

Message Types and Codes

All messages sent to Serial are in JSON format (except in AP mode when WiFi credentials are not configured, which uses plain text). Messages include a ty (type) field that identifies the message category.

Message Type: `log`

Code: ty: "log"

Format:

{
  "ty": "log",
  "lv": "info"|"warn"|"error"|"fatal"|"debug"|"event",
  "ms": "<message_text>",
  "mc": "<device_id>",
  "si": "<session_id>"
}

Levels:
- info: Informational messages
- warn: Warning messages
- error: Error messages
- fatal: Fatal error messages
- debug: Debug messages
- event: Event-style messages (state transitions)

Example:

{"ty":"log","lv":"info","ms":"INIT - Reset reason: Power On (1)","rr":"Power On","mc":"AA:BB:CC:DD:EE:FF","si":"abc123"}

Message Type: `config`

Code: ty: "config"

Format:

{
  "ty": "config",
  "fw": "<firmware_version>",
  "ho": "<api_host>"|"",
  "po": <api_port>|0,
  "ss": "<wifi_ssid>"|"",
  "sie": true|false,
  "rte": true|false,
  "usc": true|false,
  "rsc": true|false,
  "oh": <timezone_offset_hours>,
  "wtp": <wifi_tx_power>,
  "se": <audio_threshold>,
  "mi": <min_recording_ms>,
  "mx": <max_recording_ms>,
  "sth": <silence_threshold_ms>,
  "pr": <pre_record_ms>,
  "gn": <codec_gain_db>,
  "is": <sample_rate>,
  "mc": "<device_id>",
  "si": "<session_id>"
}

When sent:
- On startup (if WiFi credentials configured)
- After settings changes (5 second debounce)
- Periodically every 15 minutes
- In response to config ? command

Message Type: `health`

Code: ty: "health"

Format:

{
  "ty": "health",
  "st": "SD",
  "sd": true|false,
  "rc": <recording_count>,
  "uc": <uploaded_count>,
  "pq": <pending_queue_count>,
  "td": <total_duration_seconds>,
  "ht": "<heap_total>"|"<size>K"|"<size>M",
  "hf": "<heap_free>"|"<size>K"|"<size>M",
  "tm": true|false,
  "wi": true|false,
  "ip": "<ip_address>"|"",
  "ri": <rssi>|0,
  "qe": <queue_count>,
  "ut": <uptime_seconds>,
  "yr": <year>|null,
  "yf": <total_files>|null,
  "ys": "<size>"|null,
  "yh": <total_hours>|null,
  "ym": <months_with_recordings>|null,
  "yd": <days_with_recordings>|null,
  "am": <api_min_response_ms>|null,
  "ax": <api_max_response_ms>|null,
  "aa": <api_avg_response_ms>|null,
  "mc": "<device_id>",
  "si": "<session_id>"
}

When sent:
- In response to health ? command

Message Type: `short`

Code: ty: "short"

Format:

{
  "ty": "short",
  "rg": true|false,
  "ug": true|false,
  "cd": <current_db>,
  "mi": <min_db>,
  "mx": <max_db>,
  "mc": "<device_id>",
  "si": "<session_id>"
}

When sent:
- Periodically every 30 seconds (if WiFi credentials configured)

Settings Parameter Codes

Top-Level Keys

Code	Full Name	Type	Description
`fw`	firmware	string	Firmware version (read-only)
`cv`	configVersion	integer	Configuration schema version (read-only)
`w`	wifi	array	WiFi credential array (max 3 entries)
`a`	audio	object	Audio settings
`u`	upload	object	Upload settings
`r`	rtc	object	External RTC settings
`s`	sdCard	object	SD card settings
`t`	timezone	object	Timezone and maintenance settings
`l`	log	object	Logging configuration
`c`	cli	object	CLI settings (reserved, unused)
`wtp`	wifiTxPower	integer	WiFi transmit power (1-10)
`mac`	mac	string	Device ID / MAC address (read-only)
`cws`	connectedWiFiSsid	string	Connected WiFi SSID (read-only)
`cwi`	connectedWiFiIndex	integer	Connected WiFi index (read-only)
`rt`	runtime	object	Runtime metadata (read-only)
`cip`	currentIp	object	Current IP configuration (read-only)

WiFi Credential Fields (`w` array)

Code	Full Name	Type	Description
`ss`	ssid	string	WiFi network name
`pw`	password	string	WiFi password (WPA/WPA2 PSK)
`ctm`	connectTimeoutMs	integer	Connection timeout in milliseconds
`sie`	staticIpEnabled	boolean	Enable static IP configuration
`sip`	staticIp	string	Static IPv4 address
`ssn`	staticSubnet	string	Subnet mask
`sgt`	staticGateway	string	Default gateway
`sd1`	staticDns1	string	Primary DNS server
`sd2`	staticDns2	string	Secondary DNS server

CLI Shortcuts:
- ssid0, ssid1, ssid2 → wifi[0].ssid, wifi[1].ssid, wifi[2].ssid
- pass0, pass1, pass2 → wifi[0].password, wifi[1].password, wifi[2].password
- static0, static1, static2 → wifi[0].staticIpEnabled, etc.
- ip0, ip1, ip2 → wifi[0].staticIp, etc.
- subnet0, subnet1, subnet2 → wifi[0].staticSubnet, etc.
- gateway0, gateway1, gateway2 → wifi[0].staticGateway, etc.
- dns10, dns11, dns12 → wifi[0].staticDns1, etc.
- dns20, dns21, dns22 → wifi[0].staticDns2, etc.

Audio Settings (`a` object)

Code	Full Name	Type	Description
`sr`	sampleRate	integer	Audio sampling rate (Hz), currently only 8000
`bs`	bufferSamples	integer	Internal audio buffer size (512-4096 samples)
`ath`	audioThreshold	integer	Amplitude threshold (0-255)
`prm`	preRecordMs	integer	Pre-record window (0-500 ms)
`mrm`	minRecordingMs	integer	Minimum recording duration (ms)
`xrm`	maxRecordingMs	integer	Maximum recording duration (ms)
`stm`	silenceThresholdMs	integer	Silence duration before auto-stop (ms)
`dsf`	discardSmallFilesEnabled	boolean	Enable discarding small files
`dmm`	discardSmallFilesMinMs	integer	Minimum duration for small file discard (ms)
`cg`	codecGain	integer	Codec input gain (-3, 0, 3, 6, 9, 12, 15, 18, 21, 24 dB)

CLI Shortcuts:
- min → audio.minRecordingMs
- max → audio.maxRecordingMs
- pre / preroll / prerecord → audio.preRecordMs
- silence → audio.silenceThresholdMs
- gain → audio.codecGain
- sense → audio.audioThreshold

Upload Settings (`u` object)

Code	Full Name	Type	Description
`qd`	queueDepth	integer	Upload queue depth (4-32, legacy)
`ctm`	convertToMp3	boolean	Convert to MP3 before upload (legacy)
`ah`	apiHosts	array	API endpoint hostnames/IPs
`ap`	apiPorts	array	API endpoint TCP ports
`en`	enabled	array	Per-endpoint enable flags

CLI Shortcuts:
- host0, host1, host2 → upload.apiHosts[0], upload.apiHosts[1], upload.apiHosts[2]
- upload.apiPorts[0], upload.apiPorts[1], upload.apiPorts[2] (no shortcut)
- upload.enabled[0], upload.enabled[1], upload.enabled[2] (no shortcut)

RTC Settings (`r` object)

Code	Full Name	Type	Description
`en`	enabled	boolean	Enable external RTC
`sda`	sdaPin	integer	I²C SDA pin number
`scl`	sclPin	integer	I²C SCL pin number

SD Card Settings (`s` object)

Code	Full Name	Type	Description
`usc`	useSdCard	boolean	Enable SD card usage
`rsc`	recordToSdCard	boolean	Record audio to SD card
`m1b`	mode1bit	boolean	Use 1-bit SD bus mode
`frq`	frequency	integer	SD card bus clock frequency (1-20 MHz)
`fmf`	formatIfMountFailed	boolean	Format SD card if mount fails

Timezone Settings (`t` object)

Code	Full Name	Type	Description
`oh`	offsetHours	integer	Timezone offset from UTC (-12 to +14 hours)
`mh`	maintenanceHour	integer	Maintenance hour (0-23)
`mm`	maintenanceMinute	integer	Maintenance minute (0-59)

Log Settings (`l` object)

Code	Full Name	Type	Description
`sf`	serialFatal	boolean	Enable fatal messages on serial
`se`	serialError	boolean	Enable error messages on serial
`sw`	serialWarning	boolean	Enable warning messages on serial
`si`	serialInfo	boolean	Enable info messages on serial
`sd`	serialDebug	boolean	Enable debug messages on serial
`sev`	serialEvent	boolean	Enable event messages on serial
`ff`	fileFatal	boolean	Enable fatal messages in files
`fe`	fileError	boolean	Enable error messages in files
`fw`	fileWarning	boolean	Enable warning messages in files
`fi`	fileInfo	boolean	Enable info messages in files
`fd`	fileDebug	boolean	Enable debug messages in files
`fev`	fileEvent	boolean	Enable event messages in files

Runtime Metadata (`rt` object, read-only)

Code	Full Name	Type	Description
`mac`	mac	string	Device ID / MAC address
`wc`	wifiConnected	boolean	WiFi connection status
`css`	connectedSsid	string	Connected WiFi SSID
`rss`	rssi	integer	Current RSSI (dBm)
`ci`	connectedIndex	integer	WiFi credentials array index

Current IP Block (`cip` object, read-only)

Code	Full Name	Type	Description
`ip`	ip	string	Current IPv4 address
`sub`	subnet	string	Current subnet mask
`gw`	gateway	string	Current default gateway
`d1`	dns1	string	Primary DNS server
`d2`	dns2	string	Secondary DNS server

Config Message Field Codes

In config type messages, these codes are used:

Code	Full Name	Maps To
`ho`	host	`upload.apiHosts[0]`
`po`	port	`upload.apiPorts[0]`
`ss`	ssid	`wifi[0].ssid`
`sie`	staticIpEnabled	`wifi[0].staticIpEnabled`
`rte`	rtcEnabled	`rtc.enabled`
`usc`	useSdCard	`sdCard.useSdCard`
`rsc`	recordToSdCard	`sdCard.recordToSdCard`
`oh`	offsetHours	`timezone.offsetHours`
`wtp`	wifiTxPower	`wifiTxPower`
`se`	sense	`audio.audioThreshold`
`mi`	min	`audio.minRecordingMs`
`mx`	max	`audio.maxRecordingMs`
`sth`	silenceThreshold	`audio.silenceThresholdMs`
`pr`	preRecord	`audio.preRecordMs`
`gn`	gain	`audio.codecGainDb`
`is`	sampleRate	`audio.sampleRate`

Health Message Field Codes

In health type messages, these codes are used:

Code	Full Name	Description
`st`	storage	Storage type ("SD")
`sd`	sdCard	SD card available
`rc`	recordingCount	Audio files recorded this session
`uc`	uploadedCount	Audio files uploaded this session
`pq`	pendingQueue	Files in queue pending upload
`td`	totalDuration	Total duration recorded (seconds)
`ht`	heapTotal	Total heap size (formatted string)
`hf`	heapFree	Free heap size (formatted string)
`tm`	timeValid	Time is valid
`wi`	wifi	WiFi connected
`ip`	ip	IP address
`ri`	rssi	RSSI value
`qe`	queue	Upload queue count
`ut`	uptime	Uptime in seconds
`yr`	year	Year for yearly summary
`yf`	yearlyFiles	Total files on SD
`ys`	yearlySize	Total size (formatted string)
`yh`	yearlyHours	Total hours
`ym`	yearlyMonths	Months with recordings
`yd`	yearlyDays	Days with recordings
`am`	apiMin	API minimum response time (ms)
`ax`	apiMax	API maximum response time (ms)
`aa`	apiAvg	API average response time (ms)

Short Message Field Codes

In short type messages, these codes are used:

Code	Full Name	Description
`rg`	recording	Currently recording
`ug`	uploading	Currently uploading
`cd`	currentDb	Current audio level (dB)
`mi`	minDb	Minimum audio level (dB)
`mx`	maxDb	Maximum audio level (dB)

Common Field Codes (All Message Types)

Code	Full Name	Description
`ty`	type	Message type: "log", "config", "health", "short"
`lv`	level	Log level: "info", "warn", "error", "fatal", "debug", "event"
`ms`	message	Message text
`mc`	mac	Device ID / MAC address
`si`	sessionId	Session identifier
`rr`	resetReason	Reset reason (in INIT log message)

Notes

Case Sensitivity: All CLI commands and parameter names are case-insensitive (automatically converted to uppercase/lowercase as needed).
JSON Format: All messages are sent as single-line JSON (no pretty printing) except for CLI command responses.
AP Mode: When WiFi credentials are not configured (AP mode), log messages are sent as plain text instead of JSON.
Mutex Protection: Serial output is protected by a mutex to prevent interleaving of CLI responses and periodic messages.
Session ID: All log/config/health/short messages include a session ID (si) that changes on each device boot.
Device ID: All messages include a device ID (mc) derived from the MAC address.
Parameter Aliases: Many settings have CLI shortcuts (e.g., min → audio.minRecordingMs). See the shortcuts section for each settings category.
Array Indices: WiFi credentials and API endpoints use zero-based array indices (0, 1, 2).
Read-Only Fields: Some fields (like fw, cv, mac, rt, cip) are read-only and cannot be set via CLI commands.
Validation: Settings are validated before being saved. Invalid values may be clamped to valid ranges or rejected with an error message.

Navigation

Serial CLI Documentation

Table of Contents

CLI Command Format

Input Format

Response Format

Command Structure

Settings Commands

HELP / ?

SHOW / GET / READ

SET / CHANGE / UPDATE

SAVE / STORE

LOAD / RELOAD / REFRESH

EXPORT / DUMPCONFIG / DUMP / READCONFIG

IMPORT / WRITECONFIG / APPLY

CONFIG (with JSON)

CONFIG ? (Print Configuration JSON)

AUTOCONFIG

PUSHSETTINGS

PULLSETTINGS

TXPOWER / TX_POWER

Information Commands

TIME / CLOCK

STATUS / INFO

IP

MAC

CONFIG (CSV Format)

RECORDINGS / RECORDINGSSUMMARY

AUDIOLEVEL / AUDIOLEVELS / VU

ERRORS / ERROR

SETTIME / SET_TIME

HEALTH ?

REBOOT / RESET / RESTART

FACTORYRESET / FACTORY / FACTORY_RESET

MAINTENANCE / MAINT

MAKEINDEX / MAKE-INDEX

PUSHLOGS / UPLOADLOGS

FORMAT / FORMATSD / FORMATSDCARD

RECOVER / RECOVERY

RECONNECT / RECONNECTWIFI / WIFI_RECONNECT

SAMPLE

File Management Commands

CD / CHDIR

DIR / LS / LIST

RM / DELETE / DEL

Message Types and Codes

Message Type: log

Message Type: config

Message Type: health

Message Type: short

Settings Parameter Codes

Top-Level Keys

WiFi Credential Fields (w array)

Audio Settings (a object)

Upload Settings (u object)

RTC Settings (r object)

SD Card Settings (s object)

Timezone Settings (t object)

Log Settings (l object)

Runtime Metadata (rt object, read-only)

Current IP Block (cip object, read-only)

Config Message Field Codes

Health Message Field Codes

Short Message Field Codes

Common Field Codes (All Message Types)

Notes

Message Type: `log`

Message Type: `config`

Message Type: `health`

Message Type: `short`

WiFi Credential Fields (`w` array)

Audio Settings (`a` object)

Upload Settings (`u` object)

RTC Settings (`r` object)

SD Card Settings (`s` object)

Timezone Settings (`t` object)

Log Settings (`l` object)

Runtime Metadata (`rt` object, read-only)

Current IP Block (`cip` object, read-only)