Commands Reference¶

The v2 firmware provides a comprehensive text command protocol for device control and monitoring. All commands use a RESTful-style naming convention and return responses in unified JSON format.

Command Protocol Overview¶

The v2 firmware uses a text-based command protocol with the following characteristics:

Text Format: Human-readable commands terminated with \n or \r\n
Response Format: JSONL (JSON Lines) with unified device response envelope
Naming Convention: RESTful-style (GET_*, SET_*, TEST_*)
Aliases: Single-character shortcuts for common commands (S, U, H, etc.)
Command Queue: 10-item FIFO for asynchronous processing
Timeout: 500ms per command

About Command Aliases

Aliases (S, U, H, etc.) are provided for convenience when using the serial monitor interactively. If you are using kurikintons as an API for your own DAQ system, always use the full command names (GET_STATUS, GET_UPTIME, GET_HELP, etc.). Aliases may change, be consolidated, or be deprecated in future versions and should not be relied upon for programmatic access.

Response Format¶

All commands return responses using the unified device response protocol.

Success Response¶

{
  "type": "response",
  "status": "ok",
  "sent_us": 1706745012345678,
  "field1": "value1",
  "field2": "value2"
}

Envelope Fields:

type: Always "response" for command responses
status: "ok" for successful execution
sent_us: Unix timestamp in microseconds when response was sent

Error Response¶

{
  "type": "response",
  "status": "error",
  "sent_us": 1706745012345678,
  "error_code": 2,
  "error_message": "Threshold out of range (0-1023)"
}

Error Codes:

Code	Name	Description
0	`SUCCESS`	Command executed successfully
1	`INVALID_ARG`	Invalid command or argument format
2	`OUT_OF_RANGE`	Argument value exceeds valid range
3	`HARDWARE_ERROR`	SPI/I2C/sensor communication failure
4	`NOT_SUPPORTED`	Feature not enabled in firmware
5	`UNKNOWN`	General error

Command Categories¶

System Information¶

Get device version, status, and environmental data.

Command	Aliases	Arguments	Description	Response Fields
`GET_VERSION`	`V`	-	Firmware version string	`version`
`GET_BUILD_TYPE`	-	-	Build environment name	`build_type`
`GET_STATUS`	`S`	-	Complete system configuration and status	`version`, `build_type`, `mac_address`, `poll_count`, `deadtime_ms`, `stream_enabled`, `uptime_ms`, `thresholds`
`GET_MAC_ADDRESS`	-	-	Device MAC address (6 bytes hex)	`mac_address`
`GET_VREF`	-	-	ESP32 internal reference voltage	`vref_mv`
`GET_BME280`	-	-	All environmental sensor data	`tmp_c`, `atm_pa`, `hmd_pct`
`GET_BME280_TMP`	-	-	Temperature in Celsius	`tmp_c`
`GET_BME280_ATM`	-	-	Atmospheric pressure in Pascals	`atm_pa`
`GET_BME280_HMD`	-	-	Humidity percentage	`hmd_pct`

Detection Configuration¶

Configure cosmic ray detection parameters (poll count, thresholds, deadtime).

Command	Aliases	Arguments	Description	Valid Range	Response Fields
`SET_POLL_COUNT`	`C`	`<count>`	Set detection poll count per cycle	1-65535	`poll_count`
`GET_POLL_COUNT`	-	-	Get current poll count	-	`poll_count`
`SET_THRESHOLD`	`T`	`<ch> <val>`	Set DAC threshold (decoded value)	ch: 1-3, val: 0-1023	`channel`, `threshold`
`GET_THRESHOLD`	`G`	`<ch>`	Get DAC threshold (decoded value)	ch: 1-3	`channel`, `threshold`
`SET_DAC`	-	`<ch> <byte1> <byte2>`	Set DAC threshold (raw SPI bytes)	ch: 1-3, bytes: 0x00-0xFF	`channel`, `byte1`, `byte2`
`GET_DAC`	-	`<ch>`	Get DAC threshold via raw decode	ch: 1-3	`channel`, `threshold`
`SET_DEADTIME`	`D`	`<ms>`	Set detector non-responsive period	0-60000	`deadtime_ms`
`GET_DEADTIME`	-	-	Get current deadtime setting	-	`deadtime_ms`

LED & Testing¶

Control and test LED hardware.

Command	Aliases	Arguments	Description	Response Fields
`TEST_LED`	`L`	`<ch\|ALL> <ON\|OFF>`	Manually control LED (ch: 1, 2, 3, or ALL)	`channel`, `state`

