Scaffolder walkthrough: a hybrid plugin

This walkthrough scaffolds one hybrid plugin and reads through what the template gives you: a flight skill in the cockpit Skill Bar, a node-detail tab, native parameters (including a model picker), and a Python agent half that reads the live config and publishes its state. It then adds a target action, so the operator can click a detected person in the cockpit and follow it. By the end you have a signed archive that installs on a drone. The pattern matches the Follow-Me extension, trimmed to the parts that matter here.

Prerequisites

Node.js 20+ and pnpm 9+.
Python 3.11+ and uv for the agent-half tests, plus the cryptography package for signing.
bash with rsync and zip for scripts/pack.sh (Linux or macOS; on Windows use WSL).
Mission Control connected to a drone that runs the ADOS Drone Agent.

1. Clone and scaffold

git clone https://github.com/altnautica/ADOSExtensions.git
cd ADOSExtensions
pnpm install
pnpm --filter @altnautica/plugin-sdk build

node packages/create-ados-plugin/bin/cli.mjs \
  --target extensions/track-follow \
  --id com.example.track-follow \
  --half hybrid \
  --author "Your Name" \
  --signer my-publisher-2026-A
pnpm install

The hybrid template lays out both halves with their tests:

extensions/track-follow/
├── manifest.yaml
├── package.json
├── README.md
├── .gitignore
├── locales/en.json
├── agent/
│   ├── plugin.py
│   ├── pyproject.toml
│   └── tests/test_plugin.py
└── gcs/
    ├── package.json
    ├── tsconfig.json
    ├── vitest.config.ts
    ├── src/plugin.ts
    └── tests/plugin.test.ts

2. The manifest

The generated manifest.yaml declares both halves. The parts that matter, with the template’s __PLUGIN_ID__ already filled in:

schema_version: 2
id: com.example.track-follow
name: "Hello Hybrid Plugin"
version: "0.1.0"
risk: low

compatibility:
  ados_version: ">=0.95.0"
  gcs_version: ">=0.34.0"

agent:
  runtime: python
  entrypoint: "plugin:HelloPlugin"
  isolation: subprocess
  per_drone_config: true
  permissions:
    - id: event.publish
  resources:
    max_ram_mb: 64
    max_cpu_percent: 10
    max_pids: 4

gcs:
  entrypoint: "gcs/plugin.bundle.js"
  isolation: iframe
  permissions:
    - id: ui.slot.flight-skill
    - id: ui.slot.node-detail-tab
    - id: command.send
  contributes:
    skills:
      - id: hello
        label: "skill.label"
        icon: "sparkles"
        category: utility
        toggle: true
        confirm: false
        arm_requirement: any
        default_binding:
          key: "h"
        activation:
          via: config
          config_key: active
        state:
          via: event
          topic: "hello.state"
    tabs:
      - id: hello-tab
        slot: node.detail.tab
        profile: ["drone"]
        title: "tab.title"
        icon: "sparkles"
        order: 90
    parameters:
      - key: rate_hz
        binding: plugin.config
        schema: { type: number, minimum: 1, maximum: 20, step: 1, default: 5 }
        ui: { widget: range, label: "settings.rate", group: "settings.group", order: 10 }
      - key: greeting
        binding: plugin.config
        schema: { type: string, enum: ["hello", "namaste", "hola"], default: "hello" }
        ui: { widget: enum, label: "settings.greeting", group: "settings.group", order: 20 }
      - key: detector
        binding: engine.detector
        schema: { type: string, default: "coco-person" }
        ui: { widget: model, task: detection, label: "settings.detector", group: "settings.group", order: 30 }
  locales:
    - en

Labels such as skill.label are keys into locales/en.json. There is no supported_boards, so the plugin installs on any board; to restrict it, list board ids or SoCs from Supported hardware, or "*" for any board.

skills: the Skill Bar

ui.slot.flight-skill puts the entry in the cockpit Skill Bar, bound to h. Toggling it writes the per-drone config key active; the bar reads the live state from the hello.state event topic.

tabs: the node-detail tab

ui.slot.node-detail-tab mounts the GCS bundle as a tab on the drone’s detail panel. The bundle renders the agent’s read-back.

parameters: the native form

Mission Control renders these controls itself; the bundle does not draw them. binding: plugin.config writes the value to the plugin’s per-drone config, which the agent half reads live. The detector parameter binds to engine.detector, so picking a model switches the drone’s shared vision detector.

The template also carries a commented-out models block with per-board variants. Enable it only once source points at a real artifact and sha256 is that file’s digest; see Contribution points.

3. The agent half

agent/plugin.py defines a plain class with the lifecycle hooks the runner calls. It reads its per-drone config live on every cycle and publishes the read-back the Skill Bar and the tab consume:

import asyncio
from typing import Any

STATE_TOPIC = "hello.state"


