Serial Commands
This page documents the USB serial command interface of the bcMeter (ESP32 commercial device).
Raspberry Pi (DIY) note: The Raspberry Pi version of bcMeter does not have a serial command protocol. All control and diagnostics on the Pi are handled through the HTTP API (see API reference). The information on this page applies exclusively to the bcMeter (ESP32).
Connect via USB-C at 115200 baud:
# macOS / Linux
screen /dev/tty.usbmodem* 115200
# Or via minicom
minicom -D /dev/ttyACM0 -b 115200
Commands are plain text, terminated with a newline. The serial interface is always available regardless of measurement or WiFi mode.
Status & Diagnostics
| Command |
Description
|
status |
Compact one-liner: state, init step, error, BC, ATN, sensor/reference voltages, flow, pump duty, filter loading, sample count.
|
status json |
Same data as a JSON object — suitable for scripting and QC tooling.
|
system |
Firmware version, env, free heap, PSRAM usage, flash usage, WiFi mode/SSID/IP/RSSI, MAC address, time-sync state.
|
sensors |
Live read of all peripheral sensors: pump flow + duty + airflow voltage + bias, temperature/humidity/pressure (BME280 or SHT4x), GPS fix (if present), SPS30 PM values (if present).
|
pumpinfo |
Detailed pump diagnostics: duty, flow (L/min), airflow voltage, bias, target flow, recovering flag, failed flag.
|
logs [N] |
Print the last N incident log entries (default: all). Newest first.
|
crash |
Last reset reason and crash report JSON (if a watchdog/panic crash was recorded on previous boot).
|
ver / version |
Firmware version string and environment tag (prod/dev).
|
bcm:probe |
Machine-readable JSON identity probe for QC tooling: device name, MAC, firmware version, environment, uptime. Output is a single line prefixed for easy grep/parse.
|
cfg |
Quick display of key config values: mail_logs_to, onboarding_step_one/two, device_name, send_log_by_mail.
|
STATUS (caps) |
Machine-readable one-liner for QC scripts: OK sampling=... serLab=... adcPresent=... debug=... version=...
|
Measurement & Calibration
| Command |
Description
|
start |
Start measurement. Fails with an error message if time is not synced. Use start force to override the time-sync check.
|
start force |
Start measurement unconditionally (bypasses time-sync guard).
|
stop |
Stop measurement.
|
calibrate |
Start optical calibration (same routine as the web UI). Requires sampling to be stopped.
|
clear_error / clearerr |
Reset the error state to ERR_NONE.
|
identify |
Start LED identify blink pattern (Morse "bcmeter", ~30 s). Used to locate a specific device.
|
identify_stop / identifystop |
Stop the identify blink.
|
tempcal |
Toggle temperature calibration routine. If already running, stops it. Requires sampling stopped.
|
factory_reset |
Mirror of /api/control?action=factory_reset: stops sampling, erases all logs and config, reboots into factory state. Used by QC provisioning workflow.
|
Configuration — Read & Write
| Command |
Description
|
get <key> |
Print a single config key with its type and current value.
|
set <key> <value> |
Write a string config key to NVS. Special handling for onboarding_step_one / onboarding_step_two (stored as bool).
|
setint <key> <value> |
Write an integer config key.
|
setfloat <key> <value> |
Write a float config key.
|
| false> |
Write a bool config key. Accepts 1, true, on, yes as true.
|
cfgall [prefix] |
Dump all config entries, optionally filtered by key prefix.
|
cfgjson |
Dump entire config as a JSON object (same structure as /api/config).
|
Time Configuration
| Command |
Description
|
settime <epoch> |
Inject wall time (POSIX epoch seconds). Refuses values before 2023-11-14. Used when NTP is not available.
|
settz <POSIX TZ> |
Set the POSIX timezone string, e.g. CET-1CEST,M3.5.0/2,M10.5.0/3. Persists to NVS and applies immediately.
|
Hardware Diagnostics
| Command |
Description
|
led <ch> <duty> |
Set LED brightness. Channel 0–2 (880 / 520 / 370 nm), duty 0–255. Turns the channel on immediately.
|
pump <duty> |
Set pump PWM duty cycle (0–255). Use pumplock on first to prevent the control task from overriding this.
|
pumplock on |
Hand pump control to the serial operator — the automatic pump control task yields while locked.
|
pumplock off |
Restore automatic pump control.
|
adc |
Detect ADS1220 ADC and print current raw channel values. Reports "ADC OK" or "ADC not detected".
|
sps30 |
One-shot read from SPS30 particulate matter sensor. Returns PM2.5 and PM10 in µg/m³.
|
gps |
GPS status: fix validity, satellite count, HDOP, latitude/longitude, altitude, speed, date/time.
|
WiFi
| Command |
Description
|
wifi |
Current WiFi state: mode (AP/STA), SSID, IP address, RSSI, internet reachability, time-sync status.
|
scan |
Scan for nearby WiFi networks, print SSID, RSSI, and open/secured flag.
|
connect <ssid> <password> |
Save WiFi credentials to NVS and initiate connection.
|
ap |
Switch to access-point (hotspot) mode.
|
wificlear |
Delete stored WiFi credentials and force AP mode. Used in QC to ensure the 4G modem test cannot fall back to WiFi.
|
Modem / 4G
| Command |
Description
|
modem <AT command> |
Send a raw AT command to the SIM7080G modem and print the response. Requires modem to be powered on first.
|
modemscan |
Scan UART configurations to detect modem baud rate and port.
|
modemon |
Power on and initialise the modem.
|
modemoff |
Power off the modem.
|
debugmobile |
Trigger the debug-mobile email send (same as /api/control?action=debug_mobile). Sends a diagnostic email via the 4G modem.
|
modemlog |
Synchronously trigger the modem log streaming path (chunked upload to Lambda). Prints OK/FAIL.
|
postest <url> <size> |
POST a padded test payload of the given byte size to a URL via the modem. Used to verify HTTP POST framing over 4G. Lambda responds 200 to _coap_test payloads.
|
Storage & Session
| Command |
Description
|
storage |
Show LittleFS usage (used/total bytes), SD card presence, active session filename, and write-buffer depth.
|
export |
Export all log files to SD card.
|
startsess |
Manually start a new storage session (creates a new CSV file).
|
endsess |
Manually end the current storage session.
|
loginfo |
Print current session filename, file size, remote-sent offset, session-active flag, and free heap.
|
| current> |
Delete a named log file, or the current session if current is given.
|
gentest <KB> |
Write a synthetic CSV log of the given size (1–1024 KB) for storage stress-testing.
|
resetoffset |
Reset the remote-sent byte offset to 0 (forces re-upload of the current session on the next mail cycle).
|
reset |
Reboot the device.
|
Email & QC
| Command |
Description
|
testemail [4g] |
Send a test status email. Without 4g, sends via WiFi/Lambda. With 4g, forces 4G modem path. Recipient is mail_logs_to (falls back to jd@bcmeter.org).
|
qcemail <type> <json> |
Send a QC result email via 4G modem. type is the email subject key; json is the JSON payload. Used by the provisioning QC workflow.
|
Lab / Engineering Mode
These commands are used during hardware characterisation and manufacturing tests. They require no special mode to be active — they are always available.
| Command |
Description
|
PING |
Responds PONG\n. Used by QC scripts to verify serial connectivity.
|
LAB <ch> <led_duty> <pump_duty> <pump_hz> <n_pairs> |
Run a lab ADC capture session: set LED channel/duty and pump duty/frequency, capture N raw ADC pairs, return binary data over serial.
|
STREAM <ch> <led_duty> <led_hz> <target_ml> <pump_hz> <duration_s> |
Streaming lab mode: continuous ADC pairs with airflow control for the given duration.
|
LABFLOW <ch> <led_duty> <led_hz> <target_ml> <pump_hz> <n_pairs> |
Lab mode with airflow target: capture N pairs at controlled flow rate.
|
LABEND |
End the current lab session. Responds OK\n.
|
STOP |
Acknowledge stop. Used by QC scripts as a generic stop/sync marker.
|
SILENCE on |
Suppress serial log output during lab capture (reduces USB-CDC overhead).
|
SILENCE off |
Re-enable serial log output.
|
ADCMODE <0–6> |
Set ADS1220 data rate: 0=20, 1=45, 2=90, 3=175, 4=330, 5=600+turbo (→1200), 6=1000+turbo (→2000) SPS.
|
Debug Isolation (MUTE)
Used to isolate audible or electrical noise sources by progressively silencing PWM and RF emitters.
| Command |
Description
|
MUTE status on |
Pause the status LED task (pin to high-Z). Reversible without reset.
|
MUTE status off |
Resume the status LED task.
|
MUTE leds |
Detach all three measurement LED PWM channels (requires reset to restore).
|
MUTE pump |
Detach the pump PWM channel (requires reset to restore).
|
MUTE wifi |
Disconnect WiFi and turn off the radio (requires reset to restore).
|
General
| Command |
Description
|
help |
Print a grouped command summary to the serial console.
|
Usage Examples
# Check device status
> status
[Status] state=idle(0) init=0:... err=0:OK bc=0.0 atn=0.000 ...
# Start measurement (after syncing time via the web UI)
> start
OK sampling started
# Read live sensor snapshot
> sensors
[Pump] flow=0.3001 LPM duty=80 v=1.234 bias=0.002
[Env] T=22.50°C H=48.3% P=1013.2 hPa
[GPS] fix=YES sats=7 hdop=1.2 52.463100,13.306900 alt=48m
# Manually test pump at a fixed duty (lock first to prevent auto-override)
> pumplock on
OK pump locked — controlTask yielding
> pump 120
Pump set to 120
> pumpinfo
[Pump] duty=120 flow=0.4210 ...
> pumplock off
OK pump unlocked
# Set device timezone
> settz CET-1CEST,M3.5.0/2,M10.5.0/3
OK tz=CET-1CEST,M3.5.0/2,M10.5.0/3
# Probe via QC tooling
> bcm:probe
{"_bcm":1,"schema":"probe/v1","name":"bcmeter-A1B2","mac":"AA:BB:CC:DD:EE:FF","fw":"1.5.230","env":"prod","up":3721}