Your first plugin

This walkthrough builds com.example.hello-panel, the smallest useful plugin: a GCS-only tab on a drone’s node-detail panel that subscribes to the host’s battery telemetry and prints the pack voltage. There is no agent half. The plugin runs inside Mission Control in a sandboxed iframe, and the drone’s agent stores and serves it. By the end you have a manifest the host accepts, a bundle that mounts, a unit test that runs without Mission Control, and a signed .adosplug installed on a drone.

Battery health (per-cell analysis, sag detection, time-to-reserve and alerts) is built into the Drone Agent. See Battery health. This tutorial uses the battery topic only because every drone publishes it.

Prerequisites

Node.js 20+ and pnpm 9+.
bash with rsync and zip for scripts/pack.sh (Linux or macOS; on Windows use WSL).
Python 3.11+ with the cryptography package, for signing.
Mission Control connected to a drone that runs the ADOS Drone Agent, and root access on that drone to enrol your signing key. Demo mode does not install extensions.

1. Clone and scaffold

The SDK and the create-ados-plugin scaffolder live in the altnautica/ADOSExtensions monorepo. Neither is published to npm, so develop the plugin as a workspace member there:

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/hello-panel \
  --id com.example.hello-panel \
  --half gcs-only \
  --author "Your Name" \
  --signer my-publisher-2026-A
pnpm install

Inside the workspace the scaffolder pins @altnautica/plugin-sdk to workspace:^, so the plugin builds against the SDK in the tree. The GCS-only template lays out:

extensions/hello-panel/
├── manifest.yaml
├── package.json
├── README.md
├── CHANGELOG.md
├── .gitignore
├── locales/en.json
└── gcs/
    ├── package.json
    ├── tsconfig.json
    └── src/plugin.ts

The generated gcs/src/plugin.ts mounts a one-line greeting from the locale bundle:

import { definePlugin } from "@altnautica/plugin-sdk";

definePlugin({
  id: "com.example.hello-panel",
  version: "0.1.0",
  async mount(ctx) {
    const root = document.body;
    root.style.background = "var(--bg, #0c0c0c)";
    root.style.color = "var(--fg, #e6e6e6)";
    root.style.font = "12px system-ui, sans-serif";
    root.style.padding = "12px";
    root.textContent = ctx.i18n.t("hello.title");
  },
});

The next steps replace it with a battery tab.

2. Manifest

Replace the generated manifest.yaml with:

schema_version: 1
id: com.example.hello-panel
name: "Hello Panel"
version: "0.1.0"
description: "Prints the drone's battery pack voltage in a node-detail tab."
author: "Your Name"
license: "GPL-3.0-or-later"
risk: low

compatibility:
  ados_version: ">=0.10.0"
  gcs_version: ">=0.5.0"
  supported_boards: ["*"]

gcs:
  entrypoint: "gcs/plugin.bundle.js"
  isolation: iframe
  permissions:
    - id: ui.slot.node-detail-tab
    - id: telemetry.subscribe.battery
  contributes:
    tabs:
      - id: hello-tab
        slot: node.detail.tab
        profile: ["drone"]
        title: "Hello"
        icon: "battery"
        order: 90
  locales:
    - en

What each part does:

No agent block. A manifest needs at least one half; this one ships only the GCS half, so no process runs on the drone. The agent still checks compatibility and stores the bundle.
tabs mounts the bundle as a tab on the node-detail panel. A tab always lives in the node.detail.tab slot. profile: ["drone"] offers it on drones only; leave profile out to offer it on every node profile.
ui.slot.node-detail-tab lets the tab mount. Every visual contribution needs its matching ui.slot.* permission, or the slot skips it.
telemetry.subscribe.battery is the topic-scoped telemetry grant. The bridge checks it on every subscribe to the battery topic; the bare telemetry.subscribe grants no stream.
risk: low: the plugin reads telemetry and draws a tab. It sends no commands and stores nothing.

See Contribution points for every contribution kind and Permissions for the capability catalog.

3. The panel

Keep the logic in its own module so it can be tested without a browser. Create gcs/src/panel.ts:

import type { BatterySample, PluginContext } from "@altnautica/plugin-sdk";

export function formatPack(sample: BatterySample): string {
  return `Pack ${sample.packId}: ${sample.totalVoltageV.toFixed(2)} V`;
}

export async function mountPanel(
  ctx: PluginContext,
  el: HTMLElement,
): Promise<() => void> {
  el.textContent = "Waiting for battery telemetry";
  return ctx.telemetry.subscribe<BatterySample>("battery", (sample) => {
    el.textContent = formatPack(sample);
  });
}

ctx.telemetry.subscribe asks the host to open the battery stream for the drone the tab is mounted on. It resolves with an unsubscribe function once the host accepts the subscription. If the grant is missing, the promise rejects and no handler is left behind. Every frame on the battery topic is a BatterySample:

Field	Type	Notes
`timestampMs`	number	Sample time in milliseconds.
`packId`	number	Battery instance reported by the flight controller.
`cellVoltagesV`	number[]	Empty when the flight controller does not report cells.
`totalVoltageV`	number	Pack voltage.
`currentA`	number or null
`consumedAh`	number or null
`remainingPercent`	number or null
`temperatureC`	number or null
`cellCount`	number or null

Values the flight controller does not report arrive as null.

4. The entry point

Replace gcs/src/plugin.ts with:

