Skip to main content

Building with the Platform SDK

The Platform SDK lets you build applications, data services, and hardware integrations on top of GAMA and Lookout through one curated, versioned API — without coupling to their internals.

A single typed contract​

The API is defined once in Protobuf and published to the Buf Schema Registry (BSR) — the source of truth for every client, in every language. Because the contract is strongly typed, the same definitions drive Python, C++, and TypeScript clients identically, and incompatible changes surface at the schema level rather than at runtime.

gRPC over one connection​

All communication is gRPC over a single TLS connection:

  • Unary calls change the vessel or read a value once — set a mode, fetch the latest state. Each returns a success/failure result.
  • Server streams deliver live data — vessel state, tracks, mission progress. Open the stream once; the first message carries the current value and updates follow on change.

This is efficient over constrained, intermittent maritime links and traverses firewalls and NAT as ordinary HTTP/2 traffic.

The vessel is the unit​

Every call is scoped to a vessel by a stable vessel_id (e.g. "vessel_1"). A single endpoint may serve one or more vessels; you select the vessel per request.

The server is authoritative​

The platform validates commands and owns the truth. A mission plan, for example, is fully checked when you load it and the result is returned to you — treat the server's response, not your local assumptions, as authoritative.

Forward-compatible by design​

The schema is versioned (see Versioning). New fields are added compatibly and unknown fields are ignored by older clients, so build defensively: tolerate fields you don't recognise and absent optional values. Coordinate frames and units follow the reference conventions.

Where the code comes from​

You never hand-write client code or copy .proto files. The BSR hosts pre-generated, versioned SDKs — Python and TypeScript install straight from it; C++ is a single buf generate. See Install.

The shape of an integration​

A typical integration opens an authenticated channel, subscribes to the streams it needs (vessel state, perception tracks, mission state), and commands the vessel through unary calls. From there, the domain guides walk through each surface.