{ "asyncapi": "3.1.0", "id": "urn:waraps.api-tasks", "info": { "title": "WARA-PS Tasks MQTT API", "version": "1.0.3", "description": "### Overview\nTask command definitions for the WARA-PS system. Defines channels, operations, and message schemas for Level 2+ tasks, signals, responses, and feedback via MQTT.\n\nAll task commands, signals, responses, and feedback are exchanged on a **single topic** per agent:\n`{AgentBaseTopic}/exec/command` (QoS 1, retain false).\nMessage type is discriminated by payload structure: `command` field for commands/signals, `response` field for responses, `status` field for feedback.\n\n### Task Execution State Machine\n\nThe agent implements a five-state machine that governs how commands are received, validated, planned, executed, and completed. Only **one task may execute at a time**. New commands received while a task is active (running or paused) must be rejected.\n\n#### States\n\n| State | Description |\n|---|---|\n| **idle** | No active task. Agent is ready to receive a `start-task` command. |\n| **validating** | Incoming command is parsed and validated. Task name is checked against `direct_execution_info.tasks-available`. For movement tasks, geopoints are validated. |\n| **planning** | Task execution is being planned. May be a stub for simple agents. |\n| **running** | Task is actively executing. Agent publishes sensor data and accepts signals. |\n| **paused** | Task execution is temporarily suspended by a `$pause` signal. |\n\n#### Transitions\n\n| From | Event | To | Published on `exec/command` |\n|---|---|---|---|\n| idle | `start-task` received | validating | — |\n| validating | command is valid and parseable | planning | response: `running`, feedback: `starting` |\n| validating | command cannot be handled | idle | response: `failed` (Cannot handle command), feedback: `failed` |\n| validating | command is malformed | idle | response: `failed` (Malformed command), feedback: `failed` |\n| planning | plan is ready | running | feedback: `planning` → `running` |\n| planning | plan fails | idle | response: `failed` (Plan failure), feedback: `failed` |\n| running | `$pause` signal | paused | response: `running`, feedback: `paused` |\n| running | `$abort` signal | idle | response: `failed`, feedback: `aborted` |\n| running | `$enough` signal | idle | response: `finished`, feedback: `finished` |\n| running | task completes naturally | idle | response: `finished`, feedback: `finished` |\n| running | task fails during execution | idle | response: `failed`, feedback: `failed` |\n| paused | `$continue` signal | running | response: `running`, feedback: `running` |\n| paused | `$abort` signal | idle | response: `failed`, feedback: `aborted` |\n| paused | `$enough` signal | idle | response: `finished`, feedback: `finished` |\n\n#### State Diagram (Mermaid)\n\n```mermaid\nstateDiagram-v2\n [*] --> idle\n idle --> validating : start-task received\n validating --> planning : valid\\n→ response:running\\n→ feedback:starting\n validating --> idle : invalid / malformed\\n→ response:failed\\n→ feedback:failed\n planning --> running : plan ready\\n→ feedback:running\n planning --> idle : plan failed\\n→ response:failed\\n→ feedback:failed\n running --> paused : $pause\\n→ feedback:paused\n running --> idle : $abort\\n→ feedback:aborted\n running --> idle : $enough / complete\\n→ response:finished\\n→ feedback:finished\n running --> idle : execution error\\n→ response:failed\\n→ feedback:failed\n paused --> running : $continue\\n→ feedback:running\n paused --> idle : $abort\\n→ feedback:aborted\n paused --> idle : $enough\\n→ response:finished\\n→ feedback:finished\n```\n\n### Channels\n- **Move To** — Move the agent to a specific position.\n- **Move Path** — Move the agent along a path of waypoints.\n- **Search Area** — Search a specified area for a target.\n- **Look At Position** — Point the agent camera at a position.\n- **Look At Agent** — Make the agent camera follow another agent.\n- **Follow Lead** — Make the agent follow another agent.\n- **Collect** — Make the agent collect an item.\n- **Release** — Make the agent release all collected items.\n- **Go Home** — Make the agent return to its home position.\n- **Observe Position** — Make the agent observe a position.\n- **Set Speed** — Set the speed of an ongoing task.\n- **Reset Speed** — Reset the speed to default.\n- **Set Geofence** — Set a geofence boundary for the agent.\n- **Reset Geofence** — Remove the active geofence.\n- **Add No-Go Zone** — Add a restricted area for the agent.\n- **Reset No-Go Zones** — Remove all restricted areas.\n- **Set Heading Thrust** — Set heading and thrust directly.\n- **Deliver** — Deliver cargo to a specific position.\n- **Task Response** — Required response from Level 2+ agents when receiving a command.\n- **Task Feedback** — Required feedback from Level 2+ agents during command execution.", "contact": { "name": "waraps.org", "url": "https://portal.waraps.org/", "email": "info@waraps.org" }, "license": { "name": "Apache 2.0", "url": "http://www.apache.org/licenses/LICENSE-2.0.html" }, "x-task-state-machine": { "id": "taskExecution", "initial": "idle", "context": { "topic": "{AgentBaseTopic}/exec/command", "qos": 1, "constraint": "Only one task may execute at a time. New commands are rejected while a task is active (running or paused). After reaching idle the agent is ready for the next command." }, "states": { "idle": { "description": "No active task. Agent is ready to receive commands.", "on": { "RECEIVE_START_TASK": "validating" } }, "validating": { "description": "Parse and validate incoming command. Check that task name is listed in direct_execution_info.tasks-available. For movement tasks, validate geopoint(s) for lat/lon/alt.", "on": { "COMMAND_VALID": { "target": "planning", "actions": [ { "publish": "response", "value": "running" }, { "publish": "feedback", "value": "starting" } ] }, "COMMAND_INVALID": { "target": "idle", "actions": [ { "publish": "response", "value": "failed", "fail-reason": "Cannot handle command" }, { "publish": "feedback", "value": "failed" } ] }, "COMMAND_MALFORMED": { "target": "idle", "actions": [ { "publish": "response", "value": "failed", "fail-reason": "Malformed command" }, { "publish": "feedback", "value": "failed" } ] } } }, "planning": { "description": "Plan task execution. For movement tasks validate the route. May be a stub/placeholder for simple agents. Agents with planning capabilities implement route planning here.", "on": { "PLAN_READY": { "target": "running", "actions": [ { "publish": "feedback", "value": "planning" }, { "publish": "feedback", "value": "running" } ] }, "PLAN_FAILED": { "target": "idle", "actions": [ { "publish": "response", "value": "failed", "fail-reason": "Plan failure" }, { "publish": "feedback", "value": "failed" } ] } } }, "running": { "description": "Task is actively executing. Only one task at a time. Agent publishes sensor data and accepts signals.", "on": { "SIGNAL_PAUSE": { "target": "paused", "actions": [ { "publish": "response", "value": "running" }, { "publish": "feedback", "value": "paused" } ] }, "SIGNAL_ABORT": { "target": "idle", "actions": [ { "publish": "response", "value": "failed" }, { "publish": "feedback", "value": "aborted" } ] }, "SIGNAL_ENOUGH": { "target": "idle", "actions": [ { "publish": "response", "value": "finished" }, { "publish": "feedback", "value": "finished" } ] }, "TASK_COMPLETE": { "target": "idle", "actions": [ { "publish": "response", "value": "finished" }, { "publish": "feedback", "value": "finished" } ] }, "TASK_FAILED": { "target": "idle", "actions": [ { "publish": "response", "value": "failed", "fail-reason": "Execution error" }, { "publish": "feedback", "value": "failed" } ] } } }, "paused": { "description": "Task execution is paused by commander signal.", "on": { "SIGNAL_CONTINUE": { "target": "running", "actions": [ { "publish": "response", "value": "running" }, { "publish": "feedback", "value": "running" } ] }, "SIGNAL_ABORT": { "target": "idle", "actions": [ { "publish": "response", "value": "failed" }, { "publish": "feedback", "value": "aborted" } ] }, "SIGNAL_ENOUGH": { "target": "idle", "actions": [ { "publish": "response", "value": "finished" }, { "publish": "feedback", "value": "finished" } ] } } } } } }, "defaultContentType": "application/json", "servers": { "localhost": { "host": "localhost:1883", "protocol": "mqtt", "protocolVersion": "3.1.1+", "description": "Development MQTT broker", "variables": { "port": { "enum": [ "1882", "1883" ], "default": "1883", "description": "The port used for connecting to the locally hosted MQTT broker" } }, "security": [] }, "production": { "host": "broker.waraps.org:8883", "protocol": "mqtt", "protocolVersion": "3.1.1+", "description": "Production MQTT broker", "variables": { "port": { "enum": [ "8883" ], "default": "8883", "description": "The port used for connecting to the production MQTT broker" } }, "security": [ { "$ref": "#/components/securitySchemes/tls" } ] } }, "channels": { "moveToTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveMoveToTask.message": { "$ref": "#/components/messages/MoveToTaskMessage" } }, "description": "Receives move-to command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "movePathTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveMovePathTask.message": { "$ref": "#/components/messages/MovePathTaskMessage" } }, "description": "Receives move-path command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "searchAreaTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveSearchAreaTask.message": { "$ref": "#/components/messages/SearchAreaTaskMessage" } }, "description": "Receives search-area command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "lookAtPositionTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveLookAtPositionTask.message": { "$ref": "#/components/messages/LookAtPositionTaskMessage" } }, "description": "Receives look-at-position command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "lookAtAgentTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveLookAtAgentTask.message": { "$ref": "#/components/messages/LookAtAgentTaskMessage" } }, "description": "Receives look-at-agent command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "followLeadTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveFollowLeadTask.message": { "$ref": "#/components/messages/FollowLeadTaskMessage" } }, "description": "Receives follow-lead command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "collectTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveCollectTask.message": { "$ref": "#/components/messages/CollectTaskMessage" } }, "description": "Receives collect command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "releaseTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveReleaseTask.message": { "$ref": "#/components/messages/ReleaseTaskMessage" } }, "description": "Receives release command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "goHomeTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveGoHomeTask.message": { "$ref": "#/components/messages/GoHomeTaskMessage" } }, "description": "Receives go-home command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "observePositionTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveObservePositionTask.message": { "$ref": "#/components/messages/ObservePositionTaskMessage" } }, "description": "Receives observe-position command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "setSpeedTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveSetSpeedTask.message": { "$ref": "#/components/messages/SetSpeedTaskMessage" } }, "description": "Receives set-speed command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "resetSpeedTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveResetSpeedTask.message": { "$ref": "#/components/messages/ResetSpeedTaskMessage" } }, "description": "Receives reset-speed command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "setGeofenceTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveSetGeofenceTask.message": { "$ref": "#/components/messages/SetGeofenceTaskMessage" } }, "description": "Receives set-geofence command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "resetGeofenceTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveResetGeofenceTask.message": { "$ref": "#/components/messages/ResetGeofenceTaskMessage" } }, "description": "Receives reset-geofence command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "addNoGoZoneTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveAddNoGoZoneTask.message": { "$ref": "#/components/messages/AddNoGoZoneTaskMessage" } }, "description": "Receives add-no-go-zone command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "resetNoGoZonesTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveResetNoGoZonesTask.message": { "$ref": "#/components/messages/ResetNoGoZonesTaskMessage" } }, "description": "Receives reset-no-go-zones command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "setHeadingThrustTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveSetHeadingThrustTask.message": { "$ref": "#/components/messages/SetHeadingThrustTaskMessage" } }, "description": "Receives set-heading-thrust command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "deliverTaskChannel": { "address": "{AgentBaseTopic}/exec/command", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "receiveDeliverTask.message": { "$ref": "#/components/messages/DeliverTaskMessage" } }, "description": "Receives deliver command.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "taskResponseChannel": { "address": "{AgentBaseTopic}/exec/response", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "SendTaskResponse.message": { "$ref": "#/components/messages/TaskResponseMessage" } }, "description": "Sends command response. Required response from Level 2+ agents.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "taskFeedbackChannel": { "address": "{AgentBaseTopic}/exec/feedback", "bindings": { "$ref": "#/components/channelBindings/TaskMqttSettings" }, "messages": { "SendTaskFeedback.message": { "$ref": "#/components/messages/TaskFeedbackMessage" } }, "description": "Sends feedback during command execution. Required feedback from Level 2+ agents.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "abortSignalChannel": { "address": "{AgentBaseTopic}/exec/command", "messages": { "receiveAbortSignal.message": { "$ref": "#/components/messages/SignalMessage" } }, "description": "Receives abort signal.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "pauseSignalChannel": { "address": "{AgentBaseTopic}/exec/command", "messages": { "receivePauseSignal.message": { "$ref": "#/components/messages/SignalMessage" } }, "description": "Receives pause signal.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "continueSignalChannel": { "address": "{AgentBaseTopic}/exec/command", "messages": { "receiveContinueSignal.message": { "$ref": "#/components/messages/SignalMessage" } }, "description": "Receives continue signal.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } }, "enoughSignalChannel": { "address": "{AgentBaseTopic}/exec/command", "messages": { "receiveEnoughSignal.message": { "$ref": "#/components/messages/SignalMessage" } }, "description": "Receives enough signal.", "parameters": { "AgentBaseTopic": { "$ref": "#/components/parameters/AgentBaseTopic" } } } }, "operations": { "receiveMoveToTask": { "action": "receive", "channel": { "$ref": "#/channels/moveToTaskChannel" }, "summary": "Receives move-to command", "messages": [ { "$ref": "#/channels/moveToTaskChannel/messages/receiveMoveToTask.message" } ] }, "receiveMovePathTask": { "action": "receive", "channel": { "$ref": "#/channels/movePathTaskChannel" }, "summary": "Receives move-path command", "messages": [ { "$ref": "#/channels/movePathTaskChannel/messages/receiveMovePathTask.message" } ] }, "receiveSearchAreaTask": { "action": "receive", "channel": { "$ref": "#/channels/searchAreaTaskChannel" }, "summary": "Receives search-area command", "messages": [ { "$ref": "#/channels/searchAreaTaskChannel/messages/receiveSearchAreaTask.message" } ] }, "receiveLookAtPositionTask": { "action": "receive", "channel": { "$ref": "#/channels/lookAtPositionTaskChannel" }, "summary": "Receives look-at-position command", "messages": [ { "$ref": "#/channels/lookAtPositionTaskChannel/messages/receiveLookAtPositionTask.message" } ] }, "receiveLookAtAgentTask": { "action": "receive", "channel": { "$ref": "#/channels/lookAtAgentTaskChannel" }, "summary": "Receives look-at-agent command", "messages": [ { "$ref": "#/channels/lookAtAgentTaskChannel/messages/receiveLookAtAgentTask.message" } ] }, "receiveFollowLeadTask": { "action": "receive", "channel": { "$ref": "#/channels/followLeadTaskChannel" }, "summary": "Receives follow-lead command", "messages": [ { "$ref": "#/channels/followLeadTaskChannel/messages/receiveFollowLeadTask.message" } ] }, "receiveCollectTask": { "action": "receive", "channel": { "$ref": "#/channels/collectTaskChannel" }, "summary": "Receives collect command", "messages": [ { "$ref": "#/channels/collectTaskChannel/messages/receiveCollectTask.message" } ] }, "receiveReleaseTask": { "action": "receive", "channel": { "$ref": "#/channels/releaseTaskChannel" }, "summary": "Receives release command", "messages": [ { "$ref": "#/channels/releaseTaskChannel/messages/receiveReleaseTask.message" } ] }, "receiveGoHomeTask": { "action": "receive", "channel": { "$ref": "#/channels/goHomeTaskChannel" }, "summary": "Receives go-home command", "messages": [ { "$ref": "#/channels/goHomeTaskChannel/messages/receiveGoHomeTask.message" } ] }, "receiveObservePositionTask": { "action": "receive", "channel": { "$ref": "#/channels/observePositionTaskChannel" }, "summary": "Receives observe-position command", "messages": [ { "$ref": "#/channels/observePositionTaskChannel/messages/receiveObservePositionTask.message" } ] }, "receiveSetSpeedTask": { "action": "receive", "channel": { "$ref": "#/channels/setSpeedTaskChannel" }, "summary": "Receives set-speed command", "messages": [ { "$ref": "#/channels/setSpeedTaskChannel/messages/receiveSetSpeedTask.message" } ] }, "receiveResetSpeedTask": { "action": "receive", "channel": { "$ref": "#/channels/resetSpeedTaskChannel" }, "summary": "Receives reset-speed command", "messages": [ { "$ref": "#/channels/resetSpeedTaskChannel/messages/receiveResetSpeedTask.message" } ] }, "receiveSetGeofenceTask": { "action": "receive", "channel": { "$ref": "#/channels/setGeofenceTaskChannel" }, "summary": "Receives set-geofence command", "messages": [ { "$ref": "#/channels/setGeofenceTaskChannel/messages/receiveSetGeofenceTask.message" } ] }, "receiveResetGeofenceTask": { "action": "receive", "channel": { "$ref": "#/channels/resetGeofenceTaskChannel" }, "summary": "Receives reset-geofence command", "messages": [ { "$ref": "#/channels/resetGeofenceTaskChannel/messages/receiveResetGeofenceTask.message" } ] }, "receiveAddNoGoZoneTask": { "action": "receive", "channel": { "$ref": "#/channels/addNoGoZoneTaskChannel" }, "summary": "Receives add-no-go-zone command", "messages": [ { "$ref": "#/channels/addNoGoZoneTaskChannel/messages/receiveAddNoGoZoneTask.message" } ] }, "receiveResetNoGoZonesTask": { "action": "receive", "channel": { "$ref": "#/channels/resetNoGoZonesTaskChannel" }, "summary": "Receives reset-no-go-zones command", "messages": [ { "$ref": "#/channels/resetNoGoZonesTaskChannel/messages/receiveResetNoGoZonesTask.message" } ] }, "receiveSetHeadingThrustTask": { "action": "receive", "channel": { "$ref": "#/channels/setHeadingThrustTaskChannel" }, "summary": "Receives set-heading-thrust command", "messages": [ { "$ref": "#/channels/setHeadingThrustTaskChannel/messages/receiveSetHeadingThrustTask.message" } ] }, "receiveDeliverTask": { "action": "receive", "channel": { "$ref": "#/channels/deliverTaskChannel" }, "summary": "Receives deliver command", "messages": [ { "$ref": "#/channels/deliverTaskChannel/messages/receiveDeliverTask.message" } ] }, "SendTaskResponse": { "action": "send", "channel": { "$ref": "#/channels/taskResponseChannel" }, "summary": "Sends command response", "messages": [ { "$ref": "#/channels/taskResponseChannel/messages/SendTaskResponse.message" } ] }, "SendTaskFeedback": { "action": "send", "channel": { "$ref": "#/channels/taskFeedbackChannel" }, "summary": "Sends command execution feedback", "messages": [ { "$ref": "#/channels/taskFeedbackChannel/messages/SendTaskFeedback.message" } ] }, "receiveAbortSignal": { "action": "receive", "channel": { "$ref": "#/channels/abortSignalChannel" }, "summary": "Receives abort signal to terminate task execution", "messages": [ { "$ref": "#/channels/abortSignalChannel/messages/receiveAbortSignal.message" } ] }, "receivePauseSignal": { "action": "receive", "channel": { "$ref": "#/channels/pauseSignalChannel" }, "summary": "Receives pause signal to halt task execution", "messages": [ { "$ref": "#/channels/pauseSignalChannel/messages/receivePauseSignal.message" } ] }, "receiveContinueSignal": { "action": "receive", "channel": { "$ref": "#/channels/continueSignalChannel" }, "summary": "Receives continue signal to resume paused task", "messages": [ { "$ref": "#/channels/continueSignalChannel/messages/receiveContinueSignal.message" } ] }, "receiveEnoughSignal": { "action": "receive", "channel": { "$ref": "#/channels/enoughSignalChannel" }, "summary": "Receives enough signal to conclude task execution", "messages": [ { "$ref": "#/channels/enoughSignalChannel/messages/receiveEnoughSignal.message" } ] } }, "components": { "channelBindings": { "TaskMqttSettings": { "mqtt": { "qos": 1, "retain": false } } }, "securitySchemes": { "tls": { "type": "X509", "x-securityScheme": "tls", "description": "TLS client certificate for secure connection" }, "apiKeyAuth": { "type": "apiKey", "in": "user", "description": "An API key is required for connecting to the MQTT broker" } }, "parameters": { "AgentBaseTopic": { "description": "Full agent topic path: {organization}/{category}/{domain}/{real_sim}/{agent_name}. See AgentBaseTopic schema for structure.", "location": "$message.payload#/name" } }, "schemas": { "AgentBaseTopic": { "description": "Base topic string composed of organization, category, domain, real_sim, agent_name", "type": "string", "properties": { "organization": { "enum": [ "waraps", "saab", "liu" ] }, "category": { "enum": [ "unit", "service", "general" ] }, "domain": { "enum": [ "air", "ground", "surface", "subsurface", "space", "virtual" ] }, "real_sim": { "enum": [ "real", "simulation" ] }, "agent_name": { "type": "string" } }, "required": [ "organization", "category", "domain", "real_sim", "agent_name" ], "example": "waraps/sensor/surface/simulation/SimUSV1", "pattern": "{organization}/{category}/{domain}/{real_sim}/{agent_name}" }, "StartTaskBase": { "type": "object", "description": "Common envelope for commands using the start-task pattern.", "properties": { "com-uuid": { "$ref": "#/components/schemas/ComUUID" }, "task-uuid": { "$ref": "#/components/schemas/TaskUUID" }, "command": { "type": "string", "const": "start-task", "example": "start-task" }, "execution-unit": { "type": "string", "description": "Name of unit/agent", "example": "MiniUAV1" }, "sender": { "$ref": "#/components/schemas/Commander" } }, "required": [ "com-uuid", "command", "execution-unit", "sender", "task-uuid" ] }, "MoveToPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/MoveToTaskBody" } ] }, "MovePathPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/MovePathTaskBody" } ] }, "SearchAreaPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/SearchAreaTaskBody" } ] }, "LookAtPositionPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/LookAtPositionTaskBody" } ] }, "LookAtAgentPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/LookAtAgentTaskBody" } ] }, "FollowLeadPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/FollowLeadTaskBody" } ] }, "CollectPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/CollectTaskBody" } ] }, "ReleasePayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/ReleaseTaskBody" } ] }, "GoHomePayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/GoHomeTaskBody" } ] }, "ObservePositionPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/ObservePositionTaskBody" } ] }, "SetSpeedPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/SetSpeedTaskBody" } ] }, "ResetSpeedPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/ResetSpeedTaskBody" } ] }, "SetGeofencePayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/SetGeofenceTaskBody" } ] }, "ResetGeofencePayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/ResetGeofenceTaskBody" } ] }, "AddNoGoZonePayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/AddNoGoZoneTaskBody" } ] }, "ResetNoGoZonesPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/ResetNoGoZonesTaskBody" } ] }, "SetHeadingThrustPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/SetHeadingThrustTaskBody" } ] }, "DeliverPayload": { "allOf": [ { "$ref": "#/components/schemas/StartTaskBase" }, { "$ref": "#/components/schemas/DeliverTaskBody" } ] }, "TaskResponsePayload": { "type": "object", "properties": { "agent-uuid": { "$ref": "#/components/schemas/AgentUUID" }, "com-uuid": { "$ref": "#/components/schemas/ComUUID" }, "response": { "$ref": "#/components/schemas/TaskResponse" }, "fail-reason": { "type": "string", "example": "Execution failed ..." }, "response-to": { "$ref": "#/components/schemas/ComUUID" }, "task-uuid": { "$ref": "#/components/schemas/TaskUUID" } }, "required": [ "agent-uuid", "com-uuid", "response", "response-to", "task-uuid" ] }, "TaskFeedbackPayload": { "type": "object", "properties": { "agent-uuid": { "$ref": "#/components/schemas/AgentUUID" }, "com-uuid": { "$ref": "#/components/schemas/ComUUID" }, "status": { "$ref": "#/components/schemas/TaskFeedback" }, "task-uuid": { "$ref": "#/components/schemas/TaskUUID" } }, "required": [ "agent-uuid", "com-uuid", "status", "task-uuid" ] }, "TaskSignalPayload": { "type": "object", "properties": { "com-uuid": { "$ref": "#/components/schemas/ComUUID" }, "command": { "type": "string", "const": "signal-task", "example": "signal-task" }, "signal": { "$ref": "#/components/schemas/AvailableSignals" }, "sender": { "$ref": "#/components/schemas/Commander" }, "task-uuid": { "$ref": "#/components/schemas/TaskUUID" } }, "required": [ "com-uuid", "command", "signal", "sender", "task-uuid" ] }, "MoveToTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "move-to", "example": "move-to" }, "meta": { "type": "object", "description": "Optional metadata for the task", "properties": { "reference": { "type": "string", "description": "Reference identifier for the task", "example": "waypoint-1" } }, "additionalProperties": true }, "params": { "type": "object", "properties": { "waypoint": { "$ref": "#/components/schemas/GeoPoint" }, "speed": { "$ref": "#/components/schemas/SpeedString" }, "loop": { "type": "integer", "description": "Optional loop parameter for repeating the movement", "example": 0 } }, "required": [ "waypoint", "speed" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "MovePathTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "move-path", "example": "move-path" }, "meta": { "type": "object", "description": "Optional metadata for the task", "properties": { "reference": { "type": "string", "description": "Reference identifier for the task", "example": "scaleout2-R" } }, "additionalProperties": true }, "params": { "type": "object", "properties": { "waypoints": { "$ref": "#/components/schemas/GeoPoints" }, "speed": { "$ref": "#/components/schemas/SpeedString" }, "loop": { "type": "integer", "description": "Optional loop parameter for repeating the path", "example": 0 } }, "required": [ "waypoints", "speed" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "SearchAreaTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "search-area", "example": "search-area" }, "meta": { "type": "object", "description": "Optional metadata for the task", "properties": { "reference": { "type": "string", "description": "Reference identifier for the task", "example": "search-area-1" } }, "additionalProperties": true }, "params": { "type": "object", "properties": { "area": { "$ref": "#/components/schemas/GeoPoints" }, "speed": { "$ref": "#/components/schemas/SpeedString" }, "target-type": { "$ref": "#/components/schemas/TargetType" }, "target-size": { "$ref": "#/components/schemas/TargetSize" }, "loop": { "type": "integer", "description": "Optional loop parameter for repeating the search pattern", "example": 0 } }, "required": [ "area", "speed", "target-type", "target-size" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "LookAtPositionTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "look-at-position", "example": "look-at-position" }, "meta": { "type": "object", "description": "Optional metadata for the task", "properties": { "reference": { "type": "string", "description": "Reference identifier for the task", "example": "my_look_at_point_1" } }, "additionalProperties": true }, "params": { "type": "object", "properties": { "geopoint": { "$ref": "#/components/schemas/GeoPoint" } }, "required": [ "geopoint" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "LookAtAgentTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "look-at-agent", "example": "look-at-agent" }, "meta": { "type": "object", "description": "Optional metadata for the task", "properties": { "reference": { "type": "string", "description": "Reference identifier for the task", "example": "MiniUSV1" } }, "additionalProperties": true } }, "required": [ "name" ] } }, "required": [ "task" ] }, "FollowLeadTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "follow-lead", "example": "follow-lead" }, "meta": { "type": "object", "description": "Optional metadata for the task", "properties": { "reference": { "type": "string", "description": "Reference identifier for the task", "example": "MiniUSV1" } }, "additionalProperties": true }, "params": { "type": "object", "properties": { "speed": { "$ref": "#/components/schemas/SpeedString" } }, "required": [ "speed" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "CollectTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "collect", "example": "collect" }, "params": { "type": "object", "properties": { "cargo": { "type": "string", "example": "medicin" } }, "required": [ "cargo" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "ReleaseTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "release", "example": "release" } }, "required": [ "name" ] } }, "required": [ "task" ] }, "GoHomeTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "go-home", "example": "go-home" }, "params": { "type": "object", "properties": { "speed": { "$ref": "#/components/schemas/SpeedString" } }, "required": [ "speed" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "ObservePositionTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "observe-position", "example": "observe-position" }, "params": { "type": "object", "properties": { "distance": { "type": "number", "example": 10 }, "duration": { "type": "integer", "example": 20 }, "geopoint": { "$ref": "#/components/schemas/GeoPoint" }, "height": { "type": "number", "example": -1 }, "speed": { "type": "array", "items": { "$ref": "#/components/schemas/SpeedFloat" } } }, "required": [ "distance", "duration", "geopoint", "height", "speed" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "SetSpeedTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "set-speed", "example": "set-speed" }, "params": { "type": "object", "properties": { "speed": { "$ref": "#/components/schemas/SpeedString" } }, "required": [ "speed" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "ResetSpeedTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "reset-speed", "example": "reset-speed" } }, "required": [ "name" ] } }, "required": [ "task" ] }, "SetGeofenceTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "set-geofence", "example": "set-geofence" }, "params": { "type": "object", "properties": { "area": { "$ref": "#/components/schemas/GeoPoints" } }, "required": [ "area" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "ResetGeofenceTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "reset-geofence", "example": "reset-geofence" } }, "required": [ "name" ] } }, "required": [ "task" ] }, "AddNoGoZoneTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "add-no-go-zone", "example": "add-no-go-zone" }, "meta": { "type": "object", "additionalProperties": true }, "params": { "type": "object", "properties": { "area": { "$ref": "#/components/schemas/GeoPoints" } }, "required": [ "area" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "ResetNoGoZonesTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "reset-no-go-zones", "example": "reset-no-go-zones" } }, "required": [ "name" ] } }, "required": [ "task" ] }, "SetHeadingThrustTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "set-heading-thrust", "example": "set-heading-thrust" }, "params": { "type": "object", "properties": { "heading": { "$ref": "#/components/schemas/HeadingSensor" }, "thrust": { "$ref": "#/components/schemas/SpeedPercent" } }, "required": [ "heading", "thrust" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "DeliverTaskBody": { "type": "object", "properties": { "task": { "type": "object", "properties": { "name": { "type": "string", "const": "deliver", "example": "deliver" }, "meta": { "type": "object", "description": "Optional metadata for the task", "properties": { "reference": { "type": "string", "example": "delivery-route-1" } }, "additionalProperties": true }, "params": { "type": "object", "properties": { "waypoints": { "$ref": "#/components/schemas/GeoPoints" }, "speed": { "$ref": "#/components/schemas/SpeedString" }, "cargo": { "type": "string" } }, "required": [ "waypoints", "speed", "cargo" ] } }, "required": [ "name", "params" ] } }, "required": [ "task" ] }, "AgentUUID": { "type": "string", "description": "Agent UUID that is unique for each agent. Should be reused between sessions.", "format": "uuid" }, "ComUUID": { "type": "string", "description": "Command UUID that is unique for each sent command or signal. Used for tracing feedback and response to its command.", "format": "uuid" }, "TaskUUID": { "type": "string", "description": "Task UUID that is unique for each sent task. Used for connecting signals($abort, $pause, ...) to its task.", "format": "uuid" }, "Commander": { "description": "Name/Identification of the command instance.", "type": "string", "example": "commander" }, "SpeedString": { "type": "string", "enum": [ "slow", "standard", "fast" ], "example": "standard", "description": "Fast = 100%, standard = 75% and slow = 50% of max speed over ground (SOG) for vehicle/vessel." }, "SpeedFloat": { "type": "number", "example": 10.5, "description": "Speed over ground (SOG) in meters per second (mps)", "format": "float" }, "SpeedPercent": { "type": "number", "example": 40, "description": "Speed over ground (SOG) percentage of max speed for agent.", "format": "float" }, "TargetType": { "type": "string", "enum": [ "person", "car", "boat", "etc." ], "description": "The object class we are searching for.", "example": "person" }, "TargetSize": { "type": "number", "example": 1.8, "description": "Size of the target in meters.", "format": "float" }, "TaskResponse": { "type": "string", "description": "Response to the sent command.", "enum": [ "running", "failed", "finished" ], "example": "running" }, "TaskFeedback": { "type": "string", "description": "Task process information.", "enum": [ "starting", "planning", "running", "paused", "finished", "failed", "aborted" ], "example": "running" }, "AvailableSignals": { "type": "string", "enum": [ "$abort", "$enough", "$pause", "$continue" ], "example": "$abort" }, "GeoPoint": { "type": "object", "properties": { "latitude": { "$ref": "#/components/schemas/Latitude" }, "longitude": { "$ref": "#/components/schemas/Longitude" }, "altitude": { "$ref": "#/components/schemas/Altitude" }, "rostype": { "type": "string", "description": "Optional ROS message type identifier", "example": "GeoPoint" } }, "required": [ "latitude", "longitude", "altitude" ] }, "GeoPoints": { "type": "array", "minItems": 2, "description": "An array of WGS84 formatted objects including latitude, longitude and altitude.", "items": { "$ref": "#/components/schemas/GeoPoint" } }, "HeadingSensor": { "type": "number", "example": 137.2, "description": "Heading (deg) in relation to north." }, "Latitude": { "type": "number", "description": "WGS84 latitude, seven or more decimals for centimeter precision.", "example": 57.7611363, "format": "float" }, "Longitude": { "type": "number", "description": "WGS84 longitude, seven or more decimals for centimeter precision.", "example": 16.6805011, "format": "float" }, "Altitude": { "type": "number", "description": "WGS84 altitude, meters with centimeter precision in relation to ellipsoid.", "example": 47.81, "format": "float" } }, "messages": { "MoveToTaskMessage": { "name": "move-to", "description": "Command to move the agent to a specific position.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/MoveToPayload" } }, "MovePathTaskMessage": { "name": "move-path", "description": "Command to move the agent along a path.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/MovePathPayload" } }, "SearchAreaTaskMessage": { "name": "search-area", "description": "Command to search a specified area for a specific target and size.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/SearchAreaPayload" } }, "LookAtPositionTaskMessage": { "name": "look-at-position", "description": "Command to make the agent look at a specific position.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/LookAtPositionPayload" } }, "LookAtAgentTaskMessage": { "name": "look-at-agent", "description": "Command to make the agent's camera follow another agent.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/LookAtAgentPayload" } }, "FollowLeadTaskMessage": { "name": "follow-lead", "description": "Command to make the agent follow another agent.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/FollowLeadPayload" } }, "CollectTaskMessage": { "name": "collect", "description": "Command to make the agent collect/grab an item.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/CollectPayload" } }, "ReleaseTaskMessage": { "name": "release", "description": "Command to make the agent release all collected items.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/ReleasePayload" } }, "GoHomeTaskMessage": { "name": "go-home", "description": "Command to make the agent return to its home position.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/GoHomePayload" } }, "ObservePositionTaskMessage": { "name": "observe-position", "description": "Command to make the agent observe a position.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/ObservePositionPayload" } }, "SetSpeedTaskMessage": { "name": "set-speed", "description": "Command to set the speed of an ongoing task.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/SetSpeedPayload" } }, "ResetSpeedTaskMessage": { "name": "reset-speed", "description": "Command to reset the speed of an ongoing task.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/ResetSpeedPayload" } }, "SetGeofenceTaskMessage": { "name": "set-geofence", "description": "Command to set a geofence for the agent.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/SetGeofencePayload" } }, "ResetGeofenceTaskMessage": { "name": "reset-geofence", "description": "Command to remove the active geofence.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/ResetGeofencePayload" } }, "AddNoGoZoneTaskMessage": { "name": "add-no-go-zone", "description": "Command to add a no-go-zone for the agent.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/AddNoGoZonePayload" } }, "ResetNoGoZonesTaskMessage": { "name": "reset-no-go-zones", "description": "Command to remove all active no-go-zones.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/ResetNoGoZonesPayload" } }, "SetHeadingThrustTaskMessage": { "name": "set-heading-thrust", "description": "Command to set heading and thrust for an agent.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/SetHeadingThrustPayload" } }, "DeliverTaskMessage": { "name": "deliver", "description": "Command to deliver cargo to a specific position along a path.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/DeliverPayload" } }, "TaskResponseMessage": { "name": "response", "description": "Response message from an agent.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/TaskResponsePayload" } }, "TaskFeedbackMessage": { "name": "feedback", "description": "Feedback message on the status of a task.", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/TaskFeedbackPayload" } }, "SignalMessage": { "name": "task-signal", "description": "Message to send a control signal to an executing task (e.g., abort, pause, continue).", "contentType": "application/json", "payload": { "$ref": "#/components/schemas/TaskSignalPayload" } } } } }