import { definePlugin } from "@altnautica/plugin-sdk";
import { mountPanel } from "./panel";

definePlugin({
  id: "com.example.hello-panel",
  version: "0.1.0",
  async mount(ctx) {
    const el = document.createElement("div");
    el.style.font = "14px system-ui, sans-serif";
    el.style.padding = "12px";
    document.body.appendChild(el);
    await mountPanel(ctx, el);
  },
});

definePlugin is the only call a plugin module must make. The host loads the bundle inside the tab’s iframe, and the SDK calls mount with a PluginContext wired to the host bridge. When the tab closes or the operator switches node, Mission Control destroys the iframe, which ends the subscription with it. See Lifecycle for the teardown rules.

5. Test without a host

The SDK ships a synthetic host at @altnautica/plugin-sdk/harness. It runs the plugin against an in-memory transport and lets you push telemetry frames by hand. Create gcs/src/panel.test.ts:

import { describe, expect, it } from "vitest";
import { createPluginHarness } from "@altnautica/plugin-sdk/harness";
import { mountPanel } from "./panel";

describe("hello panel", () => {
  it("prints the pack voltage", async () => {
    const el = { textContent: "" } as HTMLElement;
    const harness = createPluginHarness({
      grantedCapabilities: ["telemetry.subscribe.battery"],
      mount: async (ctx) => {
        await mountPanel(ctx, el);
      },
    });
    await harness.start();

    harness.pushTelemetry("battery", {
      timestampMs: 0,
      packId: 0,
      cellVoltagesV: [4.1, 4.1, 4.1, 4.12],
      totalVoltageV: 16.42,
      currentA: null,
      consumedAh: null,
      remainingPercent: null,
      temperatureC: null,
      cellCount: 4,
    });

    expect(el.textContent).toBe("Pack 0: 16.42 V");
    await harness.teardown();
  });
});

Run it from the GCS package:

cd extensions/hello-panel/gcs
pnpm test

The harness gates most calls by capability like the host, but it does not gate telemetry subscriptions, so this test passes even without the grant. To check the capability your plugin claimed, assert on harness.calls: each entry records the method and the capability.

6. Pack

From the monorepo root:

scripts/pack.sh hello-panel

pack.sh builds the GCS bundle (esbuild into gcs/plugin.bundle.js), checks that every entrypoint the manifest declares is present, and zips the result into extensions/hello-panel/dist/com.example.hello-panel-0.1.0.adosplug. The name comes from the manifest id and version.

7. Sign and enrol your key

A default agent installs only archives signed by a key it trusts. Create a key once, sign the archive, and enrol the public key on the drone:

ados plugin keygen my-publisher-2026-A --output-dir keys
ADOS_SIGNING_KEY=keys/my-publisher-2026-A.priv.pem \
ADOS_SIGNING_KEY_ID=my-publisher-2026-A \
  scripts/sign.sh extensions/hello-panel/dist/com.example.hello-panel-0.1.0.adosplug

sign.sh writes com.example.hello-panel-0.1.0.signed.adosplug next to the input, with a SIGNATURE entry: the signer id, then the base64 Ed25519 signature over the canonical payload hash. Copy keys/my-publisher-2026-A.pem to /etc/ados/plugin-keys/ on the drone (root). Keep the .priv.pem out of git. Where to run keygen, how to enrol the key on a node, and the bench-only unsigned mode are covered in Bench install and signing.

8. Install

In Mission Control, open the drone from the fleet, switch to its Extensions tab, and choose Install from file. Drop in com.example.hello-panel-0.1.0.signed.adosplug. The review shows the signer, the board compatibility and the two permissions; choose Install, which reads grants 2 permissions. The Hello tab appears on the drone’s node-detail panel and updates with every battery frame. On the drone itself, ados plugin install does the same from a shell:

ados plugin install ./com.example.hello-panel-0.1.0.signed.adosplug

What just happened

The agent parsed the archive in memory, verified the signature against your enrolled key, checked compatibility, and returned a preview. Nothing was written yet.
After you approved, the agent unpacked the archive, recorded the install, and granted the two permissions.
Mission Control fetched the bundle from the agent, mounted an <iframe sandbox="allow-scripts"> on the Hello tab, and wired the postMessage bridge, which checks telemetry.subscribe.battery on every subscribe.

Next steps

Scaffolder walkthrough

A hybrid plugin with an agent half, a flight skill and parameters.

Permissions

Plan the smallest capability set a real plugin needs.

TypeScript SDK

Everything on the GCS PluginContext.

Distribution

Ship a signed release.

Start here

Tutorials

Reference

SDKs

Deep dives

Test and distribute

Prerequisites

1. Clone and scaffold

2. Manifest

3. The panel

4. The entry point

5. Test without a host

6. Pack

7. Sign and enrol your key

8. Install

What just happened

Next steps

Scaffolder walkthrough

Permissions

TypeScript SDK

Distribution

​Prerequisites

​1. Clone and scaffold

​2. Manifest

​3. The panel

​4. The entry point

​5. Test without a host

​6. Pack

​7. Sign and enrol your key

​8. Install

​What just happened

​Next steps

Scaffolder walkthrough

Permissions

TypeScript SDK

Distribution

Prerequisites

1. Clone and scaffold

2. Manifest

3. The panel

4. The entry point

5. Test without a host

6. Pack

7. Sign and enrol your key

8. Install

What just happened

Next steps