Your first plugin - ADOS Documentation

The Battery Health Panel is the first first-party extension on the new plugin host. It is a GCS-only plugin that reads the host’s normalized battery telemetry, runs an anomaly engine, and emits notifications when a rule fires. Source lives at altnautica/ADOSExtensions/extensions/battery-health-panel. This page walks through the parts that matter for plugin authors.

Manifest

schema_version: 1
id: com.altnautica.battery-health-panel
name: "ADOS Battery Health Panel"
version: "1.0.2"
description: "Cell-level battery diagnostics, predictive time-to-min, and anomaly alerts."
author: "Altnautica"
homepage: "https://github.com/altnautica/ADOSExtensions/tree/main/extensions/battery-health-panel"
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.fc-tab
    - id: ui.slot.notification-channel
    - id: ui.slot.settings-section
    - id: telemetry.subscribe.battery
    - id: telemetry.subscribe.mavlink
    - id: recording.write
  contributes:
    panels:
      - id: battery-health-tab
        slot: fc.tab
        title: "Battery Health"
        icon: "battery"
        order: 30
    notifications:
      - id: battery-anomaly
        title: "Battery anomaly"
        severity: warning
  locales:
    - en

Manifest fields are flat at the root (id, name, version, compatibility, then the gcs half). Permissions are a list of - id: <capability> entries. Six permissions, two contributes blocks (panels and notifications), no agent half. See the permissions reference for the full set of GCS slot ids. Risk band: low (no vehicle.command, no host file system, no network).

Entry point

import { definePlugin } from "@altnautica/plugin-sdk";
import { createBatteryStore } from "./batteryStore";
import type { BatterySample } from "./types";

const store = createBatteryStore();

definePlugin({
  id: "com.altnautica.battery-health-panel",
  version: "1.0.0",
  async mount(ctx) {
    await ctx.telemetry.subscribe<BatterySample>(
      "battery",
      (sample) => store.ingest(sample),
    );
    store.onAnomaly(async (fired) => {
      for (const event of fired) {
        await ctx.notifications.publish({
          channelId: "battery-anomaly",
          severity: event.severity,
          title: event.title,
          body: event.body,
        });
        await ctx.recording.mark({ label: event.title });
      }
    });
  },
});

definePlugin is the only SDK call. Everything else is plain TypeScript: a store, a rule engine, a render loop. The SDK gets out of the way.

Anomaly rule

const ruleCellLow: Rule = ({ curr, config }) => {
  const min = minDefined(curr.cellVoltagesV);
  if (min === null || min >= config.lowCellVoltageV) return null;
  if (min < config.criticalCellVoltageV) return null;
  return mk("cell_low", curr, "warning", "Cell low", `${min.toFixed(2)} V`);
};

A rule is a pure function from (prev, curr, config) to AnomalyEvent | null. The store calls every rule on every new sample. Hysteresis is the store’s job: an anomaly stays in the live list until the underlying condition has been clear for at least 5 seconds.

Testing without a host

The SDK ships a synthetic-host harness:

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

const harness = createPluginHarness({
  grantedCapabilities: [
    "telemetry.subscribe.battery",
    "ui.slot.notification-channel",
    "recording.write",
  ],
  mount: async (ctx) => {
    await ctx.telemetry.subscribe("battery", (s) => store.ingest(s));
    store.onAnomaly(async (fired) => {
      for (const e of fired) {
        await ctx.notifications.publish({ ... });
      }
    });
  },
});

await harness.start();
harness.pushTelemetry("battery", { cellVoltagesV: [3.9, 3.4, 3.9, 3.9], ... });
expect(harness.notifications).toHaveLength(1);
expect(harness.notifications[0]).toMatchObject({ severity: "warning" });
await harness.teardown();

The harness lets a single Vitest run validate the whole plugin without spinning up Mission Control or a real drone.

Packing and installing

pnpm test
scripts/pack.sh battery-health-panel

pack.sh builds the GCS bundle (esbuild into plugin.bundle.js), computes SHA-256 hashes for every asset, and zips the result into extensions/battery-health-panel/dist/<id>-<version>.adosplug. The version comes from the manifest, so the archive is named com.altnautica.battery-health-panel-1.0.2.adosplug. Signing is a separate step. With a publisher Ed25519 key in ADOS_SIGNING_KEY, sign the packed archive:

ADOS_SIGNING_KEY=/path/to/key.ed25519 \
  scripts/sign.sh dist/com.altnautica.battery-health-panel-1.0.2.adosplug

That writes a *.signed.adosplug carrying a SIGNATURE file (signer id plus the base64 Ed25519 signature over the canonical payload hash). The signer id defaults to altnautica-2026-A; override it with ADOS_SIGNING_KEY_ID. Drag the archive into Mission Control -> Settings -> Plugins -> Install plugin. Approve the six declared permissions. The panel mounts under the FC tab.

What is next

See permissions to plan the smallest surface a real plugin needs.
See event hooks to learn the host RPC catalog.
See distribution and local install to publish a signed release on GitHub.

​Manifest

​Entry point

​Anomaly rule

​Testing without a host

​Packing and installing

​What is next