Agent event bus

The agent’s plugin host runs an event bus. The host publishes vehicle and lifecycle events on it, and plugins publish their own events. This page covers the agent-side bus. For the methods a GCS half calls on Mission Control, see GCS bridge methods.

Published topics

These are the topics the host itself publishes:

Topic	How a plugin receives it
`vehicle.armed`, `vehicle.disarmed`, `vehicle.mode_changed`, `vehicle.battery_low`, `vehicle.geofence_breach`	`ctx.events.subscribe` with `event.subscribe`. Derived from the flight controller’s own MAVLink stream.
`agent.ready`, `agent.shutdown`	`ctx.events.subscribe` with `event.subscribe`.
`telemetry.state`	The `telemetry.subscribe` method, gated on `telemetry.read`. See Telemetry.
`vision.frame`, `vision.detection`	The vision facade on `ctx.vision`. See Vision plugins.
`plugin.<id>.*`	Each plugin’s own events. See Plugin-to-plugin.

Topics are printable ASCII, at most 256 bytes. A subscription pattern can end in .* within your own namespace: plugin.<id>.* matches plugin.<id>.alert but not the bare plugin.<id>. Public host topics are subscribed by exact name. Subscribing needs event.subscribe, and the topic must be one of:

your own plugin.<id>. namespace;
one of the public host topics: vehicle.armed, vehicle.disarmed, vehicle.mode_changed, vehicle.battery_low, vehicle.geofence_breach, agent.ready, agent.shutdown;
a shared topic another plugin declares, when you also hold its subscribe_capability.

Publishing under your own plugin.<id>. prefix needs no capability. Reserved, never publishable: vehicle., mavlink., mission., safety., agent., swarm., gps., vision., telemetry., and any plugin. topic outside your own plugin.<id>. prefix or your declared shared topics. Other topics need event.publish. The host decides from the topic, not from what the plugin claims, and it stamps every event with the publishing plugin’s id. Topics are delivered verbatim; the host adds no prefix.

# manifest grants: event.subscribe
class Plugin:
    async def on_start(self, ctx) -> None:
        await ctx.events.subscribe("vehicle.armed", self._on_armed)
        # Your own namespace: no capability needed to publish.
        await ctx.events.publish(
            f"plugin.{ctx.plugin_id}.alert", {"kind": "cell_low", "v": 3.4}
        )

    async def _on_armed(self, event: dict) -> None:
        ...

Telemetry

The Python ctx.telemetry.extend(channel, payload) adds a channel to the node’s heartbeat (gated on telemetry.extend). To read vehicle state, call telemetry.subscribe (gated on telemetry.read). The host pushes the newest vehicle-state snapshot as a telemetry.state event, at most 10 times a second. A node with no flight controller never fires it.

Rust: telemetry_subscribe(callback) on the SDK client.
Python: subscribe_telemetry() on the IPC client, an async iterator over the same telemetry.state snapshots. For individual MAVLink messages, use ctx.mavlink.subscribe (gated on mavlink.read). See MAVLink extensions.

A GCS half reads telemetry through ctx.telemetry.subscribe, gated on telemetry.subscribe or a per-topic telemetry.subscribe.<topic> grant. See Permissions.

Delivery and back-pressure

Each subscriber has its own queue, 256 events deep. Event payloads are capped at 64 KiB. The bus never blocks a publisher: when a subscriber’s queue is full, events are dropped for that subscriber and the host logs a warning. Treat live events as best-effort; if you need a complete record, persist from a recording instead. Do not block in an event handler. Hand work to a background task and return quickly:

import asyncio


class Plugin:
    async def on_start(self, ctx) -> None:
        self.queue: asyncio.Queue = asyncio.Queue(maxsize=64)
        asyncio.create_task(self._worker())
        await ctx.events.subscribe("vehicle.battery_low", self._ingest)

    async def _ingest(self, event: dict) -> None:
        try:
            self.queue.put_nowait(event)
        except asyncio.QueueFull:
            pass  # drop locally; never block the bus

    async def _worker(self) -> None:
        while True:
            event = await self.queue.get()
            ...

Plugin-to-plugin

A plugin.* event reaches only its publisher unless the publisher declares it in agent.contributes.shared_topics. A shared topic lives under plugin.<leaf>., where <leaf> is the last segment of the publisher’s id, and names the capability a subscriber must hold:

id: com.example.rangefinder
agent:
  permissions:
    - id: event.publish
    - id: mavlink.read
  contributes:
    shared_topics:
      - topic: plugin.rangefinder.reading
        subscribe_capability: mavlink.read

subscribe_capability is either a catalog capability or one the publisher declares itself under agent.declared_capabilities (plugin.<leaf>.<name>). The publisher needs event.publish to publish a shared topic. A subscriber needs event.subscribe plus that capability. Shared topics match exactly: plugin.rangefinder.reading.x gains nothing from the declaration. Plugin topics are derived data on a sandboxed bus. Nothing on the bus commands the vehicle.

Next steps

MAVLink extensions

Read and write MAVLink, register components and re-publish decoded data.

Multi-component plugins

How agent events reach the GCS half.

Permissions

Every capability and its risk level.

GCS bridge methods

Events and RPC on the Mission Control side.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Published topics

Telemetry

Delivery and back-pressure

Plugin-to-plugin

Next steps

MAVLink extensions

Multi-component plugins

Permissions

GCS bridge methods

​Published topics

​Subscribe and publish rules

​Telemetry

​Delivery and back-pressure

​Plugin-to-plugin

​Next steps

MAVLink extensions

Multi-component plugins

Permissions

GCS bridge methods

Published topics

Subscribe and publish rules

Telemetry

Delivery and back-pressure

Plugin-to-plugin

Next steps