Diagnostics & Help¶

Get help and system diagnostics.

Command	Aliases	Arguments	Description	Response Fields
`GET_UPTIME`	`U`	-	System uptime since last boot (milliseconds)	`uptime_ms`
`GET_TIME`	-	-	RTC time, GNSS time, uptime, and time differences	`uptime_ms`, `rtc_time`, `gnss_time`, `time_diff`
`GET_HELP`	`H`	-	Command reference (text summary)	`help`
`GET_USAGE`	-	-	List all available commands	`commands` (array)

Stream Control¶

Enable or disable cosmic ray detection output.

Command	Aliases	Arguments	Description	Valid Range	Response Fields
`SET_STREAM`	-	`<0\|1>`	Enable/disable detection event output	0 or 1	`stream_enabled`
`GET_STREAM`	-	-	Query detection stream status	-	`stream_enabled`

Configuration¶

Global configuration and reset operations.

Command	Aliases	Arguments	Description	Response Fields
`RESET`	`R`	-	Factory reset all settings to defaults	`message`

RTC (Real-Time Clock)¶

Manage device time synchronization. Always enabled in v2 firmware.

Command	Aliases	Arguments	Description	Response Fields
`SET_RTC_TIME`	`SET_TIME`	`<unix_timestamp>`	Set device time (seconds since Unix epoch)	`rtc_time`
`GET_RTC_TIME`	-	-	Get device time (seconds since Unix epoch)	`rtc_time`
`GET_RTC_TIME_MS`	-	-	Get device time (milliseconds)	`rtc_time_ms`
`GET_RTC_TIME_US`	-	-	Get device time (microseconds)	`rtc_time_us`

RTC Always Enabled in v2

The Real-Time Clock (RTC) is built into v2 firmware and always available. RTC provides absolute timestamp synchronization for multi-detector networks and is the basis for the detected_us field in cosmic ray detection events.

GNSS (GPS/GNSS Module)¶

Access GPS/GNSS data for precise positioning and time synchronization. Requires ENABLE_GNSS=1 build flag.

Command	Aliases	Arguments	Description	Response Fields
`GET_GNSS`	-	-	All GNSS data (position, time, satellites, quality)	`latitude`, `longitude`, `altitude`, `gnss_time`, `satellites`, `quality`, `valid`, `hdop`, `state`
`GET_GNSS_LATITUDE`	-	-	Geographic latitude in degrees (-90 to +90)	`latitude`
`GET_GNSS_LONGITUDE`	-	-	Geographic longitude in degrees (-180 to +180)	`longitude`
`GET_GNSS_ALTITUDE`	-	-	Altitude above mean sea level (meters)	`altitude`
`GET_GNSS_POSITION`	-	-	All position fields (latitude, longitude, altitude)	`latitude`, `longitude`, `altitude`
`GET_GNSS_TIME`	-	-	GNSS-synchronized time (unix seconds)	`gnss_time`
`GET_GNSS_TIME_MS`	-	-	GNSS time in milliseconds	`gnss_time_ms`
`GET_GNSS_TIME_US`	-	-	GNSS time in microseconds	`gnss_time_us`
`GET_GNSS_CS`	-	-	Centisecond value (fractional seconds)	`centisecond`
`GET_GNSS_SATELLITES`	-	-	Number of satellites in view	`satellites`
`GET_GNSS_QUALITY`	-	-	Fix quality indicator (0=invalid, 1=GPS, 2=DGPS)	`quality`
`GET_GNSS_VALID`	-	-	Fix validity status (boolean)	`valid`
`GET_GNSS_HDOP`	-	-	Horizontal Dilution of Precision	`hdop`
`GET_GNSS_STATE`	-	-	GNSS module state machine value	`state`

GNSS State Values:

0: INITIALIZING (warm-up phase, 0-2 seconds)
1: SEARCHING (acquiring satellite signals)
2: FIXING (refining position accuracy)
3: FIXED (valid 3D fix with ≥4 satellites, ±5m accuracy)
4: ERROR (timeout or checksum failure)

GNSS requires RTC

GNSS functionality depends on the Real-Time Clock for internal time management. RTC is always enabled in v2, but GNSS requires explicit ENABLE_GNSS=1 build flag.

WiFi (AP Mode Network)¶

Configure WiFi connectivity for remote monitoring. Requires ENABLE_WIFI=1 build flag.

