{
  "feature": "remote-device-commands",
  "version": "1.0.0",
  "description": "Send control commands from the platform to GPS tracking hardware using the device's native protocol channel or SMS fallback, supporting engine control, configuration, alarm management, and informat...",
  "category": "integration",
  "tags": [
    "gps",
    "tracking",
    "commands",
    "remote-control",
    "fleet",
    "iot"
  ],
  "actors": [
    {
      "id": "fleet_operator",
      "name": "Fleet Operator",
      "type": "human",
      "description": "Initiates commands to devices through the platform interface"
    },
    {
      "id": "platform",
      "name": "Tracking Platform",
      "type": "system",
      "description": "Validates, routes, and delivers commands to devices; queues when device is offline"
    },
    {
      "id": "device",
      "name": "GPS Device",
      "type": "external",
      "description": "Receives and executes commands, acknowledges via subsequent position or dedicated response"
    }
  ],
  "fields": [
    {
      "name": "device_id",
      "type": "hidden",
      "required": true,
      "label": "Target device for the command"
    },
    {
      "name": "type",
      "type": "select",
      "required": true,
      "label": "Command type identifier. Common types: engine_stop, engine_resume, reboot_device, power_off, fact..."
    },
    {
      "name": "text_channel",
      "type": "boolean",
      "required": false,
      "label": "When true, command is sent via SMS rather than the data channel; requires device phone number"
    },
    {
      "name": "description",
      "type": "text",
      "required": false,
      "label": "Human-readable label for this saved command"
    },
    {
      "name": "attributes",
      "type": "json",
      "required": false,
      "label": "Command-specific parameters. Common keys: frequency (reporting interval in seconds), timezone, de..."
    }
  ],
  "rules": {
    "access": {
      "permission_required": "Commands can only be sent to devices the requesting user has permission to manage",
      "limit_commands_restriction": "Users with the limitCommands restriction cannot send commands"
    },
    "validation": {
      "protocol_support_check": "The platform checks whether the device's current protocol supports the requested command type; unsupported commands are rejected before delivery",
      "text_channel_requires_phone": "Commands sent via the text channel require the device to have a phone number configured"
    },
    "processing": {
      "offline_queuing": "When a device is offline (no active TCP connection) and text_channel is false, the command is queued and delivered when the device next connects",
      "custom_commands_always_accepted": "Custom commands (type = custom) are always accepted regardless of protocol capability declarations",
      "engine_control_confirmation": "engine_stop and engine_resume require extra authorisation and must be confirmed before execution",
      "saved_commands": "Saved commands (stored with description) can be recalled and re-sent without re-entering parameters"
    }
  },
  "outcomes": {
    "command_sent": {
      "priority": 10,
      "given": [
        "fleet_operator selects command type and target device",
        "user has permission to manage the device",
        "user does not have limitCommands restriction",
        "device protocol supports the command type or type is custom",
        "device is online on the data channel or text_channel is true"
      ],
      "then": [
        {
          "action": "emit_event",
          "event": "command.sent",
          "payload": [
            "device_id",
            "command_type",
            "channel",
            "sent_at"
          ]
        }
      ],
      "result": "Command is dispatched to the device and acknowledged or executed asynchronously"
    },
    "command_queued": {
      "priority": 8,
      "given": [
        "device is currently offline",
        "text_channel is false",
        "user has permission and command type is supported"
      ],
      "then": [
        {
          "action": "create_record",
          "target": "queued_command",
          "description": "Command stored for deferred delivery",
          "type": "queued_command"
        },
        {
          "action": "emit_event",
          "event": "command.queued",
          "payload": [
            "device_id",
            "command_type",
            "queued_at"
          ]
        }
      ],
      "result": "Command stored in queue; delivered automatically when device reconnects"
    },
    "unsupported_command": {
      "priority": 3,
      "error": "COMMAND_UNSUPPORTED_BY_PROTOCOL",
      "given": [
        "device protocol does not support the requested command type",
        "command type is not custom"
      ],
      "then": [],
      "result": "Command is rejected; operator is informed that the device does not support this command"
    },
    "permission_denied": {
      "priority": 2,
      "error": "COMMAND_PERMISSION_DENIED",
      "given": [
        {
          "any": [
            "user does not have access to the target device",
            "user has the limitCommands restriction"
          ]
        }
      ],
      "then": [],
      "result": "Command is rejected; no information about the device is disclosed"
    }
  },
  "errors": [
    {
      "code": "COMMAND_UNSUPPORTED_BY_PROTOCOL",
      "message": "The target device does not support this command type",
      "status": 404
    },
    {
      "code": "COMMAND_PERMISSION_DENIED",
      "message": "You do not have permission to send commands to this device",
      "status": 403
    },
    {
      "code": "COMMAND_DEVICE_NOT_FOUND",
      "message": "The specified device does not exist",
      "status": 404
    }
  ],
  "events": [
    {
      "name": "command.sent",
      "description": "A command was dispatched to a device",
      "payload": [
        "device_id",
        "command_type",
        "channel",
        "sent_at",
        "operator_id"
      ]
    },
    {
      "name": "command.queued",
      "description": "A command was queued for offline delivery",
      "payload": [
        "device_id",
        "command_type",
        "queued_at"
      ]
    },
    {
      "name": "command.delivered",
      "description": "A queued command was delivered upon device reconnection",
      "payload": [
        "device_id",
        "command_type",
        "delivered_at"
      ]
    }
  ],
  "related": [
    {
      "feature": "gps-device-registration",
      "type": "required",
      "reason": "Devices must be registered to receive commands"
    },
    {
      "feature": "fleet-device-sharing",
      "type": "required",
      "reason": "Permission model controls who can send commands"
    }
  ],
  "agi": {
    "goals": [
      {
        "id": "reliable_remote_device_commands",
        "description": "Send control commands from the platform to GPS tracking hardware using the device's native protocol channel or SMS fallback, supporting engine control, configuration, alarm management, and informat...",
        "success_metrics": [
          {
            "metric": "success_rate",
            "target": ">= 99.5%",
            "measurement": "Successful operations divided by total attempts"
          },
          {
            "metric": "error_recovery_rate",
            "target": ">= 95%",
            "measurement": "Errors that auto-recover without manual intervention"
          }
        ],
        "constraints": [
          {
            "type": "availability",
            "description": "Must degrade gracefully when dependencies are unavailable",
            "negotiable": false
          }
        ]
      }
    ],
    "autonomy": {
      "level": "supervised",
      "human_checkpoints": [
        "before making irreversible changes"
      ],
      "escalation_triggers": [
        "error_rate > 5"
      ]
    },
    "safety": {
      "action_permissions": [
        {
          "action": "command_sent",
          "permission": "autonomous"
        },
        {
          "action": "command_queued",
          "permission": "autonomous"
        },
        {
          "action": "unsupported_command",
          "permission": "autonomous"
        },
        {
          "action": "permission_denied",
          "permission": "autonomous"
        }
      ]
    },
    "tradeoffs": [
      {
        "prefer": "reliability",
        "over": "throughput",
        "reason": "integration failures can cascade across systems"
      }
    ],
    "coordination": {
      "protocol": "orchestrated",
      "consumes": [
        {
          "capability": "gps_device_registration",
          "from": "gps-device-registration",
          "fallback": "degrade"
        },
        {
          "capability": "fleet_device_sharing",
          "from": "fleet-device-sharing",
          "fallback": "degrade"
        }
      ]
    }
  },
  "extensions": {
    "source": {
      "repo": "https://github.com/traccar/traccar",
      "project": "Traccar GPS Tracking Server",
      "tech_stack": "Java 17, Netty",
      "files_traced": 10,
      "entry_points": [
        "src/main/java/org/traccar/model/Command.java",
        "src/main/java/org/traccar/api/resource/CommandResource.java",
        "src/main/java/org/traccar/command/CommandSenderManager.java"
      ]
    }
  }
}