V1 Protocol Reference¶

Maintenance Only

V1 is on the v1 branch and receives maintenance fixes only. No new features are added. For active development, use the V2 Protocol on the main branch.

V1 uses separate types for command responses and detection events. The output format is selected at compile time via the STREAM_FORMAT build flag (default: SSV).

Detection Events¶

Detection events are emitted each time a cosmic ray is detected. The format depends on the STREAM_FORMAT build flag.

Output Formats¶

`STREAM_FORMAT`	Format	Description
`0` (default)	SSV	Space-separated values
`1`	TSV	Tab-separated values
`2`	CSV	Comma-separated values
`3`	JSONL	JSON Lines

ENABLE_DEVICE_RESPONSE

When ENABLE_DEVICE_RESPONSE=1, STREAM_FORMAT is ignored. All output uses JSONL via the unified device_response_t envelope (same as V2). The V1 branch supports both paths; ENABLE_DEVICE_RESPONSE=0 is the V1 default.

SSV Format (default)¶

85 72 91 2048 25.35 101325.0 45.67

Fields in order: hit1 hit2 hit3 adc [tmp_c atm_pa hmd_pct] [uptime_ms timedelta_us] [detected_us]

JSONL Format (STREAM_FORMAT=3)¶

{"hit1":85,"hit2":72,"hit3":91,"adc":2048,"tmp_c":25.35,"atm_pa":101325.0,"hmd_pct":45.67}

Event Fields¶

Field	Type	Always Present	Description
`hit1`	uint16	Yes	Detection count, channel 1 (GPIO12)
`hit2`	uint16	Yes	Detection count, channel 2 (GPIO19)
`hit3`	uint16	Yes	Detection count, channel 3 (GPIO27)
`adc`	int	Yes	ADC value (0–4095); 0 if ch1 has no detection
`hit_type`	uint8	`ENABLE_HITTYPE=1`	Channel bitmask (bit0=CH1, bit1=CH2, bit2=CH3)
`adc_raw`	uint16	`ENABLE_ADCMV=1`	Raw ADC value (0–4095)
`adc_mv`	uint16	`ENABLE_ADCMV=1`	ADC in millivolts (0–3300)
`tmp_c`	float	`ENABLE_BME280=1`	Temperature (°C)
`atm_pa`	float	`ENABLE_BME280=1`	Atmospheric pressure (Pa)
`hmd_pct`	float	`ENABLE_BME280=1`	Relative humidity (%)
`uptime_ms`	uint32	`ENABLE_TIMESTAMP=1`	Device uptime at detection (ms)
`timedelta_us`	uint64	`ENABLE_TIMESTAMP=1`	Time since previous event (µs)
`detected_us`	uint64	`ENABLE_RTC=1`	Detection moment unix timestamp (µs)
`gnss_latitude`	double	`ENABLE_GNSS=1`	Latitude (decimal degrees)
`gnss_longitude`	double	`ENABLE_GNSS=1`	Longitude (decimal degrees)
`gnss_altitude`	float	`ENABLE_GNSS=1`	Altitude above sea level (m)
`gnss_satellites`	uint8	`ENABLE_GNSS=1`	Number of satellites in use
`gnss_fix_quality`	uint8	`ENABLE_GNSS=1`	Fix quality (0–8, NMEA GGA spec)
`gnss_hdop`	float	`ENABLE_GNSS=1`	Horizontal dilution of precision
`gnss_fix_valid`	bool	`ENABLE_GNSS=1`	True if fix is valid
`gnss_time_us`	uint64	`ENABLE_GNSS=1`	GNSS unix timestamp (µs)

Command Responses¶

Command responses always use JSONL format, regardless of STREAM_FORMAT.

Success Response¶

{"type":"response","status":"ok"}

With data field:

{"type":"response","status":"ok","version":"1.21.3"}

Error Response¶

{"type":"response","status":"error","error_code":1}

Note

V1 responses do not include a sent_us timestamp field. That field is V2-only.

Error Codes¶

Code	Name	Description
1	`INVALID_ARG`	Invalid argument count or format
2	`OUT_OF_RANGE`	Argument value exceeds valid range
3	`INVALID_STATE`	Operation not allowed in current state
4	`INTERNAL`	Internal device error
5	`NOT_SUPPORTED`	Feature not compiled in

