Code recipes

These recipes show where code goes for the most common changes. Setting up a development environment, branch names and pull request rules are on Contributing. Directory layouts are on Project structure. To add a board, follow HAL and tiers.

Test against ArduPilot SITL

Most Mission Control recipes end with a test against a simulated autopilot. The SITL tool in tools/sitl/ builds ArduPilot and bridges it to a WebSocket:

cd tools/sitl
npm install
npm run setup   # fetch and build ArduPilot into ~/.ardupilot
npm start

The bridge binds the IPv6 loopback and accepts only clients that present a per-run token. Copy the ws://[::1]:5760/?token=... URL it prints. In Mission Control, open the connect dialog, choose Flight Controller, then WebSocket, pick the SITL #1 preset and paste the full URL, token included. The token changes on every start.

SITL accepts arm, takeoff and mission commands like a real autopilot. Before you point the same code at hardware, read Safety.

Add a flight controller panel (Mission Control)

Configuration panels live under src/components/fc/<area>/. Every panel reads and writes parameters through usePanelParams, which works the same for MAVLink parameters and MSP virtual parameters.

Create the component

// src/components/fc/misc/MyNewPanel.tsx
import { usePanelParams } from "@/hooks/use-panel-params";
import { usePanelCommit } from "@/hooks/use-panel-commit";

const paramNames = ["MY_PARAM_1", "MY_PARAM_2"];

export function MyNewPanel() {
  const {
    params,
    loading,
    dirtyParams,
    setLocalValue,
    saveAllToRam,
    commitToFlash,
    revertAll,
  } = usePanelParams({ paramNames, panelId: "my-new-panel", autoLoad: true });
  const { saving, save, flash } = usePanelCommit({ saveAllToRam, commitToFlash, revertAll });

  // Render inputs bound to params.get(name) and setLocalValue(name, value),
  // and the save and flash buttons wired to save() and flash().
}

src/components/fc/safety/FailsafePanel.tsx is a complete example, including the unsaved-changes guard.

List it in the panel navigation

Add an entry to FC_NAV_ITEMS in src/components/drone-detail/fc-nav-items.tsx:

{ id: "my-new-panel", labelKey: "myNewPanel", icon: <Sliders size={14} />, requiredCapability: "supportsParameters", section: "Tuning" },

requiredCapability hides the panel on firmwares that lack the capability. vehicleClasses, requiredVehicleType and excludeFirmware narrow it further.

Route the id to the component

In src/components/drone-detail/FcPanelRouter.tsx, add a dynamic() import for the panel and a case "my-new-panel": that returns it.

Add the label

Add "myNewPanel" under the fcNav namespace in locales/en.json. English is the source locale.

Test with SITL

Connect to SITL, open the panel, and check that it loads, edits and writes the parameters.

Add a MAVLink decoder (Mission Control)

In src/lib/protocol/mavlink-crc-extra.ts, add the message id to both maps:

// CRC_EXTRA
[999, 0xab],   // MY_NEW_MSG, from the MAVLink XML definition
// PAYLOAD_LENGTHS
[999, 24],     // MY_NEW_MSG, full (untrimmed) payload length

Without a CRC_EXTRA entry the parser cannot validate the frame.

Write the decoder

Add a typed decode* function to the matching file in src/lib/protocol/messages/:

export interface MyNewMsg {
  field1: number;
  field2: number;
}

export function decodeMyNewMsg(dv: DataView): MyNewMsg {
  return {
    field1: dv.getFloat32(0, true),
    field2: dv.getUint16(4, true),
  };
}

Add the callback

Add a callback type in src/lib/protocol/types/callbacks.ts, a myNewMsgCallbacks array to CallbackStore in src/lib/protocol/mavlink-adapter-callbacks.ts, and an onMyNewMsg entry in bindCallbackMethods. Declare onMyNewMsg?(callback: MyNewMsgCallback): () => void; on DroneProtocol in src/lib/protocol/types/protocol.ts. Making it optional means the MSP and mock adapters do not have to implement it.

Handle and route the frame

Add a handler to the matching file in src/lib/protocol/handlers/ that decodes the payload and calls each callback, then add a case to routeFrame() in src/lib/protocol/mavlink-adapter-frame-handlers.ts:

case 999: handleMyNewMsg(p, c.myNewMsgCallbacks); break

Bridge it into a store

Subscribe in bridgeTelemetry() in src/stores/drone-manager-bridge.ts and push the data into a store. Add the returned unsubscribe function to the array the bridge returns.

