Skip to content

v1.10.8 - Structured Responses & Documentation (2025-12-06)

What Changed?

This release improves API clarity by restructuring response formats into logical domains and adding comprehensive documentation to all command handlers. The GET_BME280 command is added for direct sensor data queries, while GET_STATUS and GET_QUEUE_STATS now return hierarchically organized JSON. All 18 text command handlers now include detailed docstrings showing response formats, making the API self-documenting.

What's New

Feature 1: GET_BME280 Command

What it does: Retrieves current BME280 environmental sensor readings (temperature, pressure, humidity) on demand via text command.

How to use it: Send the GET_BME280 command to get sensor data:

GET_BME280

Response format:

{
  "type": "response",
  "status": "ok",
  "bme280": {
    "tmp_c": 25.35,
    "atm_pa": 1013.25,
    "hmd_pct": 45.67
  }
}

Feature 2: Structured Response Formats

What it does: GET_STATUS and GET_QUEUE_STATS responses are now organized into logical nested domains, improving readability and maintainability.

GET_STATUS now returns nested structure:

{
  "type": "response",
  "status": "ok",
  "system": {"version": "1.10.8", "uptime_ms": 12345, "adc_channel": 32},
  "detection": {"poll_count": 100, "deadtime_ms": 0, "threshold1": 1234, ...},
  "features": {"bme280": 1, "rtc": 1, "timestamp": 1, ...}
}

GET_QUEUE_STATS now returns nested queue object:

{
  "type": "response",
  "status": "ok",
  "queue": {
    "total_events": 42,
    "queue_overflows": 0,
    "current_depth": 0,
    "max_depth": 3,
    "initialized": true
  }
}

Feature 3: Comprehensive Handler Documentation

What it does: All 18 text command handlers now include detailed docstrings with response formats, making the API self-documenting for developers.

Benefits:

  • Each handler documents: Format, Examples, Description, Aliases, Returns
  • Developers can see exact JSON structure before sending commands
  • IDE integrates docstrings for code completion hints

Installation

Quick Start

# Get the release
git checkout vX.Y.Z

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • GET_BME280 command for on-demand sensor data queries
  • Returns field in all 18 handler docstrings with JSONL response examples
  • Nested bme280 object in GET_BME280 response

🔧 Changed

  • GET_STATUS response: now uses nested system, detection, features domains
  • GET_QUEUE_STATS response: now uses nested queue object for better structure
  • All handler docstrings follow unified format with Format, Examples, Aliases, Returns sections

🐛 Fixed

  • API documentation clarity: developers can now see exact JSON structure in code

Is It Safe to Upgrade?

Backward Compatible: Mostly Yes - with minor parsing adjustments

  • Existing GET_STATUS clients need to parse new nested structure (system/detection/features)
  • Existing GET_QUEUE_STATS clients need to look for data under queue key
  • GET_BME280 is new and has no backward compatibility concerns
  • All field names remain unchanged, only nesting structure changed
  • Text commands themselves unchanged; new command (GET_BME280) is purely additive

Tests Passed

  • ✅ Builds without errors (dev:build, prod:build, debug:build)
  • ✅ Flash usage: 24.8% (324,573 / 1,310,720 bytes)
  • ✅ RAM usage: 8.4% (27,456 / 327,680 bytes)
  • ✅ All handlers return proper JSONL format
  • ✅ GET_BME280 returns sensor data in nested object
  • ✅ GET_STATUS returns hierarchical response
  • ✅ GET_QUEUE_STATS returns nested queue statistics

Release Details

  • Date: 2025-12-06
  • Version: v1.10.8
  • Files Changed: 1 (src/text_command_handlers.cpp)
  • Commits:
  • 89c038a: feat(text-command): add GET_BME280 command for sensor data retrieval
  • fa37c7c: refactor(text-command): restructure GET_STATUS response with nested domains
  • 98dd16f: refactor(text-command): restructure GET_QUEUE_STATS response with nested queue object
  • 296799f: docs(text-command): add Returns section to all handler docstrings

Next Steps

  • Implement GET_ADC command for raw ADC value queries
  • Add structured responses to binary protocol equivalents
  • Expand API documentation with request/response examples
  • Consider response versioning for future API evolution