Command	Aliases	Arguments	Description	Response Fields
`SET_WIFI_SSID`	-	`<ssid> <password>`	Connect to WiFi network	`status`
`SET_WIFI_ENABLE`	-	`<0\|1>`	Enable/disable WiFi radio	`enabled`
`GET_WIFI`	`W`	-	WiFi connection status and IP address	`state`, `ip`

WiFi AP Mode

By default, OSECHI creates an Access Point (AP) with SSID "OSECHI-DETECTOR" and IP 192.168.4.1. This allows connecting directly to the device without an external network.

Command Aliases¶

Common commands have single-character or alternative aliases for convenience:

Alias	Full Command	Category
`V`	`GET_VERSION`	System Info
`S`	`GET_STATUS`	System Info
`C`	`SET_POLL_COUNT`	Detection
`T`	`SET_THRESHOLD`	Detection
`G`	`GET_THRESHOLD`	Detection
`D`	`SET_DEADTIME`	Detection
`L`	`TEST_LED`	Testing
`U`	`GET_UPTIME`	Diagnostics
`H`	`GET_HELP`	Help
`R`	`RESET`	Configuration
`SET_TIME`	`SET_RTC_TIME`	RTC
`W`	`GET_WIFI`	WiFi

Usage Examples¶

Commands are sent by typing them into the serial monitor:

uv run platformio device monitor --baud 115200

Type a command and press Enter. The device responds with a JSON line.

Basic Commands¶

Get system status:

GET_STATUS
S

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"version":"2.3.1","build_type":"esp32dev-v2","mac_address":"3c:e9:0e:xxx","poll_count":100,"deadtime_ms":0,"stream_enabled":true,"uptime_ms":45000}

Get device uptime:

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"uptime_ms":45000}

Display all commands:

Detection Configuration¶

Set poll count to 200:

SET_POLL_COUNT 200

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"poll_count":200}

Set threshold for channel 1 to 512:

SET_THRESHOLD 1 512

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"channel":1,"threshold":512}

Set detector deadtime to 10ms:

SET_DEADTIME 10

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"deadtime_ms":10}

Time Synchronization¶

Synchronize device time (set to Unix timestamp 1706745012):

SET_RTC_TIME 1706745012

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"rtc_time":1706745012}

Get current device time:

GET_RTC_TIME

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"rtc_time":1706745012}

GNSS Usage¶

Get all GNSS data (requires ENABLE_GNSS=1):

GET_GNSS

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"latitude":35.6762,"longitude":139.6503,"altitude":10.5,"gnss_time":1706745012,"satellites":12,"quality":1,"valid":true,"hdop":1.2,"state":3}

Get GPS position only:

GET_GNSS_POSITION

Response:

{"type":"response","status":"ok","sent_us":1706745012345678,"latitude":35.6762,"longitude":139.6503,"altitude":10.5}

Error Handling¶

Example: Invalid argument (threshold out of range):

SET_THRESHOLD 1 2000

Response:

{"type":"response","status":"error","sent_us":1706745012345678,"error_code":2,"error_message":"Threshold out of range (0-1023)"}

Implementation Details¶

Command Reception:

Baud rate: 115200
Input buffer: 256 bytes maximum
Timeout: 500ms per command
Terminators: \n or \r\n

Command Processing:

10-item FIFO queue for asynchronous processing
Table-driven dispatch in src/v2_command_manager.cpp
Individual handlers in src/command/*.cpp (20 files)

Architecture:

Serial Input
    ↓
text_receive() [500ms timeout]
    ↓
v2_command_manager [dispatch table]
    ↓
command/handler.cpp [specific handler]
    ↓
v2_device_response [JSON formatting]
    ↓
Serial Output (JSONL)

Conditional Commands:

GNSS commands: Enabled with PLATFORMIO_BUILD_FLAGS="-DENABLE_GNSS=1"
WiFi commands: Enabled with PLATFORMIO_BUILD_FLAGS="-DENABLE_WIFI=1"
RTC commands: Always enabled in v2 (built-in to ESP32)

V2 API Reference - Unified device response protocol architecture
Build Guide - Build flags and customization

Commands Reference¶

Command Protocol Overview¶

Response Format¶

Success Response¶

Error Response¶

Command Categories¶

System Information¶

Detection Configuration¶

LED & Testing¶

Diagnostics & Help¶

Stream Control¶

Configuration¶

RTC (Real-Time Clock)¶

GNSS (GPS/GNSS Module)¶

WiFi (AP Mode Network)¶

Command Aliases¶

Usage Examples¶

Basic Commands¶

Detection Configuration¶

Time Synchronization¶

GNSS Usage¶

Error Handling¶

Implementation Details¶

Related Documentation¶