Unified Control API

Defines a canonical set of vehicle-agnostic commands that abstract away manufacturer-specific protocols. Instead of sending a proprietary 'move' string to an AGV and a different ROS 2 action to an AMR, the API exposes a single navigate_to_pose command.

• Action Primitives: Common commands include move_to, dock_to, charge_at, lift, and pause.
• Parameterization: Commands are parameterized with standard units (e.g., meters, radians per second) and coordinate frames.
• Protocol Buffers/JSON: Payloads are typically serialized using language-neutral formats like Protobuf for strong typing and efficiency.

Normalizes disparate data streams from every agent into a single, coherent digital twin representation. Regardless of whether an agent reports its battery as 'State of Charge' or 'Voltage', the API exposes a canonical battery_percentage field.

• Canonical State Machine: Every agent is mapped to a finite set of states: IDLE, EXECUTING, CHARGING, ERROR, OFFLINE.
• Standardized Pose: Position is always reported as {x, y, theta} in a defined global coordinate frame.
• Diagnostic Aggregation: Error codes from different manufacturers are mapped to a common severity hierarchy (INFO, WARN, FATAL).

The API is not a direct translator; it sits atop a Hardware Abstraction Layer (HAL). The HAL translates the API's generic navigate_to_pose command into the specific electrical and software signals required by a particular drive train and navigation stack.

• Decoupling: This allows the orchestration logic to be completely decoupled from hardware evolution.
• Driver Model: Each agent type requires a thin Agent Driver that implements the HAL interface, translating generic commands to proprietary protocols (e.g., VDA 5050, MQTT, ROS 2).
• Sensor Normalization: Raw sensor data (lidar, depth cameras) is abstracted into standardized obstacle lists or occupancy grids.

Relies on asynchronous communication to handle the inherent latency and unpredictability of physical robots. The API uses command queuing and publish-subscribe patterns rather than synchronous request-reply.

• Command Queues: Commands are dispatched to a per-agent queue, allowing the agent to receive its next task while still executing the current one.
• Event Streaming: Telemetry is streamed as a continuous flow of immutable events via a Message Bus (e.g., Kafka, NATS), enabling real-time monitoring and event sourcing.
• Idempotency: Commands carry unique Idempotency Keys to ensure that retried commands due to network glitches are executed exactly once.

The API provides endpoints for agents to self-register and advertise their specific capabilities, a process known as Capability Discovery. This allows the orchestrator to dynamically understand which agents can perform which tasks.

• Agent Registry: A central database stores the capabilities of each agent, such as max_payload_kg, fork_type, or supports_conveyor_docking.
• Semantic Matching: The task planner queries the registry to find agents whose capabilities match the requirements of a decomposed task.
• Dynamic Updates: An agent can update its capabilities in real-time, for example, reporting a reduced payload capacity due to a mechanical fault.

The API acts as a Policy Enforcement Point, ensuring that no command violates operational, safety, or business rules. A Policy Engine evaluates every command against a set of declarative rules before it is dispatched.

• Geofencing: Commands that would route an agent into a restricted zone are automatically rejected.
• Speed Limits: The API can override a requested velocity to enforce zone-specific speed limits.
• Maintenance Windows: Commands can be blocked for agents that have exceeded a service interval, forcing them to a charging or maintenance area.