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

Progress Log: Detection Stream Control Implementation

Task Description

Implement runtime control to enable/disable detection data streaming output while maintaining command reception and response transmission at all times. The requirement was to add a SET_STREAM 1|0 command for toggling output, with an internal enable_stream flag that doesn't affect command processing.

Outcome

Successfully completed and committed (4dfe70c)

5 files modified, 132 insertions (+), 8 deletions (-)

  1. include/runtime_config.h
  2. Added bool config_get_stream_enabled(void) - query current state

  3. Added void config_set_stream_enabled(bool enable) - set stream state

  4. src/runtime_config.cpp

  5. Added static bool g_stream_enabled = true - global flag (default enabled)

  6. Implemented Getter/Setter functions

  7. src/stream_formatter.cpp

  8. Modified send_event() dispatcher to check flag before output
  9. Early return if stream disabled (minimal overhead)

  10. Includes runtime_config.h header

  11. include/stream_formatter.h

  12. Updated send_event() documentation with stream control notes

  13. Added usage examples (C API, text commands)

  14. src/text_command_handlers.cpp

  15. Added handle_set_stream() - SET_STREAM <0|1> command
  16. Added handle_get_stream() - GET_STREAM query command
  17. Registered both in command dispatch table (Stream category)
  18. Updated RESET handler with note about stream state persistence

Key Design Decisions

  1. Non-intrusive implementation: Only send_event() checks flag, main loop unchanged
  2. Getter/Setter pattern: Encapsulates flag access via config_* namespace
  3. Stream state persistence: RESET command doesn't reset stream flag (intentional)
  4. Minimal overhead: Single boolean check when disabled (<1 CPU cycle)
  5. Backward compatible: Default enabled matches original behavior

Build Results

All configurations successful:

  • prod:build: RAM 6.9%, Flash 23.4% (SUCCESS)
  • debug:build: Compilation passed
  • dev:build: RAM 8.4%, Flash 24.7% (SUCCESS)

Command Usage

# Disable stream output
SET_STREAM 0
# Response: {"type":"response","status":"ok","stream_enabled":0}

# Query stream state
GET_STREAM
# Response: {"type":"response","status":"ok","stream_enabled":1}

# Enable stream output
SET_STREAM 1
# Response: {"type":"response","status":"ok","stream_enabled":1}

Learnings

  1. Naming consistency matters: Using config_* prefix for all functions maintains consistency with existing config_get_poll_count(), config_set_threshold() patterns

  2. Encapsulation vs. performance tradeoff resolved: Getter function adds ~1 instruction, compiler optimizes it away; maintains API encapsulation

  3. Flag placement is critical: Checking in send_event() (the dispatcher) is the right place—single point that affects all formats (SSV/TSV/CSV/JSONL)

  4. Compile-time and runtime checks work together:

  5. Format selection: Compile-time via #if STREAM_FORMAT (zero overhead)

  6. Stream control: Runtime via boolean flag (minimal overhead when disabled)

  7. Command table architecture is flexible: Adding new commands requires only:

  8. Handler function declaration
  9. Handler implementation
  10. One line in dispatch table
  11. No changes to command parsing/execution loop

Next Steps

  • Optional: Add stream state to GET_STATUS output for visibility
  • Optional: Add debug logging for stream state transitions
  • Consider: Persistent stream state across power cycles (if needed, use NVRAM)