Difference between revisions of "Serial commands"

From bcmeter.org
Jump to navigation Jump to search
(Update: V1/V2 naming, remove ESP32/Pi distinction)
(Restructure: platform separation (ESP32 commercial prioritised, Raspberry Pi DIY in own section); verified against firmware/Pi source; complete serial command list)
 
Line 1: Line 1:
== Serial Commands ==
== Serial Commands ==


The bcMeter provides a USB serial debug interface for hardware diagnostics and manual control. Connect via USB-C at 115200 baud.
This page documents the USB serial command interface of the '''bcMeter''' (ESP32 commercial device).


=== Available Commands ===
'''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''':
 
<pre>
# macOS / Linux
screen /dev/tty.usbmodem* 115200
 
# Or via minicom
minicom -D /dev/ttyACM0 -b 115200
</pre>
 
Commands are plain text, terminated with a newline. The serial interface is always available regardless of measurement or WiFi mode.
 
=== Status & Diagnostics ===
 
{| class="wikitable"
! Command !! Description
|-
| <code>status</code> || Compact one-liner: state, init step, error, BC, ATN, sensor/reference voltages, flow, pump duty, filter loading, sample count.
|-
| <code>status json</code> || Same data as a JSON object — suitable for scripting and QC tooling.
|-
| <code>system</code> || Firmware version, env, free heap, PSRAM usage, flash usage, WiFi mode/SSID/IP/RSSI, MAC address, time-sync state.
|-
| <code>sensors</code> || 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).
|-
| <code>pumpinfo</code> || Detailed pump diagnostics: duty, flow (L/min), airflow voltage, bias, target flow, recovering flag, failed flag.
|-
| <code>logs [N]</code> || Print the last N incident log entries (default: all). Newest first.
|-
| <code>crash</code> || Last reset reason and crash report JSON (if a watchdog/panic crash was recorded on previous boot).
|-
| <code>ver</code> / <code>version</code> || Firmware version string and environment tag (prod/dev).
|-
| <code>bcm:probe</code> || 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.
|-
| <code>cfg</code> || Quick display of key config values: <code>mail_logs_to</code>, <code>onboarding_step_one/two</code>, <code>device_name</code>, <code>send_log_by_mail</code>.
|-
| <code>STATUS</code> (caps) || Machine-readable one-liner for QC scripts: <code>OK sampling=... serLab=... adcPresent=... debug=... version=...</code>
|}
 
=== Measurement & Calibration ===
 
{| class="wikitable"
! Command !! Description
|-
| <code>start</code> || Start measurement. Fails with an error message if time is not synced. Use <code>start force</code> to override the time-sync check.
|-
| <code>start force</code> || Start measurement unconditionally (bypasses time-sync guard).
|-
| <code>stop</code> || Stop measurement.
|-
| <code>calibrate</code> || Start optical calibration (same routine as the web UI). Requires sampling to be stopped.
|-
| <code>clear_error</code> / <code>clearerr</code> || Reset the error state to ERR_NONE.
|-
| <code>identify</code> || Start LED identify blink pattern (Morse "bcmeter", ~30 s). Used to locate a specific device.
|-
| <code>identify_stop</code> / <code>identifystop</code> || Stop the identify blink.
|-
| <code>tempcal</code> || Toggle temperature calibration routine. If already running, stops it. Requires sampling stopped.
|-
| <code>factory_reset</code> || Mirror of <code>/api/control?action=factory_reset</code>: stops sampling, erases all logs and config, reboots into factory state. Used by QC provisioning workflow.
|}
 
=== Configuration — Read & Write ===
 
{| class="wikitable"
! Command !! Description
|-
| <code>get &lt;key&gt;</code> || Print a single config key with its type and current value.
|-
| <code>set &lt;key&gt; &lt;value&gt;</code> || Write a string config key to NVS. Special handling for <code>onboarding_step_one</code> / <code>onboarding_step_two</code> (stored as bool).
|-
| <code>setint &lt;key&gt; &lt;value&gt;</code> || Write an integer config key.
|-
| <code>setfloat &lt;key&gt; &lt;value&gt;</code> || Write a float config key.
|-
| <code>setbool &lt;key&gt; &lt;true|false&gt;</code> || Write a bool config key. Accepts <code>1</code>, <code>true</code>, <code>on</code>, <code>yes</code> as true.
|-
| <code>cfgall [prefix]</code> || Dump all config entries, optionally filtered by key prefix.
|-
| <code>cfgjson</code> || Dump entire config as a JSON object (same structure as <code>/api/config</code>).
|}
 
=== Time Configuration ===
 
