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):
| Name | Where | Used by | Rule |
|---|---|---|---|
| Suite id | drones.id | every table, page and API path of the Suite | a UUID; never shown, never sent to the vehicle |
| gateway id | connections.drone_id | the runtime on the vehicle (DRONE_ID), the drone_id claim of every token, the /drones/:id/ segment of every path | the one name the vehicle answers to; unique across vehicles; letters, digits and hyphens |
| serial number | drones.serial_number | people | free text, as printed on the airframe |
| hostname | the host of connections.server_ws | the browser and Cloudflare | where 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/telemetryand 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.
| Claim | Meaning |
|---|---|
aud | sabrobotix-jetson-gateway |
sub | the Suite user the request is made for |
drone_id | the one vehicle this token is good for |
exp | 30 to 300 seconds after issue, 120 by default |
| permissions | telemetry: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/sessionis 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. Theonlinebrowser 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.