Commands¶

V1 uses text commands over serial (115200 baud), line-terminated with \n or \r\n.

Command Reference¶

Command	Alias	Description
`GET_STATUS`	`S`	Display system configuration
`GET_VERSION`	`V`	Firmware version
`GET_UPTIME`	`U`	Milliseconds since boot
`GET_MAC_ADDRESS`	—	Device MAC address
`SET_POLL_COUNT <count>`	`C`	Set detection poll count (1–65535)
`SET_THRESHOLD <ch> <val>`	`T`	Set DAC threshold, ch 1–3, val 0–4095
`GET_THRESHOLD <ch>`	`G`	Read DAC threshold for channel
`SET_DEADTIME <ms>`	`D`	Set detector deadtime (0–60000 ms)
`SET_STREAM <0\\|1>`	—	Enable (1) or disable (0) detection output
`GET_STREAM`	—	Query stream output state
`SET_RTC_TIME <unixtime>`	`SET_TIME`	Set RTC (unix seconds)
`GET_RTC_TIME`	`GET_TIME`	Read RTC (unix seconds)
`GET_GNSS_TIME`	—	GNSS unix timestamp
`GET_GNSS_STATUS`	—	GNSS fix quality snapshot
`GET_GNSS_POSITION`	—	GNSS position (lat/lon/alt)
`TEST_LED <ch\\|ALL>`	`L`	LED hardware test
`GET_HELP`	`H`	List all commands
`RESET`	`R`	Reboot device

WiFi commands (SET_WIFI_SSID, GET_WIFI_STATUS, SET_WIFI_ENABLE) are available only when ENABLE_WIFI=1.

Build Flags¶

Feature Flags¶

Flag	v1 Default	Purpose
`STREAM_FORMAT`	`0`	Output format: SSV(0)/TSV(1)/CSV(2)/JSONL(3)
`ENABLE_BME280`	`1`	Environmental sensor data
`ENABLE_RTC`	`1`	Absolute unix timestamps (`detected_us`)
`ENABLE_TIMESTAMP`	`1`	Uptime and inter-event timing
`ENABLE_HITTYPE`	`1`	Channel activity bitmask
`ENABLE_ADCMV`	`1`	ADC millivolt conversion
`ENABLE_GPIO_ABSTRACTION`	`1`	HAL API instead of direct register access
`ENABLE_QUEUE`	`1`	FreeRTOS command queue
`ENABLE_GNSS`	`1`	GNSS positioning
`ENABLE_DEVICE_RESPONSE`	`0`	Unified JSONL protocol (V2-style output)
`ENABLE_WIFI`	`0`	WiFi AP interface
`ENABLE_TEXT_COMMAND`	`1`	Text command protocol

ADC jumper

ADC_JUMPER_CHANNEL (default: 1) must match the physical jumper position on the board.

Architecture Overview¶

┌─────────────────────────────────────────┐
│           HOST (PC / DAQ system)        │
│  • Sends text commands over USB serial  │
│  • Receives SSV/TSV/CSV/JSONL events    │
└─────────────────────────────────────────┘
            ↕ UART 115200 baud
┌─────────────────────────────────────────┐
│               ESP32 (OSECHI)            │
│                                         │
│  text_receive() ──→ text_execute()      │
│       ↑                  ↓             │
│  Serial Input       send_response()     │
│                                         │
│  cosmic_detector_read()                 │
│       ↓                                │
│  (if detected) → read sensors          │
│       ↓                                │
│  send_event() → SSV/TSV/CSV/JSONL      │
│       ↓                                │
│  Serial Output                          │
└─────────────────────────────────────────┘

Key Components¶

Component	Role
`cosmic_detector`	Polls GPIO12/19/27; returns hit counts per cycle
`stream_formatter`	Formats detection events in selected output format
`runtime_config`	Struct-based device configuration (poll count, thresholds, deadtime)
`text_command`	Receives, queues (10-item FIFO), and dispatches text commands
`response_t`	Type-safe command response (JSONL output, no `sent_us`)