Skip to content

v1.19.0 - Field Name Consistency Refactoring (2025-12-18)

What Changed?

This release standardizes field naming conventions across all protocol layers (V1 and V2) to improve code clarity and explicitly document precision levels. Timestamp fields are now consistently suffixed with _us (microseconds), and the ADC field is clearly named. This is a pure refactoring with zero functionality impact—all output remains identical.

What's New

Field Name Standardization

What it does: Unifies naming conventions across all device response messages and sensor data structures. All microsecond-precision timestamps now use the _us suffix, making precision explicit and preventing confusion with millisecond or second-based timestamps.

Changes:

Old Name New Name Context Reason
sensorValue adc All sensor events Clarity: ADC = analog-to-digital converter
sent_at sent_us Command/event responses Explicit: _us = microseconds precision
detected_at detected_us RTC-enabled detection events Explicit: _us = microseconds precision

Code example (JSON output):

// Before (v1.18.1)
{"type":"event","status":"ok","sent_at":1732046789,"hit1":100,"adc":2048,"detected_at":1732046789}

// After (v1.18.2) - same data, clearer naming
{"type":"event","status":"ok","sent_us":1732046789,"hit1":100,"adc":2048,"detected_us":1732046789}

Installation

Quick Start

# Get the release
git checkout v1.19.0

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version (v1.18.1)?

This is a MINOR version bump (1.18.1 → 1.19.0) due to the breaking change in JSON field names for clients parsing protocol responses.

✅ Added

  • None (pure refactoring)

🔧 Changed

  • Struct fields: sent_at → sent_us in all response types
  • Struct fields: detected_at → detected_us in event and RTC modules
  • Struct fields: sensorValue → adc in sensor data structures
  • JSON output: All example documentation updated to reflect new field names
  • Header files:
  • include/stream_data.h - Core sensor data structure
  • include/v2_event_queue.h - Event response types (3 occurrences)
  • include/v2_command_queue.h - Command response types
  • include/v2_device_response.h - Protocol documentation
  • Implementation files:
  • src/v2_device_response.cpp - Serialization and builder functions
  • src/v2_event_queue.cpp - Event response builders
  • src/v2_command_queue.cpp - Command dispatcher
  • src/v2_detection_processor.cpp - RTC timestamp capture
  • src/v1_main.cpp - V1 detection loop
  • src/v1_stream_formatter.cpp - All output format handlers
  • src/v1_text_command_manager.cpp - Documentation examples
  • src/command/*.cpp - Handler documentation (18 files)
  • Documentation:
  • docs/api/v2.md - V2 protocol examples and diagrams
  • docs/api/v1.md - V1 protocol examples

🐛 Fixed

  • Fixed compilation errors when structs had mismatched field names between definitions and implementations

Is It Safe to Upgrade?

Backward Compatible: ⚠️ Breaking Change for JSON Clients

Impact on existing users:

  • Firmware behavior: Identical - no functional changes, same detection and output
  • JSON output format: Field names changed - clients parsing JSON responses must update their field mappings
  • Update all references: sent_at → sent_us, detected_at → detected_us
  • Update ADC field references: sensorValue → adc (if V1 protocol with STREAM_FORMAT=3)
  • Binary protocol (V1): Unaffected - binary command format unchanged
  • Serial baud rate: Unchanged at 115200 baud
  • Device configuration: No changes to thresholds, poll counts, or settings

Recommendation:

  • If using JSON clients that parse V2 protocol responses, update your parser to use new field names before upgrading
  • If using binary protocol only, upgrade without concern
  • If using text commands only, upgrade without concern

Tests Passed

  • ✅ Builds without errors (esp32dev-next: 361,957 / 1,310,720 bytes flash, 102,672 / 327,680 bytes RAM)
  • ✅ All 13 refactoring commits applied cleanly
  • ✅ Pre-commit hooks validation passed (no whitespace, YAML/JSON syntax, merge conflicts)
  • ✅ No functional regression (same detection behavior, same sensor readings)

Release Details

  • Date: 2025-12-18
  • Version: v1.19.0
  • Files Changed: 25+ files across header definitions, implementation, handlers, and documentation
  • Commits: 13 sequential commits + 1 file rename, each with clear scope
  • Type: Pure refactoring (Semantic Versioning: MINOR increment due to JSON breaking change)
  • Binary Size Impact: 0 bytes (no functionality added/removed)

Next Steps

  • v1.20.0 (planned): Unified protocol enhancement - finalizing V2 protocol as default
  • V2 Protocol Stabilization: With field naming now consistent, V2 is ready for production evaluation
  • Client Library Updates: Recommend updating any JSON parsing clients to use new field names
  • Documentation: Field name changes documented in API references and development guides

See Also