Skip to main content

The remote link

How the Suite reaches a vehicle that is not on the local network.

The LTE and MediaMTX feature switches are enabled in the production build. They still default to off in an unspecified build so an accidental local build does not expose a half-configured control surface. See Environment variables.

The shape of it​

Autopilot ──serial MAVLink──► telemetry agent ──loopback WS──► Jetson gateway
▲
Cameras ──RTSP──► camera relay ──► MediaMTX (on the aircraft) │
▲ │
└──── Cloudflare Named Tunnel ─┘
│
browser ◄────────┘────────► Suite Node service

One Named Tunnel and one hostname per vehicle. The gateway and the media server both sit behind it, on the same public origin.

The four names of a vehicle​

A vehicle is known by four strings, to four parties, and the Suite keeps them apart (#43):

NameWhereUsed byRule
Suite iddrones.idevery table, page and API path of the Suitea UUID; never shown, never sent to the vehicle
gateway idconnections.drone_idthe runtime on the vehicle (DRONE_ID), the drone_id claim of every token, the /drones/:id/ segment of every paththe one name the vehicle answers to; unique across vehicles; letters, digits and hyphens
serial numberdrones.serial_numberpeoplefree text, as printed on the airframe
hostnamethe host of connections.server_wsthe browser and Cloudflarewhere the tunnel answers

For an existing manually managed connection, none of these names is guessed. A connection without a gateway id gets no token, command, video or telemetry — the routes answer 424 naming the missing setting — and a gateway that does not know the name it is called by answers 404, reported as GATEWAY_UNKNOWN_VEHICLE: the finding is that DRONE_ID on the vehicle and the saved gateway id disagree, and no other id is tried in its place.

The convention for a vehicle provisioned from now on: gateway id = the serial as printed (SR00021), hostname derived from it, directly under the zone (sr00021.sabrobotix.com; a second-level name such as sr00021.drones.sabrobotix.com would have no certificate under Cloudflare's Universal SSL). One hostname per vehicle is what routes a request to that vehicle's tunnel; nobody types it. GET /api/drone-control/connections?droneId=… returns an identity block with the four names and what is off among them (gateway_id_missing, gateway_id_invalid, hostname_missing, hostname_legacy, serial_number_missing). The internal runbook docs/vehicle-identity.md has the migration order for a vehicle on an older hostname, with the old alias kept until the new one is verified, and how to correlate the Suite, Cloudflare and gateway logs.

Enrol an onboard Jetson​

Administrators and Operators prepare enrolment from Drone → Setup → Onboard computer. The Suite validates the serial as a gateway identity, derives the vehicle hostname, creates or adopts its dedicated Cloudflare Named Tunnel, writes the public hostname and the connection endpoints, then displays a one-time code valid for seven days.

For a new Ubuntu/JetPack ARM64 Jetson, first extract the full jetson-ai release on the vehicle and run:

sudo bash ./setup-jetson.sh --serial SR00017 --apn <SIM-PROVIDER-APN>

Use the vehicle's actual serial and carrier APN. This command installs missing dependencies and the remote-link runtime, prepares local TLS and configuration, detects Sierra EM7565 or SIM7600 USB hardware, configures its LTE path and asks for the one-time code displayed by the Suite without echoing it. Run it only on a grounded, disarmed vehicle with initial Internet access over Ethernet or Wi-Fi. Use --serial-port /dev/… --baud … when the autopilot wiring differs from the new-vehicle defaults /dev/ttyTHS2 at 57600. A missing matching JetPack kernel driver stops setup with a diagnostic; the command does not replace the vehicle's kernel. See the runtime repository's setup guide for supported USB modes, SIM requirements and recovery.

Use --no-lte instead of --apn to prepare over Ethernet/Wi-Fi, or add --skip-enrol to run the command shown by the Suite later. An existing enrolment is preserved when rerunning setup for the same vehicle. For a Jetson whose runtime is already installed and configured, run the command shown by the Suite directly. The Jetson generates its Ed25519 machine identity and sends only the public key, its SSH host public key, serial, runtime version, contract and capabilities. The Suite accepts no endpoint supplied by the vehicle. A successful claim returns the tunnel connector token, allowed Suite origins, the gateway signing public key and the derived identity. The local telemetry-agent secret stays on the Jetson and does not exist in the Suite database or UI.

Preparing a new code for an enrolled drone is the explicit replacement flow: the former machine identity and SSH host key are retired and the new ones are recorded. The hostname and tunnel remain stable. The clear enrolment code and tunnel connector token are each returned only where they are needed and are never stored in clear in the Suite's SQLite database.

The vehicle's SSH host key​

A shell on a vehicle trusts a host key, and that trust used to live in whichever ~/.ssh/known_hosts accepted it first. The Suite keeps the inventory instead (#40): the public half of each vehicle's host key, who registered it and through which channel, and what replaced or revoked it. Manual and first-connection discovery never register a key. A successful one-time Jetson enrolment records the key through the audited enrolment channel; a second key of the same type retires the first with the replacement reason.

GET /api/drones/:droneId/ssh-host-keys/known_hosts returns the lines to append before connecting, addressed by the vehicle's remote SSH hostname and gateway hostname; …/verify?fingerprint=SHA256:… says what the registry knows about the fingerprint in a "REMOTE HOST IDENTIFICATION HAS CHANGED" warning — current, replaced, revoked or unknown — and the internal runbook docs/vehicle-ssh-fingerprints.md says what to do in each case. None of them is "delete the line and try again".

Who holds what​

The Suite Node service authenticates the user, checks visibility with listVisibleDronesForContext — the same rule that answers /api/drones/visible — and signs short-lived tokens. It stores configuration and identities, but does not own the remote telemetry socket or MAVLink session.

Everything live is held by the browser:

  • Telemetry — the browser opens wss://<vehicle-host>/drones/:id/telemetry and receives MAVLink frames as JSON with Base64 payloads. Packet bytes are forwarded, never decoded and rebuilt, so unknown message IDs survive the trip.
  • Video — the browser performs WHEP through /api/drones/:droneId/playback/:path/whep, or uses the authenticated HLS proxy. The Suite route forwards to MediaMTX and keeps the vehicle origin and gateway token out of browser-visible configuration.

Mission, parameters, flight mode, guided commands and explicit camera stream start/stop use ordinary HTTPS requests from the Suite to the gateway API. Closing a published video player ends only that browser's playback; it does not call the vehicle's stream-stop operation. Gimbal and zoom take a separate path: data/drone-gateway-direct.ts obtains a token and gateway address from the Suite, caches the token until shortly before expiry, and sends commands directly from the browser. If the browser cannot reach that address, the authenticated Suite route is used as a fallback.

The contract​

What the Suite may expect of a vehicle, and what a vehicle may demand of the Suite, is written out in docs/onboard-gateway-contract.md in the repository: endpoints, token claims, refusal codes, the telemetry fields, and which parts have been measured against a real aircraft rather than read from the code.

It exists because three faults reached production without it — reads sent without a token, camera commands sent without a request id, and a missing camera reported as a missing link. None were errors of reasoning. They were things nobody had written down, and every test stubbed the gateway.

The token​

The Suite signs an EdDSA (Ed25519) JWT and the gateway verifies it against the matching public key. Nothing else authorizes a gateway request.

ClaimMeaning
audsabrobotix-jetson-gateway
subthe Suite user the request is made for
drone_idthe one vehicle this token is good for
exp30 to 300 seconds after issue, 120 by default
permissionstelemetry:read, media:read, health:read for everyone; camera:stream:control and, for non-client roles, command:write; mavlink:write for a ground station whose account has remote control

mavlink:write is granted per account through the Administrator's remote-control setting, not inherited from an Administrator or Operator role. It is issued only for a ground-station application; the web Suite never receives it. Harlock opens in view-only mode and needs the radio pilot's acceptance for each takeover request. Revocation blocks new requests as credentials renew but does not cut an already controlling session in flight. See Remote ground stations for discovery and the separate LTE-off proof.

The private half is supplied to the Node service as SUITE_GATEWAY_PRIVATE_KEY_PEM from the protected service environment file. It is never included in the browser bundle or repository. The OIDC signing keys and licence signing keys are separate systems; see Environment variables.

Why not a socket on the server​

The Suite used to hold that WebSocket too, and keep a session per user and vehicle in a map on globalThis. It was a second socket to every vehicle, doing what the browser was already doing, that nobody read.

That server-held remote session was removed during the former Workers migration. Returning to Node hosting does not restore it: the browser remains the owner of the remote telemetry connection, while the Jetson owns the live vehicle services.

It is gone. What the routes answer now is built from the stored connection: connect resolves the endpoint the browser should open, session builds the same base, and disconnect has nothing to close, because the browser closes its own socket.

Telemetry freshness​

The browser maintains a monotonic receive timer for each selected drone. An open socket begins in connecting; an accepted telemetry or status frame makes the autopilot state current. Ten seconds without another accepted frame changes the session to disconnected with a stale-telemetry reason, without waiting for a WebSocket close event. A later valid frame restores it.

lastMessageAt is the browser receive time. The optional timestamp sent by the vehicle is stored separately and is used only to stop an out-of-order frame from overwriting newer telemetry. It never decides whether data is live, because clocks on the browser, Jetson and autopilot are not assumed to agree.

Commands and reads that require current vehicle state use the fresh session state. The remote link has no emergency bypass for stale telemetry; such a path would need separate authentication, acknowledgement and operating policy.

Remote access switch​

Each drone has a remote access switch (drones.remote_access_enabled), managed by Administrators and Operators in the drone's Setup tab or PUT /api/drones/{id}/remote-access. While it is off the Suite signs no new gateway token for that drone, and its remote SSH publication is withdrawn. The Suite refuses to sign for an unknown vehicle id as well.

Requests through Suite routes are refused at their next authorization check. Direct gimbal/zoom commands can still use a previously issued token until it expires or must be renewed; the configured token lifetime is 30–300 seconds, 120 by default. An open telemetry socket requests a new token every 60 seconds; a refusal closes it and reports that access was disabled. A contract-2 gateway also enforces the token expiry through telemetry-reauth.

An established WebRTC media session is not ended by a fresh Suite authorization check; it ends when the player/session closes. The switch is not an immediate kill switch for every existing connection and sends no flight command to the aircraft. The details are in docs/remote-link-security-boundary.md.

Reconnection and diagnosis​

The rules live in lib/drone-control-link.ts.

  • No polling over LTE. The page loads the stored connection and the session base once per selected drone. /api/drone-control/session is polled only while a bench transport runs inside the Suite process (connectionMode: "local"), one request at a time. Before this change every open tab asked for the same stored base every second: 3600 requests an hour.
  • Backoff with jitter. A failed token request or a closed WebSocket waits between half and all of 1 s × 2^attempt, capped at 30 s, and the count resets on the first accepted telemetry frame. Against an unreachable vehicle that is about 160 attempts an hour instead of 1200. The online browser event retries at once.
  • Refusals stop the retries. A token request answered 401 (the Suite session expired), 403 or 404 (the account no longer sees the vehicle or may not open the link) is not retried: asking again cannot change the answer.
  • One diagnosis. The vehicle's link indicator retains the diagnosis: Suite session expired, access denied, Suite unreachable, vehicle gateway unreachable, gateway reachable without autopilot data, or stale telemetry. The offline view keeps the map available and hides flight commands instead of presenting empty live instruments.
  • Sampled logs. Telemetry frames are logged at most once every 30 seconds, with the number of frames skipped; the token never appears in a log.

The bench transports​

Connecting straight to a vehicle over UDP or TCP uses node:dgram and node:net in the Node server. The path is behind DRONE_CONTROL_LOCAL_TRANSPORT_ENABLED and remains an opt-in bench transport; moving the Suite to Oracle does not turn it on.