This document provides comprehensive documentation for all settings in the Boondock firmware. Each setting includes its abbreviation, full meaning, data range, purpose, system impact, and important warnings.
w / wifi)Type: Array of objects (maximum 3 entries)
Default: Empty array
Purpose: Stores WiFi network credentials that the device will attempt to connect to, tried in order from index 0 to 2.
System Impact:
- The device attempts to connect to networks in array order (0, then 1, then 2).
- If no WiFi credentials are configured, the device enters Access Point (AP) mode for initial setup.
- Adding WiFi credentials triggers automatic network connection attempts.
- Removing all WiFi credentials pauses recording and upload tasks.
Warning: ⚠️ WiFi passwords are stored in plain text in NVS. When settings are sent to external systems, passwords are masked as "HIDDEN_FOR_SECURITY" for security.
ss / ssid - WiFi Network NameAbbreviation: ss
Full Name: Service Set Identifier
Type: String (max 32 characters)
Range: Any valid WiFi SSID string, empty string means unused entry
Default: "" (empty)
Purpose: The name of the WiFi network to connect to.
System Impact:
- Empty SSID entries are skipped during connection attempts.
- SSID matching is case-sensitive.
- Changing SSID triggers a reconnection attempt.
Warning: ⚠️ Ensure the SSID matches exactly (case-sensitive) with your router's broadcast name.
CLI Commands:
- Get value: show ssid0 or show ssid1 or show ssid2 (for WiFi credentials 0, 1, or 2)
- Set value: set ssid0 MyWiFi or set wifi[0].ssid MyWiFi
pw / password - WiFi PasswordAbbreviation: pw
Full Name: WiFi Password
Type: String (max 63 characters for WPA/WPA2)
Range: Any valid WPA/WPA2 PSK password
Default: "" (empty)
Purpose: The WPA/WPA2 password (Pre-Shared Key) for the WiFi network.
System Impact:
- Required for WPA/WPA2 secured networks.
- Empty password is used for open networks (not recommended for security).
- Changing password triggers a reconnection attempt.
Warning:
- ⚠️ SECURITY: Passwords are stored in plain text in NVS flash memory.
- ⚠️ Passwords are masked when sent to external systems but visible in local settings export.
- ⚠️ Use strong passwords to protect your network.
CLI Commands:
- Get value: show pass0 or show pass1 or show pass2 (for WiFi credentials 0, 1, or 2)
- Set value: set pass0 MyPassword123 or set wifi[0].password MyPassword123
ctm / connectTimeoutMs - Connection TimeoutAbbreviation: ctm
Full Name: Connect Timeout Milliseconds
Type: Unsigned integer (milliseconds)
Range: 1000 - 60000 ms (1 second to 60 seconds)
Default: 30000 (30 seconds)
Purpose: Maximum time to wait for a WiFi connection attempt before giving up and trying the next network in the array.
System Impact:
- Lower values cause faster fallback to next network but may interrupt slow connections.
- Higher values wait longer before trying next network, potentially delaying connection.
- If all networks timeout, the device waits before retrying (exponential backoff).
Warning: ⚠️ Setting too low (< 5 seconds) may prevent successful connections on slow networks. Setting too high (> 60 seconds) delays fallback to backup networks.
CLI Commands:
- Get value: show wifi[0].connectTimeoutMs
- Set value: set wifi[0].connectTimeoutMs 30000
sie / staticIpEnabled - Static IP EnabledAbbreviation: sie
Full Name: Static IP Enabled
Type: Boolean
Range: true or false
Default: false (DHCP)
Purpose: Enables static IP configuration instead of DHCP for this WiFi profile.
System Impact:
- When true, the device uses the static IP configuration (sip, ssn, sgt, sd1, sd2).
- When false, the device uses DHCP to obtain IP configuration automatically.
- Changing this setting requires WiFi reconnection to take effect.
Warning:
- ⚠️ Ensure static IP settings don't conflict with other devices on the network.
- ⚠️ Incorrect static IP configuration can prevent network access.
- ⚠️ Use DHCP unless you have a specific reason for static IP (e.g., port forwarding, firewall rules).
CLI Commands:
- Get value: show static0 or show wifi[0].staticIpEnabled
- Set value: set static0 true or set wifi[0].staticIpEnabled true
sip / staticIp - Static IP AddressAbbreviation: sip
Full Name: Static IP Address
Type: String (IPv4 address)
Range: Valid IPv4 address format (e.g., "192.168.1.50")
Default: "0.0.0.0" (unset)
Purpose: The static IPv4 address to assign to the device when staticIpEnabled is true.
System Impact:
- Only used when staticIpEnabled is true.
- Must be within the subnet range defined by staticSubnet.
- Changing this requires WiFi reconnection.
Warning:
- ⚠️ Must be a valid IP address within your network's subnet range.
- ⚠️ Ensure the IP address is not already in use by another device (IP conflict).
- ⚠️ Typical home networks use 192.168.1.x or 192.168.0.x ranges.
CLI Commands:
- Get value: show ip0 or show wifi[0].staticIp
- Set value: set ip0 192.168.1.50 or set wifi[0].staticIp 192.168.1.50
ssn / staticSubnet - Subnet MaskAbbreviation: ssn
Full Name: Static Subnet Mask
Type: String (IPv4 subnet mask)
Range: Valid IPv4 subnet mask (e.g., "255.255.255.0")
Default: "0.0.0.0" (unset)
Purpose: The subnet mask for the static IP configuration.
System Impact:
- Defines the network segment the device belongs to.
- Must match your router's subnet configuration.
- Common values: "255.255.255.0" (24-bit, /24) for most home networks.
Warning: ⚠️ Incorrect subnet mask prevents proper network communication.
CLI Commands:
- Get value: show subnet0 or show wifi[0].staticSubnet
- Set value: set subnet0 255.255.255.0 or set wifi[0].staticSubnet 255.255.255.0
sgt / staticGateway - Default GatewayAbbreviation: sgt
Full Name: Static Gateway
Type: String (IPv4 address)
Range: Valid IPv4 address (typically router's IP)
Default: "0.0.0.0" (unset)
Purpose: The default gateway (router) IP address for static IP configuration.
System Impact:
- Required for internet access when using static IP.
- Typically your router's IP address (e.g., "192.168.1.1" or "192.168.0.1").
Warning: ⚠️ Incorrect gateway prevents internet access even if local network works.
CLI Commands:
- Get value: show gateway0 or show wifi[0].staticGateway
- Set value: set gateway0 192.168.1.1 or set wifi[0].staticGateway 192.168.1.1
sd1 / staticDns1 - Primary DNS ServerAbbreviation: sd1
Full Name: Static DNS 1
Type: String (IPv4 address)
Range: Valid IPv4 address
Default: "0.0.0.0" (unset, uses gateway as DNS)
Purpose: Primary DNS server for name resolution when using static IP.
System Impact:
- Used for DNS lookups (converting domain names to IP addresses).
- Common public DNS servers: "8.8.8.8" (Google), "1.1.1.1" (Cloudflare).
Warning: ⚠️ If unset, the device uses the gateway as DNS server.
CLI Commands:
- Get value: show dns10 or show wifi[0].staticDns1
- Set value: set dns10 8.8.8.8 or set wifi[0].staticDns1 8.8.8.8
sd2 / staticDns2 - Secondary DNS ServerAbbreviation: sd2
Full Name: Static DNS 2
Type: String (IPv4 address)
Range: Valid IPv4 address
Default: "0.0.0.0" (unset, optional)
Purpose: Secondary DNS server used as fallback if primary DNS fails.
System Impact:
- Optional backup DNS server.
- Used only if primary DNS (sd1) is unavailable.
Warning: ⚠️ Optional setting - can be left unset.
CLI Commands:
- Get value: show dns20 or show wifi[0].staticDns2
- Set value: set dns20 1.1.1.1 or set wifi[0].staticDns2 1.1.1.1
wtp / wifiTxPower - WiFi Transmit PowerAbbreviation: wtp
Full Name: WiFi Transmit Power
Type: Integer
Range: 1 - 10 (device-specific scale)
Default: 10 (maximum)
Purpose: Controls WiFi radio transmit power on a 1-10 scale. Lower values reduce power consumption and range; higher values increase range and power usage.
System Impact:
- Power Consumption: Lower values reduce battery drain (important for battery-powered devices).
- Range: Higher values improve WiFi range but increase power consumption.
- Heat: Higher values generate more heat.
- Applied immediately if WiFi is connected, otherwise applied on next connection.
Warning:
- ⚠️ Lower values (1-3) significantly reduce range - only use if device is close to router.
- ⚠️ Higher values (8-10) increase power consumption and heat generation.
- ⚠️ Setting is immediately pushed to server to prevent overwrite from server pull.
CLI Commands:
- Get value: show wifiTxPower or show wtp
- Set value: set wifiTxPower 8 or set wtp 8 or use txpower 8 command
sr / sampleRate - Audio Sample RateAbbreviation: sr
Full Name: Sample Rate
Type: Integer (Hz)
Range: Currently only 8000 Hz supported
Default: 8000
Purpose: Audio sampling rate in samples per second (Hz). Determines audio quality and file size.
System Impact:
- File Size: Higher sample rates produce larger files (not applicable - only 8000 Hz supported).
- Quality: 8000 Hz is suitable for voice recording (telephone quality).
- Processing: Lower rates reduce CPU load and memory usage.
Warning: ⚠️ Currently only 8000 Hz is supported. Other values are ignored and default to 8000 Hz.
CLI Commands:
- Get value: show audio.sampleRate
- Set value: set audio.sampleRate 8000
bs / bufferSamples - Buffer SizeAbbreviation: bs
Full Name: Buffer Samples
Type: Integer (samples)
Range: 512 - 4096 samples
Default: 1024 samples
Purpose: Size of the internal audio buffer used for recording. Larger buffers improve robustness but increase latency and RAM usage.
System Impact:
- Robustness: Larger buffers handle temporary CPU spikes better, reducing dropouts.
- Latency: Larger buffers increase delay between audio capture and processing.
- Memory: Each sample uses 2 bytes (16-bit), so 1024 samples = 2 KB RAM.
- Dropouts: Smaller buffers may cause audio dropouts under heavy CPU load.
Warning:
- ⚠️ Values below 512 are clamped to 512 (minimum).
- ⚠️ Values above 4096 are clamped to 4096 (maximum).
- ⚠️ Larger buffers (2048+) use more RAM but provide better reliability.
CLI Commands:
- Get value: show audio.bufferSamples
- Set value: set audio.bufferSamples 1024
ath / audioThreshold - Audio Sensitivity ThresholdAbbreviation: ath
Full Name: Audio Threshold
Type: Integer (0-100 scale)
Range: 0 - 100
Default: 50
Purpose: Sensitivity setting that determines when audio is "loud enough" to trigger recording. Lower values = less sensitive (needs louder audio), higher values = more sensitive (triggers on quieter audio).
System Impact:
- Recording Triggers: Controls when recording starts based on audio level.
- Noise Filtering: Lower values filter out background noise better.
- False Triggers: Higher values may trigger on background noise.
- Missed Audio: Lower values may miss quiet sounds.
Mapping to dB:
- Setting 0 (low sensitivity) → approximately -20 dB
- Setting 50 (default) → approximately -40 dB
- Setting 100 (high sensitivity) → approximately -80 dB
Warning:
- ⚠️ Too low (< 30) may miss important audio events.
- ⚠️ Too high (> 80) may cause excessive false triggers from background noise.
- ⚠️ Test in your environment to find optimal value.
CLI Commands:
- Get value: show sense or show audio.audioThreshold
- Set value: set sense 50 or set audio.audioThreshold 50
prm / preRecordMs - Pre-Record WindowAbbreviation: prm
Full Name: Pre-Record Milliseconds
Type: Integer (milliseconds)
Range: 0 - 500 ms
Default: 200 ms
Purpose: Amount of audio kept before the trigger point, allowing recordings to include brief pre-trigger context. This creates a "pre-roll" buffer.
System Impact:
- Memory Usage: Uses RAM to buffer audio before trigger (approximately 16 bytes per millisecond at 8 kHz).
- File Size: Slightly increases recording file size.
- Context: Captures audio that occurred just before the trigger event.
- Disabled: Setting to 0 disables pre-roll (saves memory).
Warning:
- ⚠️ Values above 500 are clamped to 500 ms (maximum).
- ⚠️ Larger values use more RAM (500 ms ≈ 8 KB).
- ⚠️ Pre-roll is useful for capturing the start of sounds that triggered recording.
CLI Commands:
- Get value: show pre or show audio.preRecordMs
- Set value: set pre 200 or set audio.preRecordMs 200
mrm / minRecordingMs - Minimum Recording DurationAbbreviation: mrm
Full Name: Minimum Recording Milliseconds
Type: Integer (milliseconds)
Range: > 0 ms (typically 100 - 10000 ms)
Default: 1000 ms (1 second)
Purpose: Minimum duration for a recording. Shorter captures may be extended or filtered out.
System Impact:
- File Filtering: Recordings shorter than this may be discarded (if discardSmallFilesEnabled is true).
- Storage: Prevents creation of very short files that may be noise.
- Processing: Ensures recordings have minimum useful length.
Warning:
- ⚠️ Must be greater than 0.
- ⚠️ Must be less than maxRecordingMs.
- ⚠️ Too low (< 500 ms) may create many small files from brief noise.
- ⚠️ Too high (> 5000 ms) may extend unwanted recordings.
CLI Commands:
- Get value: show min or show audio.minRecordingMs
- Set value: set min 1000 or set audio.minRecordingMs 1000
xrm / maxRecordingMs - Maximum Recording DurationAbbreviation: xrm
Full Name: Maximum Recording Milliseconds
Type: Integer (milliseconds)
Range: > 0 ms (typically 10000 - 300000 ms)
Default: 60000 ms (60 seconds)
Purpose: Upper bound on recording length for a single clip. Recordings are automatically stopped at this duration.
System Impact:
- File Size: Limits maximum file size (approximately 1 MB per minute at 8 kHz).
- Storage: Prevents single recordings from consuming excessive storage.
- Upload: Large files take longer to upload and may timeout.
- Segmentation: Long audio is split into multiple files.
Warning:
- ⚠️ Must be greater than 0.
- ⚠️ Must be greater than or equal to minRecordingMs.
- ⚠️ Too low (< 10 seconds) may cut off important audio.
- ⚠️ Too high (> 5 minutes) creates large files that may fail to upload.
CLI Commands:
- Get value: show max or show audio.maxRecordingMs
- Set value: set max 60000 or set audio.maxRecordingMs 60000
stm / silenceThresholdMs - Silence ThresholdAbbreviation: stm
Full Name: Silence Threshold Milliseconds
Type: Integer (milliseconds)
Range: 500 - 30000 ms (0.5 - 30 seconds)
Default: 2000 ms (2 seconds)
Purpose: Duration of continuous silence before the recorder automatically stops recording.
System Impact:
- Auto-Stop: Recording stops automatically after this duration of silence.
- File Size: Reduces file size by stopping when audio ends.
- Storage: Saves storage by not recording long periods of silence.
- False Stops: Too short may stop during brief pauses in speech.
Warning:
- ⚠️ Too short (< 1 second) may stop during natural pauses in speech.
- ⚠️ Too long (> 10 seconds) wastes storage on silence.
- ⚠️ Consider your use case: speech vs. environmental sounds.
CLI Commands:
- Get value: show silence or show audio.silenceThresholdMs
- Set value: set silence 2000 or set audio.silenceThresholdMs 2000
cg / codecGain - Codec Input GainAbbreviation: cg
Full Name: Codec Gain
Type: Integer (dB)
Range: -3, 0, 3, 6, 9, 12, 15, 18, 21, 24 dB (snapped to nearest)
Default: 0 dB
Purpose: Input gain applied by the audio codec hardware to adjust recording level. Positive values amplify input, negative values attenuate.
System Impact:
- Recording Level: Higher gain increases recording volume (may cause clipping if too high).
- Sensitivity: Higher gain makes microphone more sensitive to quiet sounds.
- Distortion: Too high gain causes clipping and distortion.
- Noise: Higher gain amplifies both signal and noise.
Warning:
- ⚠️ Values are snapped to nearest allowed value (-3, 0, 3, 6, 9, 12, 15, 18, 21, 24).
- ⚠️ Too high (> 18 dB) may cause clipping and distortion.
- ⚠️ Too low (< 0 dB) may result in quiet recordings.
- ⚠️ Test with your microphone to find optimal gain.
CLI Commands:
- Get value: show gain or show audio.codecGain
- Set value: set gain 0 or set audio.codecGain 0 (values are snapped to nearest: -3, 0, 3, 6, 9, 12, 15, 18, 21, 24)
dsf / discardSmallFilesEnabled - Discard Small FilesAbbreviation: dsf
Full Name: Discard Small Files Enabled
Type: Boolean
Range: true or false
Default: false
Purpose: When enabled, very short recordings (below discardSmallFilesMinMs) are automatically discarded to reduce noise and storage usage.
System Impact:
- Storage: Reduces storage usage by discarding very short files (likely noise).
- Upload: Reduces upload traffic and server load.
- False Positives: May discard legitimate very short sounds.
Warning:
- ⚠️ Only effective when discardSmallFilesMinMs is configured.
- ⚠️ May discard legitimate short audio events.
- ⚠️ Useful for filtering out brief noise triggers.
CLI Commands:
- Get value: show audio.discardSmallFilesEnabled
- Set value: set audio.discardSmallFilesEnabled true
dmm / discardSmallFilesMinMs - Minimum Duration for DiscardAbbreviation: dmm
Full Name: Discard Small Files Minimum Milliseconds
Type: Integer (milliseconds)
Range: > 0 ms
Default: 1000 ms (1 second)
Purpose: Minimum duration below which recordings are considered "too small" and discarded when discardSmallFilesEnabled is true.
System Impact:
- Filtering: Files shorter than this are discarded.
- Storage: Reduces storage usage.
- Loss: Legitimate short sounds are lost.
Warning:
- ⚠️ Only used when discardSmallFilesEnabled is true.
- ⚠️ Should be less than minRecordingMs to be effective.
- ⚠️ Consider your use case: do you need very short recordings?
CLI Commands:
- Get value: show audio.discardSmallFilesMinMs
- Set value: set audio.discardSmallFilesMinMs 1000
ah / apiHosts - API HostnamesAbbreviation: ah
Full Name: API Hosts
Type: Array of strings (maximum 3 entries)
Range: Valid hostnames or IP addresses (max 63 characters each)
Default: ["api.oh.boondock.cloud", "api.or.boondock.cloud", "api.vi.boondock.cloud"]
Purpose: Hostnames or IP addresses of API endpoints used for uploading audio files.
System Impact:
- Redundancy: Multiple endpoints provide failover if one is unavailable.
- Load Distribution: Uploads are distributed across enabled endpoints.
- Connection: Changing hosts invalidates cached endpoint state and triggers reconnection.
- Failover: Device automatically tries next endpoint if current one fails.
Warning:
- ⚠️ Hostnames must be resolvable via DNS.
- ⚠️ Changing hosts requires matching port configuration (apiPorts).
- ⚠️ Ensure endpoints are accessible from your network.
CLI Commands:
- Get value: show host0 or show host1 or show host2 (for endpoints 0, 1, or 2) or show upload.apiHosts[0]
- Set value: set host0 api.example.com or set upload.apiHosts[0] api.example.com
ap / apiPorts - API PortsAbbreviation: ap
Full Name: API Ports
Type: Array of integers (TCP port numbers)
Range: 1 - 65535 (port 0 is invalid and ignored)
Default: [7001, 7001, 7001]
Purpose: TCP port numbers for each API endpoint. Must match the port the server is listening on.
System Impact:
- Connection: Port must match server configuration.
- SSL/TLS: Port 443 typically indicates HTTPS, other ports may be HTTP.
- Firewall: Ensure firewall allows outbound connections to these ports.
Warning:
- ⚠️ Port 0 is invalid and causes endpoint to be ignored.
- ⚠️ Port must match server configuration exactly.
- ⚠️ Ensure network firewall allows outbound connections.
CLI Commands:
- Get value: show upload.apiPorts[0] or show upload.apiPorts[1] or show upload.apiPorts[2]
- Set value: set upload.apiPorts[0] 7001
en / enabled - Endpoint Enabled FlagsAbbreviation: en
Full Name: Enabled
Type: Array of booleans (one per endpoint)
Range: true or false for each endpoint
Default: [true, true, true] (all enabled)
Purpose: Per-endpoint enable flags indicating which API endpoints are actively used for uploads.
System Impact:
- Upload Selection: Only enabled endpoints are used for uploads.
- Failover: Disabled endpoints are skipped during failover.
- Testing: Can disable endpoints for testing without removing configuration.
Warning:
- ⚠️ At least one endpoint should be enabled for uploads to work.
- ⚠️ If all endpoints are disabled, uploads will fail.
CLI Commands:
- Get value: show upload.enabled[0] or show upload.enabled[1] or show upload.enabled[2]
- Set value: set upload.enabled[0] true
qd / queueDepth - Queue Depth (Legacy)Abbreviation: qd
Full Name: Queue Depth
Type: Integer
Range: 4 - 32 (clamped)
Default: 4
Purpose: Legacy parameter indicating desired upload queue depth. The modern filesystem-based queue may not rely on this directly but it is preserved for compatibility.
System Impact:
- Legacy: May not be actively used by current firmware.
- Compatibility: Kept for backward compatibility with older configurations.
Warning: ⚠️ This is a legacy setting and may not affect current behavior.
CLI Commands:
- Get value: show upload.queueDepth
- Set value: set upload.queueDepth 4
ctm / convertToMp3 - Convert to MP3 (Legacy)Abbreviation: ctm
Full Name: Convert To MP3
Type: Boolean
Range: true or false
Default: true
Purpose: Legacy flag indicating whether to transcode recordings to MP3 before upload. Kept for backward compatibility.
System Impact:
- Legacy: May not be actively used by current firmware.
- Compatibility: Kept for backward compatibility.
Warning: ⚠️ This is a legacy setting and may not affect current behavior.
CLI Commands:
- Get value: show upload.convertToMp3
- Set value: set upload.convertToMp3 true
r / rtc - RTC Configuration ObjectType: Object
Purpose: Configuration for external Real-Time Clock (RTC) hardware module.
System Impact:
- Time Accuracy: External RTC provides accurate time even when WiFi is unavailable.
- Battery Backup: RTC modules with battery backup maintain time across power cycles.
- I²C Communication: Uses I²C protocol for communication.
Warning: ⚠️ Requires compatible RTC hardware module (e.g., DS1307, DS3231).
en / enabled - RTC EnabledAbbreviation: en
Full Name: RTC Enabled
Type: Boolean
Range: true or false
Default: false
Purpose: Enables use of external RTC hardware for time synchronization.
System Impact:
- Time Source: When enabled, device uses RTC for time instead of NTP.
- Accuracy: RTC provides accurate time even without WiFi.
- Battery: RTC modules with battery backup maintain time during power loss.
Warning: ⚠️ Requires RTC hardware to be connected and properly configured.
CLI Commands:
- Get value: show rtc.enabled
- Set value: set rtc.enabled true
sda / sdaPin - I²C SDA PinAbbreviation: sda
Full Name: SDA Pin
Type: Integer (GPIO pin number)
Range: Valid GPIO pin number for your ESP32 board
Default: 5
Purpose: GPIO pin number for I²C SDA (Serial Data) line connection to RTC module.
System Impact:
- Communication: Must match physical wiring to RTC module.
- Conflict: Ensure pin is not used by other peripherals.
Warning:
- ⚠️ Pin number depends on your ESP32 board variant.
- ⚠️ Ensure pin matches physical wiring.
- ⚠️ Check board pinout diagram for correct pin numbers.
CLI Commands:
- Get value: show rtc.sdaPin
- Set value: set rtc.sdaPin 5
scl / sclPin - I²C SCL PinAbbreviation: scl
Full Name: SCL Pin
Type: Integer (GPIO pin number)
Range: Valid GPIO pin number for your ESP32 board
Default: 18
Purpose: GPIO pin number for I²C SCL (Serial Clock) line connection to RTC module.
System Impact:
- Communication: Must match physical wiring to RTC module.
- Conflict: Ensure pin is not used by other peripherals.
Warning:
- ⚠️ Pin number depends on your ESP32 board variant.
- ⚠️ Ensure pin matches physical wiring.
- ⚠️ SCL and SDA pins must be different.
CLI Commands:
- Get value: show rtc.sclPin
- Set value: set rtc.sclPin 18
s / sdCard - SD Card Configuration ObjectType: Object
Purpose: Configuration for SD card storage and recording.
System Impact:
- Storage Mode: When SD card is enabled, recordings are stored on SD card instead of PSRAM.
- Capacity: SD card provides much larger storage capacity than PSRAM.
- Reliability: SD card storage is more reliable for long-term storage.
Warning: ⚠️ SD card must be properly formatted (FAT32) and inserted before enabling.
usc / useSdCard - Use SD CardAbbreviation: usc
Full Name: Use SD Card
Type: Boolean
Range: true or false
Default:
- false for TANGO firmware
- true for EDGE/ECHO firmware
Purpose: Enables SD card usage in general (mounting, space checks, etc.).
System Impact:
- Storage: When enabled, device attempts to mount SD card on startup.
- Fallback: If SD card fails to mount, device falls back to PSRAM mode.
- Performance: SD card operations are slower than PSRAM but provide more storage.
Warning:
- ⚠️ SD card must be inserted and properly formatted before enabling.
- ⚠️ If SD card is not available, device uses PSRAM mode automatically.
- ⚠️ Changing this setting requires device restart to take effect.
CLI Commands:
- Get value: show sdcard.useSdCard or show sdCard.useSdCard
- Set value: set sdcard.useSdCard true or set sdCard.useSdCard true
rsc / recordToSdCard - Record to SD CardAbbreviation: rsc
Full Name: Record To SD Card
Type: Boolean
Range: true or false
Default:
- false for TANGO firmware
- true for EDGE/ECHO firmware
Purpose: When enabled, audio recordings are written to the SD card instead of PSRAM.
System Impact:
- Storage Capacity: SD card provides much larger storage (GB) vs PSRAM (MB).
- File Persistence: Files on SD card persist across reboots.
- Upload Queue: Files are queued in /pending directory on SD card.
- Performance: SD card writes are slower than PSRAM but provide more capacity.
Warning:
- ⚠️ Requires useSdCard to be true.
- ⚠️ SD card must have sufficient free space.
- ⚠️ Slow SD cards may cause recording dropouts.
CLI Commands:
- Get value: show sdcard.recordToSdCard or show sdCard.recordToSdCard
- Set value: set sdcard.recordToSdCard true or set sdCard.recordToSdCard true
m1b / mode1bit - 1-Bit ModeAbbreviation: m1b
Full Name: Mode 1 Bit
Type: Boolean
Range: true or false
Default: false (4-bit mode)
Purpose: Selects 1-bit SD bus mode when true, which reduces pin count at the cost of throughput.
System Impact:
- Pin Usage: 1-bit mode uses fewer GPIO pins (2 pins vs 6 pins for 4-bit).
- Speed: 1-bit mode is slower than 4-bit mode (approximately 4x slower).
- Compatibility: Some SD cards may not work reliably in 1-bit mode.
Warning:
- ⚠️ 1-bit mode is significantly slower - may cause recording issues.
- ⚠️ Use 4-bit mode unless you need to free GPIO pins.
- ⚠️ Some SD cards may not work in 1-bit mode.
CLI Commands:
- Get value: show sdcard.mode1bit or show sdCard.mode1bit
- Set value: set sdcard.mode1bit false or set sdCard.mode1bit false
frq / frequency - SD Card Bus FrequencyAbbreviation: frq
Full Name: Frequency
Type: Integer (Hz)
Range: 1,000,000 - 20,000,000 Hz (1 - 20 MHz)
Default: 10000000 (10 MHz)
Purpose: SD card bus clock frequency. Higher frequencies provide faster data transfer but may cause reliability issues with some cards.
System Impact:
- Speed: Higher frequency = faster read/write operations.
- Reliability: Some SD cards may not work reliably at high frequencies.
- Power: Higher frequency may increase power consumption slightly.
Warning:
- ⚠️ Values outside 1-20 MHz range are ignored.
- ⚠️ High frequencies (> 15 MHz) may cause reliability issues with some SD cards.
- ⚠️ Start with default (10 MHz) and increase only if needed.
CLI Commands:
- Get value: show sdcard.frequency or show sdCard.frequency
- Set value: set sdcard.frequency 10000000 or set sdCard.frequency 10000000
fmf / formatIfMountFailed - Format If Mount FailedAbbreviation: fmf
Full Name: Format If Mount Failed
Type: Boolean
Range: true or false
Default: false
Purpose: When enabled, device may attempt to format the SD card when mounting fails.
System Impact:
- Data Loss: ⚠️ WARNING: Formatting erases all data on SD card!
- Recovery: May recover corrupted SD cards by reformatting.
- Risk: May format cards that are temporarily unavailable (e.g., loose connection).
Warning:
- ⚠️ CRITICAL: Enabling this may cause data loss if SD card mount fails!
- ⚠️ Only enable if you understand the risks and have backups.
- ⚠️ Formatting erases all files on the SD card.
- ⚠️ Recommended to keep disabled unless troubleshooting.
CLI Commands:
- Get value: show sdcard.formatIfMountFailed or show sdCard.formatIfMountFailed
- Set value: set sdcard.formatIfMountFailed false or set sdCard.formatIfMountFailed false
t / timezone - Timezone Configuration ObjectType: Object
Purpose: Device timezone offset and daily maintenance window configuration.
System Impact:
- Time Display: Affects how timestamps are displayed and stored.
- Maintenance: Defines when daily maintenance tasks run.
- Scheduling: Used for time-based operations.
oh / offsetHours - Timezone OffsetAbbreviation: oh
Full Name: Offset Hours
Type: Integer (hours)
Range: -12 to +14 (clamped to this range)
Default: 0 (UTC)
Purpose: Fixed timezone offset from UTC in hours. Used to convert UTC time to local time.
System Impact:
- Timestamps: Affects how recording timestamps are calculated.
- File Names: Recording filenames use local time based on this offset.
- Display: Time shown in status messages uses this offset.
Examples:
- 0 = UTC (Coordinated Universal Time)
- -5 = EST (Eastern Standard Time)
- -8 = PST (Pacific Standard Time)
- +5 = IST (India Standard Time)
- +9 = JST (Japan Standard Time)
Warning:
- ⚠️ Values outside -12 to +14 are clamped to valid range.
- ⚠️ Does not account for Daylight Saving Time (DST) - fixed offset only.
- ⚠️ Must manually adjust for DST if needed.
CLI Commands:
- Get value: show timezone.offsetHours
- Set value: set timezone.offsetHours -5 (for EST) or set timezone.offsetHours 0 (for UTC)
mh / maintenanceHour - Maintenance HourAbbreviation: mh
Full Name: Maintenance Hour
Type: Integer (hour of day)
Range: 0 - 23 (clamped)
Default: 3 (3 AM)
Purpose: Hour of day (local time) when daily maintenance tasks may run.
System Impact:
- Scheduling: Maintenance tasks run at this hour (plus maintenanceMinute).
- Network: Maintenance may include uploading logs, syncing settings, etc.
- Timing: Should be set to low-activity hours to minimize impact.
Warning:
- ⚠️ Values outside 0-23 are clamped.
- ⚠️ Uses local time (based on offsetHours).
- ⚠️ Set to off-peak hours to minimize impact.
CLI Commands:
- Get value: show timezone.maintenanceHour
- Set value: set timezone.maintenanceHour 3 (for 3 AM)
mm / maintenanceMinute - Maintenance MinuteAbbreviation: mm
Full Name: Maintenance Minute
Type: Integer (minute of hour)
Range: 0 - 59 (clamped)
Default: 0
Purpose: Minute within the maintenance hour for scheduled maintenance.
System Impact:
- Precision: Allows fine-tuning of maintenance schedule.
- Distribution: Multiple devices can be staggered by setting different minutes.
Warning:
- ⚠️ Values outside 0-59 are clamped.
- ⚠️ Combined with maintenanceHour to form full time (e.g., 3:00 AM).
CLI Commands:
- Get value: show timezone.maintenanceMinute
- Set value: set timezone.maintenanceMinute 0
l / log - Logging Configuration ObjectType: Object
Purpose: Per-channel log level enables for serial and file logging. Allows fine-grained control over verbosity and storage use.
System Impact:
- Serial Output: Controls what appears on Serial port (CLI).
- File Logging: Controls what is written to log files on SD card.
- Storage: More verbose logging uses more storage space.
- Performance: Excessive logging may impact performance.
Warning: ⚠️ Enabling debug logging generates large amounts of output and may impact performance.
These settings control what appears on the Serial port (CLI).
sf / serialFatal - Serial FatalAbbreviation: sf
Full Name: Serial Fatal
Type: Boolean
Range: true or false
Default: true
Purpose: Enable fatal-level messages on serial output.
System Impact: Critical error messages that cause system shutdown are displayed.
CLI Commands:
- Get value: show log.serialFatal
- Set value: set log.serialFatal true
se / serialError - Serial ErrorAbbreviation: se
Full Name: Serial Error
Type: Boolean
Range: true or false
Default: true
Purpose: Enable error-level messages on serial output.
System Impact: Error messages indicating problems are displayed.
CLI Commands:
- Get value: show log.serialError
- Set value: set log.serialError true
sw / serialWarning - Serial WarningAbbreviation: sw
Full Name: Serial Warning
Type: Boolean
Range: true or false
Default: true
Purpose: Enable warning-level messages on serial output.
System Impact: Warning messages about potential issues are displayed.
CLI Commands:
- Get value: show log.serialWarning
- Set value: set log.serialWarning true
si / serialInfo - Serial InfoAbbreviation: si
Full Name: Serial Info
Type: Boolean
Range: true or false
Default: false
Purpose: Enable informational messages on serial output.
System Impact: General informational messages are displayed. Enabling increases serial output volume.
Warning: ⚠️ Enabling generates significant serial output.
CLI Commands:
- Get value: show log.serialInfo
- Set value: set log.serialInfo false
sd / serialDebug - Serial DebugAbbreviation: sd
Full Name: Serial Debug
Type: Boolean
Range: true or false
Default: false
Purpose: Enable debug-level messages on serial output.
System Impact: Detailed debug messages are displayed. Enabling generates very high serial output volume.
Warning:
- ⚠️ Enabling generates very large amounts of serial output.
- ⚠️ May impact performance.
- ⚠️ Use only for troubleshooting.
CLI Commands:
- Get value: show log.serialDebug
- Set value: set log.serialDebug false
sev / serialEvent - Serial EventAbbreviation: sev
Full Name: Serial Event
Type: Boolean
Range: true or false
Default: true
Purpose: Enable event-style messages on serial (e.g., state transitions).
System Impact: Event messages (like recording start/stop, upload start/stop) are displayed.
CLI Commands:
- Get value: show log.serialEvent
- Set value: set log.serialEvent true
These settings control what is written to log files on SD card.
ff / fileFatal - File FatalAbbreviation: ff
Full Name: File Fatal
Type: Boolean
Range: true or false
Default: true
Purpose: Enable fatal-level messages in log files.
System Impact: Critical error messages are written to log files.
CLI Commands:
- Get value: show log.fileFatal
- Set value: set log.fileFatal true
fe / fileError - File ErrorAbbreviation: fe
Full Name: File Error
Type: Boolean
Range: true or false
Default: true
Purpose: Enable error-level messages in log files.
System Impact: Error messages are written to log files.
CLI Commands:
- Get value: show log.fileError
- Set value: set log.fileError true
fw / fileWarning - File WarningAbbreviation: fw
Full Name: File Warning
Type: Boolean
Range: true or false
Default: true
Purpose: Enable warning-level messages in log files.
System Impact: Warning messages are written to log files.
CLI Commands:
- Get value: show log.fileWarning
- Set value: set log.fileWarning true
fi / fileInfo - File InfoAbbreviation: fi
Full Name: File Info
Type: Boolean
Range: true or false
Default: false
Purpose: Enable informational messages in log files.
System Impact: General informational messages are written to log files. Enabling increases log file size.
Warning: ⚠️ Enabling increases log file size significantly.
CLI Commands:
- Get value: show log.fileInfo
- Set value: set log.fileInfo false
fd / fileDebug - File DebugAbbreviation: fd
Full Name: File Debug
Type: Boolean
Range: true or false
Default: false
Purpose: Enable debug-level messages in log files.
System Impact: Detailed debug messages are written to log files. Enabling generates very large log files.
Warning:
- ⚠️ Enabling generates very large log files.
- ⚠️ May fill SD card quickly.
- ⚠️ Use only for troubleshooting.
CLI Commands:
- Get value: show log.fileDebug
- Set value: set log.fileDebug false
fev / fileEvent - File EventAbbreviation: fev
Full Name: File Event
Type: Boolean
Range: true or false
Default: true
Purpose: Enable event-style messages in log files.
System Impact: Event messages are written to log files.
CLI Commands:
- Get value: show log.fileEvent
- Set value: set log.fileEvent true
These settings are computed at runtime and cannot be changed by the user.
fw / firmware - Firmware VersionAbbreviation: fw
Full Name: Firmware
Type: String
Direction: Read-only
Purpose: Identifies the running firmware version. Useful for diagnostics and matching server-side expectations.
Example: "EDGE-2025-12-17"
CLI Commands:
- Get value: show firmware (read-only, cannot be set)
cv / configVersion - Configuration VersionAbbreviation: cv
Full Name: Config Version
Type: String
Direction: Read-only
Purpose: Schema version for the configuration JSON. Used internally for backward-compatible migrations.
Example: "1.0.0"
CLI Commands:
- Get value: show configVersion (read-only, cannot be set)
mac - Device ID / MAC AddressAbbreviation: mac
Full Name: MAC Address
Type: String
Direction: Read-only
Purpose: Unique device identifier, typically derived from the MAC address. Used for device identification and tracking.
Example: "AA:BB:CC:DD:EE:FF"
CLI Commands:
- Get value: show mac or use mac command (read-only, cannot be set)
cws / connectedWiFiSsid - Connected WiFi SSIDAbbreviation: cws
Full Name: Connected WiFi SSID
Type: String
Direction: Read-only
Purpose: Index into the WiFi credentials array (w) corresponding to the credential that matched the current WiFi connection, or -1 if unknown.
CLI Commands:
- Get value: Use status command to view connected WiFi SSID (read-only, cannot be set)
cwi / connectedWiFiIndex - Connected WiFi IndexAbbreviation: cwi
Full Name: Connected WiFi Index
Type: Integer
Direction: Read-only
Purpose: Index into the WiFi credentials array (w) corresponding to the credential that matched the current WiFi connection, or -1 if unknown.
CLI Commands:
- Get value: Use status command to view connected WiFi index (read-only, cannot be set)
rt / runtime - Runtime MetadataAbbreviation: cwi
Full Name: Connected WiFi Index
Type: Integer
Direction: Read-only
Purpose: Index into the WiFi credentials array (w) corresponding to the credential that matched the current WiFi connection, or -1 if unknown.
rt / runtime - Runtime MetadataAbbreviation: rt
Full Name: Runtime
Type: Object
Direction: Read-only
Purpose: Snapshot of current network/runtime status for UI consumption. Recomputed on each serialization and not persisted.
Fields:
- mac - Device ID
- wc - WiFi connected status
- css - Connected SSID
- rss - RSSI value
- ci - Connected index
CLI Commands:
- Get value: Use status command to view runtime metadata (read-only, cannot be set)
cip / currentIp - Current IP ConfigurationAbbreviation: cip
Full Name: Current IP
Type: Object
Direction: Read-only
Purpose: Current IP configuration for the WiFi interface. Only present if an IP/subnet/gateway/DNS is available.
Fields:
- ip - Current IPv4 address
- sub - Subnet mask
- gw - Default gateway
- d1 - Primary DNS server
- d2 - Secondary DNS server
CLI Commands:
- Get value: Use ip command or status command to view current IP (read-only, cannot be set)
recordToSdCard requires useSdCard to be trueSD card must be physically inserted and formatted
Static IP:
sip, ssn, sgt, sd1, sd2) only used when staticIpEnabled is trueAll static IP fields should be configured together
RTC:
sda, scl) only used when rtc.enabled is trueRequires physical RTC hardware connection
Upload Endpoints:
apiPorts and enabled arrays must match apiHosts array lengthuseSdCard - SD card mounting happens at startupmode1bit - SD card bus mode set during initializationfrequency - SD card frequency set during initializationwifiTxPower - Applied immediately if WiFi is connectedcodecGain - Applied immediately to audio codecexport command to check current valuessave command completed successfully