MAVLink extensions

The agent already speaks MAVLink to the flight controller and routes it to the GCS. An agent plugin extends that through these facades:

ctx.mavlink: subscribe to messages, send frames, register a MAVLink component.
ctx.vision: register as the visual-odometry source and inject pose.
ctx.msp: the raw MSP byte plane to Betaflight, iNav and KISS flight controllers.
ctx.flight: scoped guided-mode and attitude/rate setpoint senders.

mavlink.write, msp.write, flight.guided_setpoint and flight.rate_setpoint can move the aircraft. Bench-test with props off and read Safety before flying a plugin that uses them.

Capabilities

Capability	Lets the plugin
`mavlink.read`	Subscribe to MAVLink messages from the link.
`mavlink.write`	Send MAVLink frames to the flight controller.
`mavlink.component.{camera,gimbal,payload,peripheral,vio}`	Register as a MAVLink component of that kind.
`mavlink.tunnel`	Exchange application payloads over MAVLink `TUNNEL` frames.
`msp.read`, `msp.write`	Receive and send MSP bytes.
`flight.guided_setpoint`	Send guided-mode position, velocity or acceleration setpoints.
`flight.rate_setpoint`	Send attitude and body-rate setpoints with thrust.

Risk levels and the install-dialog badges for each are on Permissions.

Subscribing to messages

ctx.mavlink.subscribe registers a callback for one message name. The callback receives the message name, the raw frame bytes and a timestamp. Decode the frame with your own MAVLink library:

async def on_start(self, ctx) -> None:
    async def on_battery(msg: dict) -> None:
        # msg["msg_name"], msg["frame"] (raw bytes), msg["timestamp_ms"]
        self.decode_and_store(msg["frame"])

    await ctx.mavlink.subscribe("BATTERY_STATUS", on_battery)

The host reads each inbound frame once and fans it out to every subscriber; no per-plugin parser runs on the link.

Sending frames

ctx.mavlink.send writes an encoded frame to the flight controller. Pass component_id to send under a component the plugin has registered:

frame = encode_command_long(
    target_system=1,
    target_component=1,
    command=203,  # MAV_CMD_DO_DIGICAM_CONTROL
    params=[0, 0, 0, 0, 1, 0, 0],
)
await ctx.mavlink.send(frame)

Registering as a component

A plugin that should appear on the MAVLink bus as a camera, gimbal, payload, peripheral or visual-odometry source registers a component id. Declare it in the manifest so the host reserves the id, and hold the matching mavlink.component.<kind> capability:

agent:
  permissions:
    - id: mavlink.component.camera
  mavlink_components:
    - component_id: 100
      component_kind: camera
      sub_id: 1

async def on_start(self, ctx) -> None:
    await ctx.mavlink.register_component(100, "camera")

The kinds are camera, gimbal, payload, peripheral, vio and generic. The first five map to mavlink.component.<kind>. The SIYI pod extension registers camera 100 and gimbal 154; the Follow-Me and MAVLink Gimbal v2 extensions declare component 191 as generic.

Visual odometry

A visual-odometry plugin registers the vio component once, then sends pose estimates. The helpers are on ctx.vision and need the mavlink.component.vio grant:

async def on_start(self, ctx) -> None:
    self.ctx = ctx
    await ctx.vision.register_vio_component()

async def on_pose(self, pose) -> None:
    await self.ctx.vision.inject_pose(pose)  # VISION_POSITION_ESTIMATE

inject_odometry(odometry) sends an ODOMETRY message (pose plus body-frame twist) under the same component. A bad pose stream feeds the flight controller’s estimator and can produce unsafe position control.

Re-publishing decoded data

A common pattern decodes one message and re-publishes a clean event, so raw MAVLink stays in one plugin. Publish on your own namespace for your own use, and declare a shared topic for other plugins:

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

async def on_start(self, ctx) -> None:
    async def on_distance(msg: dict) -> None:
        distance_m = self.decode_distance(msg["frame"])
        await ctx.events.publish(f"plugin.{ctx.plugin_id}.reading", {"distance_m": distance_m})
        await ctx.events.publish("plugin.rangefinder.reading", {"distance_m": distance_m})

    await ctx.mavlink.subscribe("DISTANCE_SENSOR", on_distance)

Another plugin with event.subscribe and mavlink.read then subscribes to plugin.rangefinder.reading without touching MAVLink. Your plugin.com.example.rangefinder.* topics stay private to your plugin. See Agent event bus.

MSP flight controllers

For Betaflight, iNav and KISS flight controllers, ctx.msp moves raw MSP bytes. The host moves bytes only; build and parse frames with ados.plugins.msp. send needs msp.write and subscribe needs msp.read. MSP has no per-message topic, so the callback receives every chunk the flight controller sends:

async def on_start(self, ctx) -> None:
    async def on_bytes(chunk: dict) -> None:
        self.parser.feed(chunk["bytes"])  # chunk["timestamp_ms"] too

    await ctx.msp.subscribe(on_bytes)
    await ctx.msp.send(self.build_request())

Guided setpoints

A flight-behavior plugin commands the vehicle in guided mode through ctx.flight instead of raw MAVLink writes, so one capability gates the flight-command surface. guided_setpoint needs flight.guided_setpoint; the host encodes the matching SET_POSITION_TARGET_* message:

await ctx.flight.guided_setpoint(
    kind="local_ned",          # or "global_int" (lat/lon in 1e7, alt in m)
    coordinate_frame=1,        # MAV_FRAME_LOCAL_NED
    type_mask=0b0000_1101_1100_0111,  # velocity only
    vx=2.0, vy=0.0, vz=0.0,
)

kind picks the frame family, coordinate_frame is a MAV_FRAME_* value and type_mask is the ignore-axis bitmask. Unset axes default to zero. The call returns {"ok": bool, ...}, or a not_available shape when the MAVLink router is unreachable. rate_setpoint sends SET_ATTITUDE_TARGET (attitude quaternion and/or body rates plus normalized thrust) and needs flight.rate_setpoint. A GCS half does not send MAVLink. It calls ctx.command.send with one of the host’s named commands (takeoff, land, rtl), gated on command.send; the operator approves each command in a dialog before it reaches the vehicle.

Next steps

Vision plugins

Frames, inference and detections on the vision engine.

Agent event bus

Publish and subscribe rules and shared topics.

Permissions

Every capability and its risk level.

Safety

Pre-flight checks before flying a plugin that commands the aircraft.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Capabilities

Subscribing to messages

Sending frames

Registering as a component

Visual odometry

Re-publishing decoded data

MSP flight controllers

Guided setpoints

Next steps

Vision plugins

Agent event bus

Permissions

Safety

​Capabilities

​Subscribing to messages

​Sending frames

​Registering as a component

​Visual odometry

​Re-publishing decoded data

​MSP flight controllers

​Guided setpoints

​Next steps

Vision plugins

Agent event bus

Permissions

Safety

Capabilities

Subscribing to messages

Sending frames

Registering as a component

Visual odometry

Re-publishing decoded data

MSP flight controllers

Guided setpoints

Next steps