Skip to content

v1.12.0 - Unified Device Response Protocol (Planned)

What Changed?

Unified Device Response implementation is currently in progress. Phase 1 (foundation) has been completed with zero impact on existing builds. This release will eventually consolidate all command responses and detection events into a single device_response_t type with schema validation.

Note: Full implementation is not yet complete - currently only Phase 1 foundation is finished.

What's New

Main Feature: Unified Device Response Protocol (Phase 1 Foundation Only)

What it does (when Phase 2-4 complete): Replaces separate response_t and event_t types with unified device_response_t that conforms to docs/schemas/device-response.json. All output messages will include type, status, timestamp, error info, and payload fields.

Current Status (Phase 1 - Complete):

  • ✅ Type definitions created
  • ✅ Builder function signatures defined
  • ✅ Builder function implementations added
  • 🚧 NOT YET: Integration with command handlers
  • 🚧 NOT YET: Serialization implementation
  • 🚧 NOT YET: Schema validation integration

Code example (Phase 1 - available now):

// Builder functions now available
device_response_t response = device_response_ok(TYPE_RESPONSE);
device_response_t error = device_response_error(
  TYPE_RESPONSE,
  ERROR_OUT_OF_RANGE,
  "Value exceeds maximum"
);
uint32_t timestamp = device_get_timestamp();

Installation

Quick Start

# Get the release (when available)
git checkout v1.12.0

# Build (Phase 1 enabled in dev profile)
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added (Phase 1 Only)

  • include/device_response.h: Type definitions and builder function signatures
  • response_type_t enum (TYPE_RESPONSE, TYPE_EVENT)
  • response_status_t enum (STATUS_OK, STATUS_ERROR)
  • response_code_t enum (RESPONSE_OK, ERROR_INVALID_ARG through ERROR_UNKNOWN)
  • device_response_t structure definition
  • Builder function declarations
  • src/device_response.cpp: Builder function implementations
  • device_response_ok(): Create success messages
  • device_response_error(): Create error messages
  • device_get_timestamp(): Get current timestamp
  • ENABLE_DEVICE_RESPONSE configuration flag in config.h

🔧 Changed

  • platformio.ini: Added ENABLE_DEVICE_RESPONSE documentation
  • esp32dev-dev profile: Includes -DENABLE_DEVICE_RESPONSE=1 for testing

🚧 NOT YET (Phase 2-4 - Planned)

  • Command/event serialization (still using legacy types)
  • Serial output format (still using legacy types)
  • Schema validation integration
  • Default flag behavior (ENABLE_DEVICE_RESPONSE still defaults to 0)

Is It Safe to Upgrade?

Backward Compatible: Yes (Phase 1 only)

  • ✅ ENABLE_DEVICE_RESPONSE defaults to 0 (disabled)
  • ✅ No impact on current builds
  • ✅ Zero bytes added to production when disabled
  • ✅ New types and functions only compiled when enabled

Breaking Changes: None (in Phase 1)

Note: Full v1.12.0 release (Phases 2-4) will require client updates to use new unified format.

Tests Passed

  • ✅ Builds without errors (development and production)
  • ✅ Development build: 348 KB Flash, 28.8 KB RAM
  • ✅ Production build: 307 KB Flash, 22.8 KB RAM
  • ✅ Zero overhead when disabled

Release Details

  • Status: 🚧 Phase 1 Complete, Phases 2-4 In Progress
  • Version: v1.12.0 (Roadmap)
  • Phase 1 Completion Date: Dec 8, 2025
  • Projected Phase 4 (Release): Jan 2026

Phase Timeline: - Phase 1 (Foundation): ✅ Complete - Phase 2 (Integration): 🚧 Planned - Phase 3 (Testing): 🚧 Planned - Phase 4 (Release): 🚧 Planned

Next Steps

Immediate (Phase 2): - Integrate device_response_t with text command handlers - Integrate device_response_t with binary command response formatting - Update event serialization to use device_response_t

Later (Phases 3-4): - Complete schema validation integration - Enable ENABLE_DEVICE_RESPONSE=1 by default - Remove legacy response_t/event_t code paths - Complete migration documentation

Future (v1.13.0+): - Full RTC integration for Unix timestamps - Advanced payload field handling - Performance optimization

Documentation