{| class="wikitable"
! Command !! Description
|-
| <code>settime &lt;epoch&gt;</code> || Inject wall time (POSIX epoch seconds). Refuses values before 2023-11-14. Used when NTP is not available.
|-
| <code>settz &lt;POSIX TZ&gt;</code> || Set the POSIX timezone string, e.g. <code>CET-1CEST,M3.5.0/2,M10.5.0/3</code>. Persists to NVS and applies immediately.
|}
 
=== Hardware Diagnostics ===
 
{| class="wikitable"
! Command !! Description
|-
| <code>led &lt;ch&gt; &lt;duty&gt;</code> || Set LED brightness. Channel 0–2 (880 / 520 / 370 nm), duty 0–255. Turns the channel on immediately.
|-
| <code>pump &lt;duty&gt;</code> || Set pump PWM duty cycle (0–255). Use <code>pumplock on</code> first to prevent the control task from overriding this.
|-
| <code>pumplock on</code> || Hand pump control to the serial operator — the automatic pump control task yields while locked.
|-
| <code>pumplock off</code> || Restore automatic pump control.
|-
| <code>adc</code> || Detect ADS1220 ADC and print current raw channel values. Reports "ADC OK" or "ADC not detected".
|-
| <code>sps30</code> || One-shot read from SPS30 particulate matter sensor. Returns PM2.5 and PM10 in µg/m³.
|-
| <code>gps</code> || GPS status: fix validity, satellite count, HDOP, latitude/longitude, altitude, speed, date/time.
|}
 
=== WiFi ===
 
{| class="wikitable"
! Command !! Description
|-
| <code>wifi</code> || Current WiFi state: mode (AP/STA), SSID, IP address, RSSI, internet reachability, time-sync status.
|-
| <code>scan</code> || Scan for nearby WiFi networks, print SSID, RSSI, and open/secured flag.
|-
| <code>connect &lt;ssid&gt; &lt;password&gt;</code> || Save WiFi credentials to NVS and initiate connection.
|-
| <code>ap</code> || Switch to access-point (hotspot) mode.
|-
| <code>wificlear</code> || Delete stored WiFi credentials and force AP mode. Used in QC to ensure the 4G modem test cannot fall back to WiFi.
|}
 
=== Modem / 4G ===