class HelloPlugin:
    def __init__(self) -> None:
        self._ctx: Any = None
        self._task: asyncio.Task[None] | None = None

    async def on_start(self, ctx: Any) -> None:
        self._ctx = ctx
        ctx.log.info("hello_plugin_started")
        self._task = asyncio.create_task(self._loop())

    async def on_stop(self, ctx: Any) -> None:
        if self._task is not None:
            self._task.cancel()
            self._task = None

    async def _loop(self) -> None:
        while True:
            active = bool(await self._ctx.config_kv.get("active", False))
            rate_hz = float(await self._ctx.config_kv.get("rate_hz", 5) or 5)
            await self._ctx.events.publish(STATE_TOPIC, {"active": active})
            await asyncio.sleep(1.0 / max(rate_hz, 1.0))

activation.via: config means the Skill toggle is a config write the host routes to the agent; the plugin sees it on its next ctx.config_kv.get. ctx.config is the static config loaded at start; use ctx.config_kv for values that change while the plugin runs. See the Python SDK for the full context.

4. Follow a clicked target

To make the plugin follow a person the operator clicks in the cockpit video, the agent half subscribes to detections and the GCS half declares a target action. Add vision.detection.subscribe to agent.permissions, then subscribe in on_start:

    async def on_start(self, ctx: Any) -> None:
        self._ctx = ctx
        await ctx.events.publish(STATE_TOPIC, {"active": False})
        await ctx.vision.subscribe_detections(self._on_batch)
        self._task = asyncio.create_task(self._loop())

    async def on_configure(self, ctx: Any, config: dict) -> None:
        # Called once, before on_start, with the static config.
        ctx.log.info("hello_configured", keys=sorted(config))

    async def _on_batch(self, batch: Any) -> None:
        if not bool(await self._ctx.config_kv.get("active", False)):
            return
        # Steer toward the tracked subject here.

Then add a target_actions block under gcs.contributes:

    target_actions:
      - id: follow
        label: "Follow this target"
        icon: crosshair
        order: 20
        applies_to_class: person
        designate: true
        config_key: active
        config_value: true
        default_key: "f"
      - id: stop-follow
        label: "Stop following"
        icon: circle-stop
        order: 21
        applies_to_class: person
        designate: false
        config_key: active
        config_value: false
        default_key: "x"

When the operator clicks a person and picks Follow this target, Mission Control designates that box to the drone’s vision tracker and writes active: true to the plugin’s config. The action inherits the confirm and arm gates of any skill that writes the same config_key. Mission Control performs both steps, so a target action needs no extra GCS permission. A GCS half that designates from its own UI instead calls ctx.command.send("vision.designate", { camera_id, bbox: { x, y, width, height } }). That needs vision.track.designate under gcs.permissions; command.send alone does not allow designation, and the operator confirms every designation.

A plugin that steers the vehicle needs flight capabilities on its agent half (mavlink.write, flight.guided_setpoint) and a risk of at least high. Read Safety and test on a simulator before any flight.

5. Test

From the plugin folder, the template’s test script runs both halves:

cd extensions/track-follow
pnpm test

That runs vitest in gcs/ and then uv run pytest in agent/.

6. Pack, sign and install

From the monorepo root:

scripts/pack.sh track-follow
ADOS_SIGNING_KEY=keys/my-publisher-2026-A.priv.pem \
ADOS_SIGNING_KEY_ID=my-publisher-2026-A \
  scripts/sign.sh extensions/track-follow/dist/com.example.track-follow-0.1.0.adosplug

pack.sh builds the GCS bundle, checks that the declared entrypoints are present, and zips the result. sign.sh writes com.example.track-follow-0.1.0.signed.adosplug. The drone must trust my-publisher-2026-A: enrol its public key as described in Bench install and signing. Open the drone from the fleet, switch to its Extensions tab, choose Install from file and drop in the .signed.adosplug. Approve the permissions and enable the extension.

Verify each contribution

Skill Bar

Open the drone’s cockpit. The Hello skill is in the Skill Bar, bound to h. Press it; the per-drone config key active flips.

Node-detail tab

Open the drone’s detail panel. The Hello tab shows the live read-back from the agent half.

Parameters

The Behavior group shows the rate slider, the greeting dropdown and the detector picker. Edits clamp to the schema bounds.

Target action

With a detector running, click a person in the cockpit video. The popup offers Follow this target.

Next steps

Contribution points

Every contribution kind in detail.

Parameter schema

Widgets, bindings and validation.

Python SDK

The agent-half context.

Vision plugins

Detectors, models and the vision engine.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Scaffolder walkthrough: a hybrid plugin

Prerequisites

1. Clone and scaffold

2. The manifest

3. The agent half

4. Follow a clicked target

5. Test

6. Pack, sign and install

Verify each contribution

Next steps

Contribution points

Parameter schema

Python SDK

Vision plugins

​Prerequisites

​1. Clone and scaffold

​2. The manifest

​3. The agent half

​4. Follow a clicked target

​5. Test

​6. Pack, sign and install

​Verify each contribution

​Next steps

Contribution points

Parameter schema

Python SDK

Vision plugins

Prerequisites

1. Clone and scaffold

2. The manifest

3. The agent half

4. Follow a clicked target

5. Test

6. Pack, sign and install

Verify each contribution

Next steps