Command and metrics reference

MQTT commands and model metrics

The following is a reference for the MQTT commands and model metrics that are available in the Edge Impulse Greengrass integration.

Use the commands to do the following through AWS IoT Core MQTT topics:

• Control the Edge Impulse Linux Runner service
• Manage the confidence threshold filter
• Retrieve model information
• Manage the inference cache

Commands are sent as JSON messages to the device’s command input topic and results are published to the command output topic:

    

        
        
/edgeimpulse/device/<device-name>/command/input
/edgeimpulse/device/<device-name>/command/output

    

All commands use the following JSON structure:

    

        
        
{
   "cmd": "<command-verb>",
   "value": "<optional-value>"
}

    

The value field is required only for commands that set a value.

Model metrics

The Edge Impulse Linux Runner accumulates and publishes model metrics to IoT Core at the interval specified by the metrics_sleeptime_ms configuration parameter. Metrics are published to:

    

        
        
/edgeimpulse/device/<device-name>/model/metrics

    

The published metrics include:

• mean_confidence: Running average of inference confidence scores for the current model.
• standard_deviation: Running standard deviation of confidence scores.
• confidence_trend: Direction the confidence is trending (incr or decr).

The output is similar to:

    

        
        {
   "mean_confidence": 0.696142,
   "standard_deviation": 0.095282,
   "confidence_trend": "decr",
   "details": {
      "n": 5,
      "sum_confidences": 3.480711,
      "sum_confidences_squared": 2.468464
   },
   "ts": 1736016142920,
   "id": "e4faa78b-2a09-40d1-adfd-8e5fc32feb11"
}

        
    

Startup notification

When the Edge Impulse Linux Runner starts or restarts, it publishes the following JSON to the command output topic:

    

        
        {
   "result": {
      "status": "started",
      "ts": 1736026956853,
      "id": "5c4e627e-6e9d-4382-bba7-00c0129705c4"
   }
}

        
    

You can use this message to detect service restarts and re-apply any runtime changes (for example, confidence filter settings) to the newly started Edge Impulse Linux Runner.

MQTT commands

The following MQTT commands are available in the Edge Impulse Greengrass integration:

restart

The command restarts the Edge Impulse Linux Runner process:

    

        
        
{
   "cmd": "restart"
}

    

When used with the ei_shutdown_behavior option set to wait_on_restart, the Edge Impulse Linux Runner pauses after the model completes and waits for this command before restarting.

enable_threshold_filter

The command enables the confidence threshold filter:

    

        
        
{
   "cmd": "enable_threshold_filter"
}

    

By default, the filter is disabled and all results are published. When enabled, only inference results that meet the threshold criteria are published to IoT Core.

The output is similar to:

    

        
        {
   "result": {
      "threshold_filter_config": {
         "enabled": "yes",
         "confidence_threshold": 0.7,
         "threshold_criteria": "ge"
      }
   }
}

        
    

disable_threshold_filter

The command disables the confidence threshold filter:

    

        
        
{
   "cmd": "disable_threshold_filter"
}

    

All inference results are published to IoT Core regardless of confidence score.

The output is similar to:

    

        
        {
   "result": {
      "threshold_filter_config": {
         "enabled": "no",
         "confidence_threshold": 0.7,
         "threshold_criteria": "ge"
      }
   }
}

        
    

set_threshold_filter_criteria

The command sets the comparison operator for the confidence threshold filter:

    

        
        
{
   "cmd": "set_threshold_filter_criteria",
   "value": "ge"
}

    

The available criteria are:

The output is similar to:

    

        
        {
   "result": {
      "criteria": "gt"
   }
}

        
    

get_threshold_filter_criteria

The command retrieves the currently configured threshold filter criteria:

    

        
        
{
   "cmd": "get_threshold_filter_criteria"
}

    

The output is similar to:

    

        
        {
   "result": {
      "criteria": "gt"
   }
}

        
    

set_threshold_filter_confidence

The command sets the confidence threshold value between 0 and 100:

    

        
        
{
   "cmd": "set_threshold_filter_confidence",
   "value": 0.756
}

    

Inference results are filtered against this value using the configured criteria.

The output is similar to:

    

        
        {
   "result": {
      "confidence_threshold": "0.756"
   }
}

        
    

get_threshold_filter_confidence

The command retrieves the currently configured confidence threshold value:

    

        
        
{
   "cmd": "get_threshold_filter_confidence"
}

    

The output is similar to:

    

        
        {
   "result": {
      "confidence_threshold": "0.756"
   }
}

        
    

get_threshold_filter_config

The command retrieves the complete threshold filter configuration, including enabled state, confidence value, and criteria:

    

        
        
{
   "cmd": "get_threshold_filter_config"
}

    

The output is similar to:

    

        
        {
   "result": {
      "threshold_filter_config": {
         "enabled": "no",
         "confidence_threshold": "0.756",
         "threshold_criteria": "gt"
      }
   }
}

        
    

get_model_info

The command retrieves information about the currently running model, including its name, version, input dimensions, labels, and detection type:

    

        
        
{
   "cmd": "get_model_info"
}

    

The output is similar to:

    

        
        {
   "result": {
      "model_info": {
         "model_name": "occupant_counter",
         "model_version": "v25",
         "model_params": {
            "axis_count": 1,
            "frequency": 0,
            "has_anomaly": 0,
            "image_channel_count": 3,
            "image_input_frames": 1,
            "image_input_height": 640,
            "image_input_width": 640,
            "image_resize_mode": "fit-longest",
            "inferencing_engine": 6,
            "input_features_count": 409600,
            "interval_ms": 1,
            "label_count": 1,
            "labels": [
               "person"
            ],
            "model_type": "object_detection",
            "sensor": 3,
            "slice_size": 102400,
            "threshold": 0.5,
            "use_continuous_mode": false,
            "sensorType": "camera"
         }
      }
   }
}

        
    

reset_metrics

The command resets the accumulated model metrics counters to zero:

    

        
        
{
   "cmd": "reset_metrics"
}

    

The output is similar to:

    

        
        {
   "result": {
      "metrics_reset": "OK"
   }
}

        
    

clear_cache

The command clears all inference image caches. It respects the component configuration — it clears all caches that are currently enabled (local file cache, S3 cache, or both):

    

        
        
{
   "cmd": "clear_cache"
}

    

The output is similar to:

    

        
        {
   "result": {
      "clear_cache": {
         "local": "OK",
         "s3": "OK"
      }
   }
}

        
    

clear_cache_file

The command clears a specific cached inference result by its UUID:

    

        
        
{
   "cmd": "clear_cache_file",
   "value": "<uuid>"
}

    

Like clear_cache, clear_cache_file clears the file from all enabled caches.

The output is similar to:

    

        
        {
   "result": {
      "clear_cache_file": {
         "local": "OK",
         "s3": "OK",
         "uuid": "e4faa78b-2a09-40d1-adfd-8e5fc32feb11"
      }
   }
}

        
    

What you’ve learned

You can now use MQTT commands through AWS IoT Core to control the Edge Impulse Linux Runner in real time and interpret its model metrics.