Skip to content

v1.16.6 - Enhanced GET_USAGE Command with Argument Specifications (2025-12-12)

What Changed?

This release enhances the GET_USAGE command output to include argument specifications for all available commands. Users can now see exactly what arguments each command expects in a structured table format with command name, argument specification, and description. This improvement makes the command interface more discoverable and user-friendly.

What's New

Main Feature: Argument Specifications in GET_USAGE Output

What it does: The GET_USAGE command now returns comprehensive command information including the argument specification for each command. This allows users and client applications to understand the exact syntax required for each command without needing external documentation.

How to use it: Send the GET_USAGE command via the serial interface. The response now includes an args field for each command showing the expected argument format.

Example output:

{
  "type": "response",
  "status": "ok",
  "sent_at": 12345,
  "commands": [
    {"command": "GET_VERSION", "args": "", "description": "Firmware version"},
    {"command": "SET_POLL_COUNT", "args": "<count>", "description": "Set poll count"},
    {"command": "SET_THRESHOLD", "args": "<ch> <val>", "description": "Set DAC threshold"},
    {"command": "TEST_LED", "args": "<ch|ALL> <ON|OFF>", "description": "Test LED control"}
  ]
}

Argument Format Convention:

  • Empty string "" - Command takes no arguments
  • <name> - Single required argument
  • <name1> <name2> - Multiple required arguments
  • <option1|option2> - Multiple choices for an argument

Installation

Quick Start

# Get the release
git checkout v1.16.6

# Build
task build

# Upload
task upload

# Check it works
task monitor

What's Different from the Last Version?

✅ Added

  • args field to command_entry_t structure for storing argument specifications
  • Argument specifications in command_table[] for all 30+ commands (e.g., "<count>", "<ch> <val>", "<0|1>")
  • args field to GET_USAGE JSON response output for better discoverability

🔧 Changed

  • GET_USAGE command response now includes three fields: command, args, and description (previously only had command and description)

Is It Safe to Upgrade?

Backward Compatible: Yes

  • GET_USAGE response is extended, not changed (existing command and description fields remain)
  • New args field is additive and does not affect existing command parsing or execution
  • No changes to command behavior or detection logic
  • Safe to upgrade from v1.16.5

Tests Passed

  • ✅ dev:build succeeds (RAM 8.8%, Flash 26.6%)
  • ✅ prod:build succeeds (RAM 8.1%, Flash 26.2%)
  • ✅ GET_USAGE command returns JSON with command, args, and description fields
  • ✅ All commands have appropriate argument specifications

Release Details

  • Date: 2025-12-12
  • Version: v1.16.6
  • Files Changed: 3
  • include/command_queue.h - Added args field to command_entry_t structure
  • src/command_manager.cpp - Updated 30+ command table entries with argument specs
  • src/command/usage.cpp - Added args to JSON output

Next Steps

  • Consider extending argument specifications to GET_HELP command for additional discoverability
  • Plan integration of command argument metadata with client applications and documentation generation
  • Explore dynamic command validation based on argument specifications in future versions