Skip to content

v1.13.14 - Update RESET & STREAM Commands (2025-12-11)

What Changed?

This release completes Phase 6 Payload Pointer Pattern migration for additional command handlers. The RESET and STREAM command handlers (both SET_STREAM and GET_STREAM) have been refactored to follow the unified 3-layer architecture, providing consistent structured JSON payloads and improved code organization. All changes maintain backward compatibility—only response structure clarity is enhanced.

What's New

Refactoring: Phase 6 Pattern Migration

What it does: Consolidates command handler architecture across the codebase by migrating RESET and STREAM handlers to Phase 6 Payload Pointer Pattern. This ensures all command handlers follow the same structured 3-layer approach: validation → business logic → payload creation.

Pattern Overview:

The Phase 6 pattern standardizes all command handlers with:

  1. VALIDATION Layer - Check argument count and type validation
  2. BUSINESS LOGIC Layer - Execute command-specific logic via Command class
  3. LAYER 1 OUTPUT - Create static JsonDocument payload with response-specific fields

Handler Examples:

RESET Handler:

// VALIDATION: No arguments expected
if (cmd.arg_count != 0) {
  return error_response(DEVICE_CODE_INVALID_ARG, "RESET takes no arguments");
}

// BUSINESS LOGIC: Reset configuration
// (Command::getInstance().reset() - implementation in Command class)

// LAYER 1 OUTPUT: Create payload
static JsonDocument payload;
payload.clear();
payload["message"] = "Factory reset initiated";
response.payload = &payload;

SET_STREAM Handler:

// VALIDATION: Requires one argument (0 or 1)
if (cmd.arg_count != 1) {
  return error_response(DEVICE_CODE_INVALID_ARG, "SET_STREAM requires one argument: <0|1>");
}

// Parse and validate numeric input
uint8_t enable = (uint8_t)strtoul(cmd.args[0], &endptr, 10);
if (*endptr != '\0' || enable > 1) {
  return error_response(DEVICE_CODE_OUT_OF_RANGE, "Invalid stream value (must be 0 or 1)");
}

// BUSINESS LOGIC: Apply stream configuration
Command::getInstance().set_stream((bool)enable);

// LAYER 1 OUTPUT: Create payload with confirmation
static JsonDocument payload;
payload.clear();
payload["stream_enabled"] = (bool)enable;
response.payload = &payload;

Response Examples:

// RESET command
RESET
{"type":"response","status":"ok","sent_at":12345,"message":"Factory reset initiated"}

// SET_STREAM 1 (enable detection output)
SET_STREAM 1
{"type":"response","status":"ok","sent_at":12345,"stream_enabled":true}

// GET_STREAM
GET_STREAM
{"type":"response","status":"ok","sent_at":12345,"stream_enabled":true}

// Error: Invalid argument
SET_STREAM invalid
{"type":"response","status":"error","sent_at":12345,"error_code":2,"error_message":"Invalid stream value (must be 0 or 1)"}

Architecture Benefits

  1. Consistency: All command handlers now follow identical 3-layer structure
  2. Maintainability: Clear separation of validation, logic, and output concerns
  3. Extensibility: New handlers can be added following the same proven pattern
  4. Type Safety: Static JsonDocument ensures pointer validity through serialization layers
  5. Code Clarity: Organized sections with clear section headers make handler intent obvious

Installation

Quick Start

# Get the release
git checkout v1.13.14

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • Comprehensive JSDoc documentation for RESET handler
  • Enhanced file header documentation for STREAM handlers with command signatures

🔧 Changed

  • RESET handler refactored to Phase 6 Payload Pointer Pattern
  • SET_STREAM handler refactored to Phase 6 Payload Pointer Pattern
  • GET_STREAM handler refactored to Phase 6 Payload Pointer Pattern
  • All handlers now use structured 3-layer architecture with section comments
  • Response payloads now properly return confirmation values

🐛 Fixed

  • RESET now returns confirmation message in response payload (previously empty)
  • STREAM handlers now return state confirmation in response payload (previously empty)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • Command syntax unchanged (RESET, SET_STREAM, GET_STREAM work identically)
  • Response format enhanced with proper payload fields (response envelope format unchanged)
  • Clients expecting structured JSON payloads will now receive them consistently
  • No breaking changes to serial protocol or command syntax

Tests Passed

  • ✅ Builds without errors (all PlatformIO environments)
  • ✅ Pre-commit hooks pass (formatting, trailing whitespace, YAML/JSON validation)
  • ✅ Phase 6 Payload Pointer Pattern implementation verified for RESET and STREAM handlers
  • ✅ Command handler architecture consistency confirmed

Release Details

  • Date: 2025-12-11
  • Version: v1.13.14
  • Files Changed: 2
  • src/command/reset.cpp (refactored)
  • src/command/stream.cpp (refactored)

Next Steps

  • Migrate remaining command handlers to Phase 6 pattern (GNSS, WiFi, etc.)
  • CommandParser class planned for v1.14.0 to centralize argument parsing
  • Complete Phase 1 of Unified Device Response Protocol consolidation