Remote Commands

Overview

Remote Commands let you control EdgeFlow devices from the cloud in real-time. Commands travel through the secure WebSocket tunnel and are processed by the device's Command Handler. Each command returns a structured response with status, data, or error information.

Command Format

Commands follow a request-response pattern over the tunnel:

# Request (Cloud → Device)
{
  "type": "command",
  "id": "cmd_unique_id",
  "action": "start_flow",
  "payload": {
    "flow_id": "flow_abc123"
  }
}

# Response (Device → Cloud)
{
  "type": "response",
  "id": "cmd_unique_id",
  "status": "success",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_xyz789",
    "status": "running"
  }
}

Available Commands

Health Check

Verify the device is responsive and get basic health info.

# Request
{"action": "health_check", "payload": {}}

# Response
{
  "status": "success",
  "data": {
    "status": "healthy",
    "uptime": 86400,
    "version": "1.2.3"
  }
}

List Flows

Get all flows on the device with their current status.

# Request
{"action": "list_flows", "payload": {}}

# Response
{
  "status": "success",
  "data": {
    "flows": [
      {
        "id": "flow_abc123",
        "name": "Temperature Monitor",
        "status": "running",
        "node_count": 5
      },
      {
        "id": "flow_def456",
        "name": "Motion Alerts",
        "status": "stopped",
        "node_count": 3
      }
    ]
  }
}

Get Flow

Retrieve the full flow definition including nodes and connections.

# Request
{"action": "get_flow", "payload": {"flow_id": "flow_abc123"}}

# Response
{
  "status": "success",
  "data": {
    "id": "flow_abc123",
    "name": "Temperature Monitor",
    "status": "running",
    "nodes": [...],
    "connections": [...]
  }
}

Start Flow

Start execution of a stopped flow.

# Request
{"action": "start_flow", "payload": {"flow_id": "flow_abc123"}}

# Response
{
  "status": "success",
  "data": {
    "flow_id": "flow_abc123",
    "execution_id": "exec_xyz789",
    "status": "running"
  }
}

Stop Flow

Stop a running flow.

# Request
{"action": "stop_flow", "payload": {"flow_id": "flow_abc123"}}

# Response
{
  "status": "success",
  "data": {
    "flow_id": "flow_abc123",
    "status": "stopped"
  }
}

Get System Metrics

Query real-time system resource usage.

# Request
{"action": "get_system_metrics", "payload": {}}

# Response
{
  "status": "success",
  "data": {
    "hostname": "edgeflow-pi-001",
    "os": "linux",
    "arch": "arm64",
    "board_model": "Raspberry Pi 4 Model B",
    "uptime": 86400,
    "temperature": 45.5,
    "cpu": {"usage_percent": 23.5, "cores": 4},
    "memory": {
      "total_bytes": 4294967296,
      "used_bytes": 1073741824,
      "percent": 25.0
    },
    "load_avg": {"1min": 0.5, "5min": 0.3, "15min": 0.2}
  }
}

Get GPIO State

Read current GPIO pin states and configurations.

# Request
{"action": "get_gpio_state", "payload": {}}

# Response
{
  "status": "success",
  "data": {
    "pins": {
      "17": {"mode": "output", "value": 1},
      "27": {"mode": "input", "value": 0, "pull": "up"},
      "22": {"mode": "pwm", "duty_cycle": 75}
    }
  }
}

Get Execution History

Retrieve recent flow execution records with timing and error details.

# Request
{"action": "get_executions", "payload": {}}

# Response
{
  "status": "success",
  "data": {
    "executions": [
      {
        "id": "exec_xyz789",
        "flow_id": "flow_abc123",
        "flow_name": "Temperature Monitor",
        "status": "completed",
        "duration": 1234,
        "node_count": 5,
        "completed_nodes": 5,
        "error_nodes": 0
      }
    ]
  }
}

Get Shadow

Retrieve the device's shadow state.

# Request
{"action": "get_shadow", "payload": {}}

# Response
{
  "status": "success",
  "data": {
    "desired": {"log_level": "info"},
    "reported": {"log_level": "debug", "uptime": 86400},
    "delta": {"log_level": "info"}
  }
}

Update Desired State

Push a desired state change to the device's shadow.

# Request
{
  "action": "update_desired",
  "payload": {
    "desired": {
      "log_level": "info",
      "flow_autostart": true
    }
  }
}

# Response
{
  "status": "success",
  "data": {
    "version": 43,
    "delta": {"log_level": "info"}
  }
}

Command Summary

Timeout & Error Handling

• Default command timeout: 30 seconds
• Commands are tracked by unique ID for request-response correlation
• Timed-out commands return an error response automatically
• If the tunnel is disconnected, commands are rejected immediately

# Error response example
{
  "type": "response",
  "id": "cmd_unique_id",
  "status": "error",
  "error": "flow not found: flow_invalid123"
}