Skip to content

v2.1.0 - Unified JSON Output Format (2025-01-01)

What Changed?

This release deprecates the STREAM_FORMAT build flag and unifies all sensor data output to JSON Lines (JSONL) format exclusively. All firmware builds (v0, v1, v2) now output the same JSON format, eliminating the need for format selection at compile time. Client code should be updated to parse JSON instead of space/tab/comma-separated values.

What's New

Breaking Change: Stream Output Format Unified to JSONL

What it does: All sensor detection events are now output exclusively in JSON Lines format, regardless of build profile. Previous format options (SSV, TSV, CSV) are no longer available. This ensures consistency across all firmware variants and simplifies client implementation.

How to use it: Parse the serial output as newline-delimited JSON. Each detection event is a single-line JSON object.

Example output:

{"type":"event","status":"ok","hit1":95,"hit2":87,"hit3":91,"adc":2048,"tmp_c":25.35,"atm_pa":101325,"hmd_pct":45.67}
{"type":"event","status":"ok","hit1":100,"hit2":92,"hit3":88,"adc":2100,"tmp_c":25.40,"atm_pa":101324,"hmd_pct":45.70}

Client migration:

  • Old method: Split on space/tab/comma, parse by position
  • New method: Parse each line as JSON, access fields by name
  • Recommended tools: jq (shell), Python json module, ArduinoJson (C++)

Installation

Quick Start

# Checkout the release
git checkout v2.1.0

# Build (any profile)
task v2:build    # v2 (recommended)
task build       # v1 (alias for dev:build)
task v0:build    # v0 (legacy)

# Upload
task upload

# Monitor serial output (JSON format)
task monitor

What's Different from v2.0.0?

✅ Added

  • [None - deprecation only]

🔧 Changed

  • STREAM_FORMAT flag deprecated: No longer used in any build profile
  • Unified output format: All profiles output JSON Lines exclusively
  • Removed format functions: send_ssv(), send_tsv(), send_csv() functions deleted
  • Simplified stream formatter: send_event() always calls send_jsonl()

🐛 Fixed

  • [None]

Is It Safe to Upgrade?

Backward Compatible: No

  • Breaking change for v1.x users: Client code must be updated to parse JSON
  • Data format change: Stream output is now JSON instead of space-separated values
  • Build flag removal: STREAM_FORMAT build flags in platformio.ini have no effect
  • Firmware builds: All profiles (v0, v1, v2) now output identical JSON format

Mitigation:

  • Update client parsing code to use JSON parser before upgrading
  • No firmware changes required - all profiles automatically output JSON
  • Field names remain unchanged for compatibility

Tests Passed

  • ✅ Builds without errors (all profiles: v0, v1, v2)
  • ✅ Pre-commit checks pass
  • ✅ JSON output structure validated
  • ✅ All optional fields (BME280, timestamp, RTC, GNSS, HITTYPE, ADCMV) serialize correctly

Release Details

  • Date: 2025-01-01
  • Version: v2.1.0
  • Files Changed: 4
  • include/config.h - STREAM_FORMAT deprecated
  • src/v1_stream_formatter.cpp - JSONL only implementation
  • include/v1_stream_formatter.h - Removed deprecated functions
  • platformio.ini - Removed STREAM_FORMAT build flags
  • Increment Type: MINOR (new feature: format unification)

Next Steps

Potential future improvements:

  • Device response protocol (command responses in same JSON format)
  • Timestamp precision improvements
  • Additional optional fields based on deployment needs