{| class="wikitable"
{| class="wikitable"
! Command !! Description
! Command !! Description
|-
|-
| <code>led <ch> <duty></code> || Set LED brightness. Channel 0–2 (880/520/370nm), duty 0–255.
| <code>modem &lt;AT command&gt;</code> || Send a raw AT command to the SIM7080G modem and print the response. Requires modem to be powered on first.
|-
| <code>modemscan</code> || Scan UART configurations to detect modem baud rate and port.
|-
|-
| <code>pump <duty></code> || Set pump PWM duty cycle (0–255).
| <code>modemon</code> || Power on and initialise the modem.
|-
|-
| <code>adc</code> || Test ADS1220 ADC detection and read current values.
| <code>modemoff</code> || Power off the modem.
|-
|-
| <code>sps30</code> || Quick read from particulate matter sensor.
| <code>debugmobile</code> || Trigger the debug-mobile email send (same as <code>/api/control?action=debug_mobile</code>). Sends a diagnostic email via the 4G modem.
|-
|-
| <code>gps</code> || GPS position report (lat, lon, altitude, satellites, HDOP).
| <code>modemlog</code> || Synchronously trigger the modem log streaming path (chunked upload to Lambda). Prints OK/FAIL.
|-
|-
| <code>modem <AT command></code> || Send raw AT command to SIM7080G modem.
| <code>postest &lt;url&gt; &lt;size&gt;</code> || 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 <code>_coap_test</code> payloads.
|}
 
=== Storage & Session ===
 
{| class="wikitable"
! Command !! Description
|-
|-
| <code>modemscan</code> || Detect modem UART configuration.
| <code>storage</code> || Show LittleFS usage (used/total bytes), SD card presence, active session filename, and write-buffer depth.
|-
|-
| <code>modemon</code> / <code>modemoff</code> || Power control for the modem.
| <code>export</code> || Export all log files to SD card.
|-
|-
| <code>wifi</code> || Current WiFi status and IP address.
| <code>startsess</code> || Manually start a new storage session (creates a new CSV file).
|-
|-
| <code>scan</code> || Scan for nearby WiFi networks.
| <code>endsess</code> || Manually end the current storage session.
|-
|-
| <code>connect <ssid> <password></code> || Save WiFi credentials and connect.
| <code>loginfo</code> || Print current session filename, file size, remote-sent offset, session-active flag, and free heap.
|-
|-
| <code>ap</code> || Switch to access point (hotspot) mode.
| <code>dellog &lt;filename|current&gt;</code> || Delete a named log file, or the current session if <code>current</code> is given.
|-
|-
| <code>storage</code> || Show storage usage summary (internal + SD card).
| <code>gentest &lt;KB&gt;</code> || Write a synthetic CSV log of the given size (1–1024 KB) for storage stress-testing.
|-
|-
| <code>export</code> || Export all logs to SD card.
| <code>resetoffset</code> || Reset the remote-sent byte offset to 0 (forces re-upload of the current session on the next mail cycle).
|-
|-
| <code>reset</code> || Reboot the device.
| <code>reset</code> || Reboot the device.
|}
=== Email & QC ===
{| class="wikitable"
! Command !! Description
|-
| <code>testemail [4g]</code> || Send a test status email. Without <code>4g</code>, sends via WiFi/Lambda. With <code>4g</code>, forces 4G modem path. Recipient is <code>mail_logs_to</code> (falls back to <code>jd@bcmeter.org</code>).
|-
| <code>qcemail &lt;type&gt; &lt;json&gt;</code> || Send a QC result email via 4G modem. <code>type</code> is the email subject key; <code>json</code> 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.
{| class="wikitable"
! Command !! Description
|-
| <code>PING</code> || Responds <code>PONG\n</code>. Used by QC scripts to verify serial connectivity.
|-
| <code>LAB &lt;ch&gt; &lt;led_duty&gt; &lt;pump_duty&gt; &lt;pump_hz&gt; &lt;n_pairs&gt;</code> || Run a lab ADC capture session: set LED channel/duty and pump duty/frequency, capture N raw ADC pairs, return binary data over serial.
|-
| <code>STREAM &lt;ch&gt; &lt;led_duty&gt; &lt;led_hz&gt; &lt;target_ml&gt; &lt;pump_hz&gt; &lt;duration_s&gt;</code> || Streaming lab mode: continuous ADC pairs with airflow control for the given duration.
|-
| <code>LABFLOW &lt;ch&gt; &lt;led_duty&gt; &lt;led_hz&gt; &lt;target_ml&gt; &lt;pump_hz&gt; &lt;n_pairs&gt;</code> || Lab mode with airflow target: capture N pairs at controlled flow rate.
|-
| <code>LABEND</code> || End the current lab session. Responds <code>OK\n</code>.
|-
| <code>STOP</code> || Acknowledge stop. Used by QC scripts as a generic stop/sync marker.
|-
| <code>SILENCE on</code> || Suppress serial log output during lab capture (reduces USB-CDC overhead).
|-
| <code>SILENCE off</code> || Re-enable serial log output.
|-
| <code>ADCMODE &lt;0–6&gt;</code> || 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.
{| class="wikitable"
! Command !! Description
|-
| <code>MUTE status on</code> || Pause the status LED task (pin to high-Z). Reversible without reset.
|-
| <code>MUTE status off</code> || Resume the status LED task.
|-
| <code>MUTE leds</code> || Detach all three measurement LED PWM channels (requires <code>reset</code> to restore).
|-
| <code>MUTE pump</code> || Detach the pump PWM channel (requires <code>reset</code> to restore).
|-
| <code>MUTE wifi</code> || Disconnect WiFi and turn off the radio (requires <code>reset</code> to restore).
|}
=== General ===
{| class="wikitable"
! Command !! Description
|-
|-
| <code>help</code> || List all available commands.
| <code>help</code> || Print a grouped command summary to the serial console.
|}
|}


=== Usage Example ===
=== Usage Examples ===


<pre>
<pre>
# Connect via screen (macOS/Linux)
# Check device status
screen /dev/tty.usbmodem* 115200
> 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


# Or via minicom
# Read live sensor snapshot
minicom -D /dev/ttyACM0 -b 115200
> 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


# Check sensor readings
# Manually test pump at a fixed duty (lock first to prevent auto-override)
> adc
> pumplock on
ADS1220 detected at SPI
OK pump locked — controlTask yielding
Ch0 (Sen 880): 2.341V
> pump 120
Ch1 (Ref 880): 2.518V
Pump set to 120
> pumpinfo
[Pump] duty=120 flow=0.4210 ...
> pumplock off
OK pump unlocked


# Manually control pump
# Set device timezone
> pump 80
> settz CET-1CEST,M3.5.0/2,M10.5.0/3
Pump duty set to 80/255
OK tz=CET-1CEST,M3.5.0/2,M10.5.0/3


# Check GPS
# Probe via QC tooling
> gps
> bcm:probe
Fix: valid
{"_bcm":1,"schema":"probe/v1","name":"bcmeter-A1B2","mac":"AA:BB:CC:DD:EE:FF","fw":"1.5.230","env":"prod","up":3721}
Lat: 52.4631, Lon: 13.3069
Sats: 7, HDOP: 1.2
Alt: 48.3m, Speed: 0.0 km/h
</pre>
</pre>

Latest revision as of 20:59, 8 June 2026

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}
Retrieved from "https://bcmeter.org/wiki/index.php?title=Serial_commands&oldid=426"