Skip to content
  • Date Created: 2025-12-06
  • Last Modified: 2025-12-06

Progress Log: Text Command Response Format Standardization

Task Description

Standardized response format across text command handlers to improve consistency and simplicity. Main changes include:

  1. GET_UPTIME Simplification: Removed complex time conversion (days, hours, minutes, seconds) and return only raw uptime_ms
  2. RTC_TIME Standardization: Added missing "type":"response" field and unified field names (rtc_timestamp)
  3. Format Verification: Confirmed all 19 text command handlers follow unified response format

Outcome

✅ Completed Successfully

Changes Made

  1. Commit 1 (6c86a90): GET_UPTIME simplification
  2. Removed time decomposition logic
  3. Response now: {"type":"response","status":"ok","uptime_ms":value}

  4. Saves ~30 bytes Flash, ~120 bytes JSON payload

  5. Commit 2 (2c1778b): RTC_TIME standardization

  6. Added "type":"response" to SET_RTC_TIME (line 825)
  7. Added "type":"response" to GET_RTC_TIME (line 857)
  8. Unified field names to "rtc_timestamp"

  9. Response format: {"type":"response","status":"ok","rtc_timestamp":value}

  10. Documentation

  11. Updated CLAUDE.md (line 341): GET_UPTIME description
  12. Created v1.10.6 release notes with detailed breaking changes

Verification

✅ All 19 text command handlers confirmed to have "type":"response" field:

  • SET_POLL_COUNT, SET_THRESHOLD, GET_THRESHOLD
  • GET_VERSION, RESET, SET_DEADTIME
  • GET_STATUS, TEST_LED, GET_UPTIME
  • GET_MAC_ADDRESS, GET_HELP
  • SET_STREAM, GET_STREAM
  • GET_QUEUE_STATS (conditional)
  • SET_RTC_TIME, GET_RTC_TIME (conditional)
  • SET_WIFI_SSID, SET_WIFI_ENABLE, GET_WIFI_STATUS (conditional)

Files Modified

  • src/text_command_handlers.cpp (2 commits, 8 lines changed)
  • CLAUDE.md (1 line updated)
  • docs/releases/v1.10.6.md (created, new file)

Learnings

1. Consistency as Design Principle

Standardizing response format across all commands:

  • Makes client parsing predictable
  • Reduces implementation bugs on client side
  • Sets pattern for future commands

2. Firmware Optimization Trade-offs

Removing time conversion from GET_UPTIME:

  • Saves firmware size and runtime overhead
  • Delegates responsibility to client (appropriate for embedded systems)
  • Client libraries can implement custom formatting

3. Breaking Changes Require Clear Documentation

RTC_TIME field renaming from timestamp/time to rtc_timestamp:

  • Improves clarity (matches uptime_ms pattern)
  • Requires explicit versioning and migration guide
  • Worth the one-time breaking change for long-term consistency

Next Steps

  1. Testing: Validate JSON parsing with actual serial output
  2. Client Migration: Update any existing client code using GET_UPTIME/RTC_TIME
  3. Release: Tag v1.10.6 and publish release notes
  4. Future: Consider Phase 1 of response layer refactoring using these standardized patterns