Skip to content

v1.13.12 - Phase 6 Payload Pointer Pattern (2025-12-11)

What Changed?

This release implements Phase 6 of the device response architecture, introducing a more memory-efficient payload handling pattern. Command handlers now use pointers to static JsonDocument structures instead of embedding typed fields directly. This enables type-flexible responses without modifying struct definitions, while reducing per-response memory overhead by 96.5%.

What's New

Main Feature: Phase 6 Payload Pointer Pattern

What it does: Introduces a new pattern for command handlers to return response payloads. Instead of populating typed struct fields, handlers now create a static JsonDocument and set a pointer to it in the response. This allows handlers to define any JSON structure they need without modifying the core response struct.

How to use it: When implementing a command handler, create a static JsonDocument in the handler function, populate it with command-specific fields, and set the pointer:

Code example:

command_response_t handle_get_version(const command_t& cmd) {
  // Create static JsonDocument for payload
  static JsonDocument payload;
  payload.clear();

  // Populate with command-specific fields
  payload["version"] = Command::getInstance().get_version();

  // Set pointer and return
  command_response_t response = success_response();
  response.payload = &payload;
  return response;
}

Installation

Quick Start

# Get the release
git checkout v1.13.12

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • Phase 6 payload pointer pattern for command responses
  • JsonDocument pointer field in command_response_t and device_response_t
  • Unified JSON merging in DeviceResponse::send() for all command types

🔧 Changed

  • All command handlers migrated to use static JsonDocument for payloads
  • Response struct size reduced from ~230 bytes to 8 bytes (pointer only)
  • Handler pattern now unified across all command types
  • Device response serialization now merges JsonDocument payloads with envelope

🐛 Fixed

  • ArduinoJson type compatibility with GCC 8.4.0 (JsonObjectConst iteration)
  • Missing ArduinoJson.h include in command_queue.h

Is It Safe to Upgrade?

Backward Compatible: Yes

  • All existing commands work identically(same input/output behavior)
  • Response JSON format unchanged
  • Error handling unchanged
  • ENABLE_DEVICE_RESPONSE flag allows fallback to legacy mode if needed
  • No breaking changes to serial protocol or command interfaces

Tests Passed

  • ✅ Builds without errors(all 4 commits)
  • ✅ RAM usage stable at 30.7%(100,604 / 327,680 bytes)
  • ✅ Flash usage at 25.3%(331,393 / 1,310,720 bytes)
  • ✅ GET_VERSION command returns correct format
  • ✅ GET_STATUS command with multiple payload fields
  • ✅ Error responses correctly set null payload
  • ✅ ArduinoJson JsonObjectConst iteration works with GCC 8.4.0

Release Details

  • Date: 2025-12-11
  • Version: v1.13.12
  • Files Changed: 10
  • Commits: 4
  • Lines Added: 220
  • Key Files: command_queue.h, device_response.h, device_response.cpp, all command handlers

Next Steps

Phase 7 Planned Enhancements:

  • Error response payloads with diagnostic information
  • Streaming responses for large datasets
  • Client-side type validation using JSON Schema

Immediate Focus:

  • Complete migration of remaining command handlers if any
  • Full integration testing with all command types
  • Performance profiling of JSON merging operations