Skip to content

v1.7.0 - Unified Sensor Data Structure & Multiple Output Formats (2025-11-21)

What Changed?

This release introduces a unified sensor_data_t structure that consolidates all sensor readings from detection events, replacing scattered Serial.print() calls with a clean, format-agnostic output system. Four output formats (SSV, TSV, CSV, JSONL) are now supported and selected at build time with zero runtime overhead. The feature maintains 100% backward compatibility with production deployments.

What's New

Main Feature: Unified Sensor Data Structure with Multiple Output Formats

What it does:

Introduces a centralized sensor_data_t structure that collects all sensor readings (signal1-3, ADC, temperature, pressure, humidity, timestamps) in one place. Four output formats are supported:

  • SSV (Space-Separated Values) - Default, backward compatible
  • TSV (Tab-Separated Values) - Canonical for spreadsheets
  • CSV (Comma-Separated Values) - With header per boot
  • JSONL (JSON Lines) - Machine-readable structured data

How to use it: The output format is selected at compile time via platformio.ini build flags. No code changes needed for end users—just rebuild with the desired format.

# Default (SSV - backward compatible)
task build && task upload

# Select TSV format
PLATFORMIO_BUILD_FLAGS="-DOUTPUT_FORMAT=1" pio run -e esp32dev-release

# Select CSV format
PLATFORMIO_BUILD_FLAGS="-DOUTPUT_FORMAT=2" pio run -e esp32dev-release

# Select JSONL format
PLATFORMIO_BUILD_FLAGS="-DOUTPUT_FORMAT=3" pio run -e esp32dev-release

Code example:

// In main.cpp event handler - much simpler than before
sensor_data_t data = {
  .signal1 = (uint16_t)detection.signal1,
  .signal2 = (uint16_t)detection.signal2,
  .signal3 = (uint16_t)detection.signal3,
  .sensorValue = adc_reading,
  .temperature = bme_temp,
  .pressure = bme_pressure,
  .humidity = bme_humidity,
};
send_sensor_data(&data);  // Automatically selects format based on OUTPUT_FORMAT flag

Output examples:

# SSV (default)
100 85 92 2048 25.35 1013.25 45.67

# TSV
100    85     92     2048   25.35  1013.25 45.67

# CSV (with header on first detection)
signal1,signal2,signal3,adc,temp,pressure,humidity
100,85,92,2048,25.35,1013.25,45.67

# JSONL
{"signal1":100,"signal2":85,"signal3":92,"adc":2048,"temp":25.35,"pressure":1013.25,"humidity":45.67}

Installation

Quick Start

# Get the release
git checkout v1.7.0

# Build (default SSV format)
task build

# Upload to device
task upload

# Monitor output
task monitor

What's Different from the Last Version?

✅ Added

  • Unified sensor_data_t structure for all sensor data collection
  • Three new output formats: TSV, CSV, JSONL (in addition to existing SSV)
  • Build-time format selection via OUTPUT_FORMAT flag
  • Comprehensive progress log and specification documentation
  • Build configuration guide in CLAUDE.md

🔧 Changed

  • main.cpp event handler: Replaced 22+ Serial.print() calls with single send_sensor_data() call
  • Added conditional compilation guards to reduce binary size (unused formats excluded)
  • Introduced OUTPUT_FORMAT and field control flags to platformio.ini

🐛 Fixed

  • Code maintainability: Sensor output logic now centralized in sensor_output.cpp
  • Type safety: Proper casting of signal fields (int → uint16_t)

Is It Safe to Upgrade?

Backward Compatible: ✅ Yes, 100%

  • Default configuration (OUTPUT_FORMAT=0) produces identical SSV output to v1.6.11
  • No behavior changes for existing deployments
  • All sensor values and timestamps work exactly as before
  • No changes to detection logic or hardware interfaces

Tests Passed

  • ✅ Builds without errors (all 3 profiles: release, debug, dev)
  • ✅ All 12 functional requirements met
  • ✅ All 3 user stories complete
  • ✅ Memory efficient: Flash 22.7%, RAM 6.9% (no overhead)
  • ✅ Backward compatibility: 100% identical output with defaults
  • ✅ Code quality: Full docstrings and inline comments

Release Details

  • Date: 2025-11-21
  • Version: v1.7.0
  • Files Changed: 12
  • Lines Added: 1,408
  • Lines Deleted: 102
  • Commits:
  • 692fd73 - Build configuration documentation
  • 2e19ccf - Format markdown documentation
  • 798323e - Add progress log entry
  • 3f71585 - Mark task phases complete

Next Steps

v1.8.0 (Planning):

  1. Text Protocol Parsing Optimization - Consolidate argument parsers and error handling (~180-190 lines reduction)
  2. Serial Protocol Specification - Create formal protocol documentation for interoperability

Future Enhancements:

  • LTSV format support
  • MessagePack binary format
  • RTC absolute time support (v1.8.0+)
  • Multi-board support (v2.0.0)

See REFACTORING_ROADMAP.md for complete roadmap.