Skip to content

NOTES

Overview

The command module provides MQTT remote control functionality for sensing operations. It allows users to control online and offline sensing through MQTT commands, enabling remote monitoring and control of sensor data acquisition.

Command Format

All sensing commands start with SENSE, prefix to distinguish them from other command types.

Command Structure

SENSE,<TYPE>,<ACTION>,<PARAMETERS>

Where: - <TYPE>: ONLINE or OFFLINE - <ACTION>: Command action (e.g., F=, D=, STOP, STATUS) - <PARAMETERS>: Command-specific parameters

Online Sensing Commands

Start/Configure Online Sensing

SENSE,ONLINE,F=<frequency>,D=<duration>
  • F: Sampling frequency in Hz (float, range: 0.1 - 10000 Hz)
  • D: Duration in seconds (float, 0 means continuous operation)

Examples: - SENSE,ONLINE,F=20,D=60 - 20 Hz sampling for 60 seconds - SENSE,ONLINE,F=1,D=0 - 1 Hz sampling, continuous operation

Stop Online Sensing

SENSE,ONLINE,STOP

Immediately stops the online sensing operation.

Query Online Sensing Status

SENSE,ONLINE,STATUS

Returns the current status and configuration of online sensing.

Offline Sensing Commands

Immediate Start

SENSE,OFFLINE,F=<frequency>,D=<duration>
  • F: Sampling frequency in Hz (float, range: 1 - 4000 Hz)
  • D: Sampling duration in seconds (float, must be > 0)

Example: - SENSE,OFFLINE,F=100,D=10 - 100 Hz sampling for 10 seconds

Delayed Start

SENSE,OFFLINE,F=<frequency>,D=<duration>,DL=<delay_seconds>
  • DL: Delay time in seconds (integer, >= 0)

Example: - SENSE,OFFLINE,F=100,D=10,DL=5 - Start after 5 seconds, then sample at 100 Hz for 10 seconds

Scheduled Start

SENSE,OFFLINE,F=<frequency>,D=<duration>,TIME=<YYMMDDHHMMSS>
  • TIME: Time format YYMMDDHHMMSS (12 digits)
  • YY: Year (00-99, represents 2000-2099)
  • MM: Month (01-12)
  • DD: Day (01-31)
  • HH: Hour (00-23)
  • MM: Minute (00-59)
  • SS: Second (00-59)

Example: - SENSE,OFFLINE,F=100,D=10,TIME=251216200000 - Start at 2025-12-16 20:00:00

Stop Offline Sensing

SENSE,OFFLINE,STOP

Stops the offline sensing operation if it is currently running.

Query Offline Sensing Status

SENSE,OFFLINE,STATUS

Returns the current status of offline sensing.

Response Format

After command execution, the device publishes a response message via MQTT:

Success Responses

  • SENSE,OK,ONLINE,F=20.00,D=60.00 - Online sensing started successfully
  • SENSE,OK,ONLINE,STOPPED - Online sensing stopped successfully
  • SENSE,OK,OFFLINE,F=100.00,D=10.00 - Offline sensing started successfully
  • SENSE,OK,OFFLINE,SAMPLES=1000,FREQ=100.00,DUR=10.00,SD=OK - Offline sensing completed

Error Responses

  • SENSE,ERROR,ONLINE,INVALID_FREQ - Invalid frequency parameter
  • SENSE,ERROR,OFFLINE,ALREADY_RUNNING - Offline sensing already in progress
  • SENSE,ERROR,OFFLINE,TIME_PAST - Scheduled time is in the past
  • SENSE,ERROR,SENSOR_NOT_INITIALIZED - Sensor not initialized

Implementation Details

Command Processing Architecture

The command handler uses a queue-based architecture:

  1. Command Queue: Commands are queued for processing to avoid blocking MQTT callback
  2. Command Processing Task: A dedicated FreeRTOS task processes commands from the queue
  3. Non-blocking Operations: Long-running operations (like offline sensing) are executed in separate tasks

Parameter Parsing

The module includes robust parameter parsing functions:

  • parse_float_param(): Extracts float parameters (e.g., F=20.5)
  • parse_int_param(): Extracts integer parameters (e.g., DL=5)
  • parse_time_param(): Parses time strings in YYMMDDHHMMSS format

Thread Safety

  • Commands are processed sequentially through a queue
  • Sensor handle is set before processing commands
  • State checks prevent concurrent operations

Usage Notes

  1. Sensor Initialization: The sensor handle must be set using sensing_command_set_sensor_handle() before processing commands.

  2. MQTT Connection: MQTT must be connected for command processing and response publishing.

  3. Time Synchronization: For scheduled start (TIME parameter), system time must be synchronized (NTP).

  4. Concurrent Operations: The system prevents starting offline sensing while it's already running, but online sensing can be stopped and restarted with new parameters.

  5. Command Format: Commands are case-sensitive and must follow the exact format. Extra spaces are automatically trimmed.

Error Handling

The command handler validates:

  • Command format and structure
  • Parameter ranges (frequency, duration, delay)
  • System state (sensor initialization, running status)
  • Time validity (for scheduled operations)

All errors are reported via MQTT response messages for remote debugging.