v1.7.1 - Text Protocol Response JSONL Unification (2025-11-21)

What Changed?

v1.7.1 unifies all text protocol command responses to JSON Lines (JSONL) format. This dramatically simplifies client-side processing and enables unified handling of detection events and command responses with a single parser.

---

What's New

Main Feature: Text Protocol Response JSONL Unification

What it does:

All 10 text commands (GET_VERSION, SET_THRESHOLD, STATUS, etc.) now return responses in standardized JSON Lines format. Error responses also follow a consistent schema with error codes.

Key Improvements:

1. Unified Format: All command responses in JSON Lines format
2. Helper Functions: send_error_response() / send_ok_response() for standardization
3. Error Code Unification: 1=invalid argument, 2=out of range, 3=internal error
4. Memory Optimization: F() macro moves strings to FLASH (~500 bytes RAM saved)
5. Code Quality: 197 lines eliminated, 60% duplication reduced

How to use it:

Text command responses now return in unified JSON format. No configuration needed—existing command usage remains unchanged.

# Serial Monitor usage example
GET_VERSION
# Response: {"version":"1.7.1"}

STATUS
# Response: {"version":"1.7.1","poll_count":100,"interval_ms":0,"threshold1":0,"threshold2":0,"threshold3":0,"uptime_ms":12345}

SET_THRESHOLD 1 500
# Response: {"channel":1,"threshold":500}

# Error response example
SET_THRESHOLD 1 5000
# Response: {"status":"error","command":"SET_THRESHOLD","error":"Threshold value out of range [0, 4095]","code":2}

Code example:

Implementation pattern (unified across all handlers):

// Success response pattern
static CommandResponse handle_set_poll_count(SerialCommand cmd) {
  // ... argument validation ...

  StaticJsonDocument<128> doc;
  doc["poll_count"] = config_get_poll_count();
  serializeJson(doc, Serial);
  Serial.println();
  response.is_ok = true;
  return response;
}

// Error response pattern (helper function)
if (arg_count != 1) {
  send_error_response(F("SET_POLL_COUNT"), F("Missing required argument: <count>"), 1);
  return response;
}

---

Implementation Details

Supported Commands

All 10 text commands now respond in JSONL format:

Command	Response Example	Description
GET_VERSION	{"version":"1.7.1"}	Firmware version
GET_THRESHOLD <ch>	{"channel":1,"threshold":0}	Get channel threshold
SET_THRESHOLD <ch> <val>	{"channel":1,"threshold":500}	Set channel threshold
SET_POLL_COUNT <count>	{"poll_count":200}	Set polling count
SET_INTERVAL <ms>	{"interval_ms":5000}	Set detection interval (debug)
STATUS	{...7 fields...}	Full system status
UPTIME	{"uptime_ms":..., ...}	Time since power-on
LED <ch\|ALL> <ON\|OFF>	{"channel":1,"state":"ON"}	Control LEDs
HELP	{"commands":[...]}	Command list
RESET	{"status":"ok","message":"..."}	Reset configuration

Error Response Schema

Error responses follow a unified schema:

{"status":"error","command":"COMMAND_NAME","error":"Error message","code":1}

Error Codes:

• 1: Invalid argument (missing or malformed)
• 2: Out of range (value exceeds limits)
• 3: Internal error (command execution failed)

---

Installation

Quick Start

# Checkout v1.7.1
git checkout v1.7.1

# Build
task build

# Upload
task upload

# Verify with serial monitor
task monitor

# Send command examples
GET_VERSION
STATUS
SET_POLL_COUNT 150

---

What's Different from the Last Version?

✅ Added

• JSONL format responses for all text protocol commands
• send_error_response() helper function (standardizes error responses)
• send_ok_response() helper function (standardizes success responses)
• F() macro string optimization (51 occurrences)

🔧 Changed

• All text command response formats unified to JSON Lines
• Error messages returned with unified schema and codes
• Internal error handling optimized in command handlers

📊 Code Quality

• Reduced: 197 lines of code eliminated
• Duplication: 60% reduction in duplicated code
• RAM Optimization: ~500 bytes saved (F() macro)
• Memory Usage: Flash 23.9%, RAM 7.3%

---

Is It Safe to Upgrade?

Backward Compatible: Partial

• ✅ All existing text commands still work (argument format unchanged)
• ⚠️ Important: Client-side response parsing logic changes
• Shift from plaintext to JSON response format
• Client may need JSON parser updates

Recommendation:

After upgrading to v1.7.1, verify that your client program correctly parses JSON responses.

---

Tests Passed

• ✅ All 10 text commands confirmed JSONL response format
• ✅ Error response schema unification confirmed (error codes 1/2/3)
• ✅ F() macro memory optimization verified
• ✅ Build successful (Flash 23.9%, RAM 7.3%)
• ✅ All 3 build profiles verified (dev/debug/prod)

---

Data Acquisition Use Case

Combined with v1.7.0's serial output JSONL format, detection events and command responses can now be processed uniformly:

# Python example: Unified processing of detection events and responses
import json
from datetime import datetime

def parse_device_output(line):
    """Parse detection events and status responses with single function"""
    data = json.loads(line)

    # Detect event detection
    if 'signal1' in data:
        return {'type': 'detection', 'data': data}
    # Status response detection
    elif 'version' in data or 'status' in data:
        return {'type': 'response', 'data': data}
    return None

# Unified device logging
with open('device_log.jsonl', 'a') as logfile:
    for line in serial_input:
        parsed = parse_device_output(line)
        if parsed:
            record = {
                'timestamp': datetime.now().isoformat(),
                'type': parsed['type'],
                'payload': parsed['data']
            }
            json.dump(record, logfile)
            logfile.write('\n')

---

Release Details

• Date: 2025-11-21
• Version: v1.7.1
• Files Changed: 2 files
• REFACTORING_ROADMAP.md - Phase G completion record
• Commits: 4 commits
• bcd0f69 - Consolidate JSONL response with helper functions
• 57093e9 - Update REFACTORING_ROADMAP after Phase G completion

---

Next Steps

Near-term (v1.8.0)

1. Serial Protocol Specification - Document text protocol formally
2. Unit Tests - Comprehensive testing of text command handlers

Mid-term (v1.8.0+)

1. RTC Time Support - Add absolute timestamps (Unix timestamp)
2. Protocol Optimization - Revisit Phases A-F if needed

Long-term (v2.0.0+)

1. Multi-board support
2. Web dashboard with real-time visualization
3. Machine learning-based event classification

See REFACTORING_ROADMAP.md for details.