Skip to content

STREAM_FORMAT

⚠️ DEPRECATED in v2.1.0 - This flag is no longer used. All firmware builds output JSON Lines (JSONL) format exclusively. See v2.1.0 Release Notes for migration details.

Compile-time flag to select sensor data output format (historical reference).

Controls the format in which sensor detection events are streamed to serial. Only the selected format is compiled; unused formats are completely excluded from the binary for optimal code size.

Options (Historical - v1.x)

⚠️ All options below are deprecated as of v2.1.0. Only JSONL format is now supported.

Previous v1.x options (no longer available):

  • STREAM_FORMAT=0: SSV (Space-Separated Values) - default, backward compatible - DEPRECATED
  • Format: hit1 hit2 hit3 adc [adc_raw adc_mv] tmp_c atm_pa hmd_pct [uptime_ms timedelta_us] [detected_us]
  • STREAM_FORMAT=1: TSV (Tab-Separated Values) - canonical for data pipelines - DEPRECATED
  • Format: hit1\thit2\thit3\tadc\t[adc_raw\tadc_mv]\ttmp_c\tatm_pa\thmd_pct...
  • STREAM_FORMAT=2: CSV (Comma-Separated Values) - with header on first boot - DEPRECATED
  • Header: hit1,hit2,hit3,adc,[adc_raw,adc_mv],tmp_c,atm_pa,hmd_pct...
  • STREAM_FORMAT=3: JSONL (JSON Lines) - structured JSON per event - NOW THE ONLY FORMAT
  • Format (v2.1.0+): {"type":"event","status":"ok","hit1":val,"hit2":val,"hit3":val,"adc":val,...}

In v1.x, all formats output identical numeric values; they differed only in delimiters and structure.

v2.1.0+: Only JSON Lines format is available. All sensor data output uses this format exclusively.

ADC Fields (v1.9.5+)

With ENABLE_ADCMV=1, additional ADC millivolt fields are included:

  • adc: Original ADC reading (0-4095) - always present
  • adc_raw: Raw ADC value (0-4095) - only when ENABLE_ADCMV=1
  • adc_mv: ADC value converted to millivolts (0-3300 on 3.3V ESP32) - only when ENABLE_ADCMV=1

Note: When ENABLE_ADCMV=0 (default), only adc field is output. The adc_raw and adc_mv fields provide hardware calibration-based voltage conversion using ESP32's built-in calibration table.

Added

v1.7.0

Recommendation (Historical)

DEPRECATED: This recommendation is historical. As of v2.1.0, only JSONL is supported.

Previously (v1.x): Use STREAM_FORMAT=3 (JSONL) for flexibility and maintainability. JSONL format includes implicit header information (column names as JSON keys), enabling seamless data format extensions without breaking downstream consumers. Self-documenting structure eliminates parsing ambiguity and supports future field additions.

Current Status (v2.1.0+): All firmware builds output JSON Lines exclusively. No format selection is available.

How to Read JSONL

Each line is a complete, independent JSON object. Parse line-by-line without header parsing.

with json package

import json
with open('data.jsonl') as f:
    for line in f:
        event = json.loads(line)
        print(f"Signal1: {event['signal1']}, Temp: {event['temp']}")

with pandas package

import pandas as pd
df = pd.read_json('data.jsonl', lines=True)

with polars package

import polars as pl
df = pl.read_ndjson('data.json')

Field names are self-documenting; no header interpretation needed.