Skip to content

v1.13.8 - Phase 0: Device Response Type Consolidation (2025-12-10)

What Changed?

This release establishes the architectural foundation for the unified device response protocol by consolidating response types and creating symmetric Layer 1 validation types for both command and event processing paths. The Phase 0 implementation adds the missing event_response_t type, defines builder functions for type-safe response construction, and marks legacy patterns for deprecation in v1.15.0. All changes are backward compatible with zero runtime overhead.

What's New

Main Feature: Symmetric Layer 1 Response Types

What it does:

Introduces event_response_t as a Layer 1 validation type that mirrors the command response path. Both command and event processing now follow an identical three-layer pattern:

  1. Layer 1 (Domain): Validation and error handling (command_response_t, event_response_t)
  2. Layer 2 (Transport): Unified envelope (device_response_t)
  3. Layer 3 (Serialization): JSON output (via ArduinoJson)

How to use it:

The new types are automatically used by the device response protocol. No user-facing changes required. This is an internal architectural improvement.

For developers building new handlers or response handlers in Phase 1+:

// Layer 1: Return typed response from handler
event_response_t event = event_response_ok(sensor_data);
if (validation_failed) {
  event = event_response_error(DEVICE_CODE_NOT_READY, "Sensor not initialized");
}

// Layer 2: Convert to unified envelope (automatic in Phase 1)
device_response_t response = event_response_to_device_response(&event);

// Layer 3: Serialize (handled by send_event_response_full())
send_event_response_full(&entry);

Installation

Quick Start

# Get the release
git checkout v1.13.8

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • event_response_t Layer 1 response type in include/event_queue.h - bridges raw event data to device response envelope
  • event_response_ok() builder function - creates successful event responses with validation
  • event_response_error() builder function - creates error event responses with error classification
  • event_response_to_device_response() converter function - Layer 2 transformation from domain to transport layer
  • Deprecation notices on legacy command_response_t in text_command.h - guides migration path
  • Deprecation notices on legacy response_t union pattern in response.h - documents technical rationale

🔧 Changed

  • Enhanced documentation in include/event_queue.h with clear Layer 1→2→3 separation
  • Updated include/response.h with migration timeline (v1.14.0→v1.16.0) and rationale
  • Added architectural clarity to include/text_command.h regarding duplicate types

📋 Documentation

  • Comprehensive progress log entry documenting Phase 0 analysis and implementation
  • Clear deprecation timeline for legacy patterns (v1.15.0 planned removal)
  • Migration guidance for developers in Phase 1 handler refactoring

Is It Safe to Upgrade?

Backward Compatible: ✅ Yes

  • Zero breaking changes to public API
  • No runtime behavior modifications
  • All existing code continues to work
  • Pure type definition and documentation additions
  • Legacy paths unaffected by new types

Tests Passed

  • ✅ Build succeeds (esp32dev-dev profile)
  • ✅ RAM usage: 8.8% (28764 / 327680 bytes)
  • ✅ Flash usage: 26.6% (348221 / 1310720 bytes)
  • ✅ Pre-commit hooks pass (trailing whitespace, file endings, merge conflicts)
  • ✅ No breaking changes to existing functionality

Release Details

  • Date: 2025-12-10
  • Version: v1.13.8
  • Files Changed: 5
  • include/event_queue.h (+70 lines)
  • include/event_response.h (+71 lines)
  • include/text_command.h (+30 lines)
  • include/response.h (+25 lines)
  • docs/progress/entries/2025-12-10-device-response-unification-analysis.md (new)

Next Steps

Phase 1: Handler Refactoring (v1.14.0, estimated 2-3 weeks):

  1. Refactor all 16 command handlers to use device_response_ok/error builders instead of snprintf() JSON construction
  2. Implement command_response_to_device() Layer 2 converter function
  3. Create unified serialization layer via send_response() function
  4. Establish symmetric Layer 1→2→3 pattern for both command and event paths

Phase 2: Complete Unification:

  • Implement event response Layer 1 path with full builder pattern
  • Verify symmetric architecture for all response types
  • Documentation and developer guide updates

See also: docs/architecture/device-response-protocol-v1.md for detailed Phase 1-4 timeline