Add a Zustand store (Mission Control)

Create the store

// src/stores/my-new-store.ts
import { create } from "zustand";

interface MyNewState {
  value: number;
  setValue: (v: number) => void;
}

export const useMyNewStore = create<MyNewState>((set) => ({
  value: 0,
  setValue: (v) => set({ value: v }),
}));

Select specific fields

const value = useMyNewStore((s) => s.value);

Never subscribe to the whole store.

If the store must survive a reload, wrap it in persist with a storage name, a version and a migration:

import { create } from "zustand";
import { persist, createJSONStorage } from "zustand/middleware";
import { indexedDBStorage } from "@/lib/storage";

export const useMyNewStore = create<MyNewState>()(
  persist(
    (set) => ({
      value: 0,
      setValue: (v) => set({ value: v }),
    }),
    {
      name: "altcmd:my-new-store",
      storage: createJSONStorage(indexedDBStorage.storage),
      version: 1,
      migrate: (persisted, _version) => persisted as MyNewState,
    },
  ),
);

Bump version and branch on the old version in migrate whenever the stored shape changes. If the store is fed by live telemetry, do not call set() per message. Mutate the data in place and notify through a coalesced version bumper, as telemetry-store does:

import { createVersionBumper } from "./coalesced-version";

const bumper = createVersionBumper(() =>
  useMyNewStore.setState((s) => ({ _version: s._version + 1 })),
);
// after each in-place update:
bumper.scheduleVersionBump();

A store with a bumper must call bumper.cancelVersionBump() from its clear() action.

Add an agent service (Drone Agent)

New long-running services are Rust binaries in the crates/ workspace, installed to /opt/ados/bin/. The supervisor runs every unit through systemctl; it never spawns processes itself. The design is explained on Agent services.

Create the crate

Add crates/ados-my-service/ with a binary target and add it to the workspace members in crates/Cargo.toml. Use ados-protocol for any socket you read or write, so framing and contract versions stay in one place.

Write the unit file

Add data/systemd/ados-my-service.service, following the existing units:

[Unit]
Description=ADOS My Service
PartOf=ados-supervisor.service

[Service]
Slice=ados.slice
Type=simple
ExecStart=/opt/ados/bin/ados-my-service
Restart=always
RestartSec=3
Environment=ADOS_CONFIG=/etc/ados/config.yaml
NoNewPrivileges=yes
ProtectSystem=strict
ReadWritePaths=/run/ados
MemoryMax=50M
CPUQuota=25%
StandardOutput=journal
StandardError=journal
SyslogIdentifier=ados-my-service

[Install]
WantedBy=ados-supervisor.service

Set MemoryMax, CPUQuota and ReadWritePaths to what the service really needs.

Add a UnitSpec row to UNITS in crates/ados-protocol/src/units.rs. The supervisor’s catalog, the installer’s enable, start, teardown and health lists, the REST restart allowlist and the armed interlock’s link-dropping class are all derived from that table, and a test fails if a unit file in data/systemd/ has no row (or a row has no unit file):

UnitSpec {
    name: "ados-my-service.service",
    category: Some(Hardware),
    profiles: DRONE,
    ..BASE
},

Set idle_ok: true if the service exits 0 on purpose when the node has nothing for it to do, and drops_link: true if restarting it drops a command, telemetry, video, RC, mesh, access-point or cloud link.

Ship the binary

Add the binary to the installer’s prebuilt catalog in crates/ados-installer/src/binaries.rs for the profiles that run it. CI publishes every service binary as an asset of the per-commit rev-<sha> release, and the installer fetches the assets for the active profile from there.

Next steps

Contributing

Development setup, branches and pull requests.

Project structure

Where every module lives.

HAL and tiers

Add a board profile.

Architecture

Integrations

Contribute to the code

Test against ArduPilot SITL

Add a flight controller panel (Mission Control)

Add a MAVLink decoder (Mission Control)

Add a Zustand store (Mission Control)

Add an agent service (Drone Agent)

Next steps

Contributing

Project structure

HAL and tiers

​Test against ArduPilot SITL

​Add a flight controller panel (Mission Control)

​Add a MAVLink decoder (Mission Control)

​Add a Zustand store (Mission Control)

​Add an agent service (Drone Agent)

​Next steps

Contributing

Project structure

HAL and tiers

Test against ArduPilot SITL

Add a flight controller panel (Mission Control)

Add a MAVLink decoder (Mission Control)

Add a Zustand store (Mission Control)

Add an agent service (Drone Agent)

Next steps