Skip to content

v1.12.1 - Unified Device Response Builder Module (2025-12-08)

What Changed?

This release introduces the DeviceResponseBuilder module, a reusable factory pattern for consolidating JSON response generation across all command handlers. The refactoring eliminates 60+ lines of duplicate code, reduces binary size by 2,344 bytes, and prepares the infrastructure for Phase 2B nested response handlers while maintaining 100% backward compatibility.

What's New

Main Feature: Response Builder Pattern

What it does: The new DeviceResponseBuilder class provides static factory methods to create device response JSON documents without code duplication. Handlers now call builder methods instead of manually constructing JSON, reducing code complexity and improving maintainability.

How to use it: Instead of manually constructing JSON in each handler:

// OLD (before v1.12.1)
JsonDocument doc;
doc["type"] = "response";
doc["status"] = "ok";
doc["sent_at"] = device_get_timestamp();
doc["version"] = config_get_version();
serializeJson(doc, Serial);
Serial.println();

Use the builder for a cleaner, DRY approach:

// NEW (v1.12.1+)
JsonDocument doc = DeviceResponseBuilder::simple("version", config_get_version());
serializeJson(doc, Serial);
Serial.println();

Code example:

All simple handlers now follow this pattern:

static command_response_t handle_get_version(text_command_t cmd) {
  if (cmd.arg_count != 0) {
    text_response_error(F("GET_VERSION"), F("Unexpected arguments"), 1);
    return response;
  }

#if ENABLE_DEVICE_RESPONSE
  // Clean: 4 lines instead of 8
  JsonDocument doc = DeviceResponseBuilder::simple("version", config_get_version());
  serializeJson(doc, Serial);
  Serial.println();
  response.is_ok = true;
#else
  send_response(response_string("version", config_get_version()));
  response.is_ok = true;
#endif

  return response;
}

Builder API:

  • DeviceResponseBuilder::simple(const char* field, const char* value) - String field
  • DeviceResponseBuilder::simple(const char* field, int32_t value) - Integer field
  • DeviceResponseBuilder::simple(const char* field, bool value) - Boolean field
  • DeviceResponseBuilder::empty() - Base response for nested objects (Phase 2B)

Installation

Quick Start

# Get the release
git checkout v1.12.1

# Build
task build

# Upload
task upload

# Check it works
task monitor

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

✅ Added

  • DeviceResponseBuilder module (include/device_response_builder.h, src/device_response_builder.cpp)
  • Static factory methods for creating unified response JSON documents
  • Support for string, integer, and boolean payload fields
  • Helper method for nested object creation (Phase 2B preparation)
  • Full conditional compilation support (#if ENABLE_DEVICE_RESPONSE)

🔧 Changed

  • All 10 Phase 2A command handlers refactored:
  • GET_VERSION, GET_UPTIME, GET_MAC_ADDRESS, SET_POLL_COUNT, SET_DEADTIME
  • GET_STREAM, SET_STREAM, GET_QUEUE_STATS, TEST_LED, GET_HELP, RESET
  • Now use DeviceResponseBuilder instead of manual JSON construction
  • Code reduction: 50% fewer lines per handler (8 lines → 4 lines)

🐛 Fixed

  • Eliminated duplicate JSON construction code across handlers
  • Improved code maintainability via centralized builder logic
  • Binary size optimization: 2,344 bytes saved

Is It Safe to Upgrade?

Backward Compatible: Yes ✅

  • All handlers maintain identical JSON output format
  • No behavioral changes (type, status, sent_at fields unchanged)
  • Legacy code paths preserved via ENABLE_DEVICE_RESPONSE=1 flag
  • Existing client parsers continue to work without modification
  • Previous v1.12.0 output: {"type":"response","status":"ok","sent_at":47,"version":"1.12.0"}
  • v1.12.1 output: Identical

Tests Passed

  • ✅ Build: SUCCESS (Zero errors, Flash 26.7%, RAM 8.8%)
  • ✅ Builder module: Compiles and links without conflicts
  • ✅ All 10 refactored handlers: Zero compilation errors
  • ✅ JSON output validation: Identical to v1.12.0 baseline
  • ✅ Code reduction: 60+ lines eliminated, 2,344 bytes saved
  • ✅ Serial output: Verified at 115200 baud
  • ✅ Backward compatibility: All legacy code paths intact
  • ✅ Firmware upload: SUCCESS (13.47 seconds)

Release Details

  • Date: 2025-12-08
  • Version: v1.12.1
  • Files Changed: 4
  • Added: include/device_response_builder.h (185 lines)
  • Added: src/device_response_builder.cpp (82 lines)
  • Modified: src/text_command_manager.cpp (133 lines changed)
  • Modified: specs/028-device-response-unify/tasks.md (117 lines added)
  • Total Insertions: 409
  • Total Deletions: 108
  • Binary Size: 2,344 bytes saved

Next Steps

Phase 2B (Nested Handlers): Coming next is migration of complex handlers with nested response objects:

  • GET_THRESHOLD, SET_THRESHOLD
  • GET_GNSS_STATUS, GET_GNSS_POSITION, GET_GNSS_TIME
  • GET_RTC_TIME, SET_RTC_TIME

The DeviceResponseBuilder::empty() factory method provides the foundation for these nested responses, reducing code duplication in Phase 2B handlers as well.

Phase 2C (Complex Handlers): After Phase 2B, GET_STATUS and GET_HELP handlers will be refactored with multiple nested objects and conditional fields based on ENABLE_* flags.

Phase 3 (Event Output): Detection events will be unified to use the same device_response_t structure with type="event".

Phase 4 (Legacy Cleanup): Once all handlers use device_response_t, the legacy response.h and response.cpp files will be removed, providing additional binary size savings.