v1.15.5 - Event Payload Refactoring (2025-12-12)¶

What Changed?¶

This release improves code clarity and maintainability by refactoring the event payload construction system. A critical GNSS timing field (gnss_time_us) that was silently dropped from output is now included. The API gains clearer naming semantics with get_event_payload() replacing the confusing build_event_payload(), while maintaining full backward compatibility.

What's New¶

Main Feature: Improved Event Payload API¶

What it does:

Fixes missing GNSS timing data (gnss_time_us) in payload output
Improves API semantics: get_event_payload() is now the recommended function
Separates payload construction logic into a pure, testable function
Enhanced documentation with explicit "ephemeral pointer" guarantees

How to use it:

// New recommended API (v1.14.1+)
const JsonDocument* payload = get_event_payload(&event);

// Old name still works (deprecated)
const JsonDocument* payload = build_event_payload(&event);  // Will be removed in v2.0.0

Key improvements:

GNSS Timing Data Fix: gnss_time_us field is now included in all GNSS-enabled outputs
Clearer API Naming: get_event_payload() vs build_event_payload() - "get" better reflects the ephemeral nature of returned pointer
Testable Architecture: Internal set_event_payload() function separated for unit testing
Better Documentation: Explicit timing guarantees, safe/unsafe usage examples

Installation¶

Quick Start¶

# Get the release
git checkout v1.15.5

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?¶

✅ Added¶

get_event_payload() - Recommended event payload retrieval function (v1.14.1+)
set_event_payload() - Internal pure function for testable payload construction
Enhanced documentation: "EPHEMERAL POINTER GUARANTEE" section explaining static storage semantics
Safe and unsafe usage examples in function documentation

🔧 Changed¶

Event payload includes gnss_time_us field (was previously silently dropped)
Function naming: build_event_payload() → get_event_payload() (more accurate semantics)
Documentation examples updated to use get_event_payload()
Improved clarity on timing requirements for payload usage

🐛 Fixed¶

GNSS Data Loss: gnss_time_us field now included in all GNSS payload outputs
Payload construction logic separated from storage management for clarity

Backward Compatibility¶

Fully Backward Compatible: ✅ Yes

build_event_payload() remains available as a deprecated inline alias
All existing code continues to work without modification
Deprecation warning guides gradual migration to get_event_payload()
No breaking changes to public APIs or data structures

Migration Path:

v1.14.1-v1.15.x: Both names work; prefer get_event_payload() in new code
v2.0.0: build_event_payload() will be removed; switch all code to get_event_payload()

Tests Passed¶

✅ Builds successfully (esp32dev-dev profile)
✅ Memory usage unchanged: RAM 8.8%, Flash 26.6%
✅ GNSS field (gnss_time_us) verified in payload
✅ All documentation examples compile correctly
✅ Backward compatibility with deprecated function name verified
✅ Pre-commit hooks pass (trailing whitespace, file endings, merge conflicts)

Technical Details¶

Files Modified¶

File	Changes
`src/event_queue.cpp`	Added `set_event_payload()` helper; renamed main function to `get_event_payload()`
`include/event_queue.h`	Enhanced documentation; added `get_event_payload()` and deprecated `build_event_payload()` alias
`src/detection_processor.cpp`	Updated call site to use `get_event_payload()`

Memory Impact¶

No change: Static storage, payload buffer, and per-event overhead remain identical
RAM: 8.8% of 320KB (28,764 bytes used)
Flash: 26.6% of 1.3MB (348,469 bytes used)

Performance Impact¶

Zero overhead: Internal helper function inlines to identical machine code
GNSS field addition: <1 microsecond per detection event

Release Details¶

Date: 2025-12-12
Version: v1.15.5
Files Changed: 3 (src/event_queue.cpp, include/event_queue.h, src/detection_processor.cpp)
Commits: 2 (refactoring phases)

Next Steps¶

v1.15.6+: Continued EventQueue architecture improvements
v2.0.0: Remove deprecated build_event_payload() function
Future: Potential circular buffer pattern for future multi-threaded support