Skip to main content

Connecting to a vessel

Every integration opens one authenticated gRPC channel to a Platform endpoint and reuses it for all calls. This page covers where that endpoint comes from, the environments you might connect to, and the TLS options you need for on-vessel and local-network deployments.

Before you begin

You need a PLATFORM_ENDPOINT and a PLATFORM_TOKEN, and a channel set up as shown in Authenticate.

Endpoint format​

A Platform endpoint is a host:port pair:

platform.example.greenroomrobotics.com:443

The host resolves to a specific deployment; the port is the TLS gRPC port. A single endpoint may serve one or more vessels, which you select per request with a vessel_id.

Finding your vessel_id

Calls are scoped to a vessel by a stable vessel_id (e.g. "vessel_1"). The IDs a given endpoint serves are provisioned for your integration — confirm them through your Greenroom engagement.

Environments​

Coordinate the endpoint for each environment through your Greenroom engagement.

Confirm with Greenroom

Which environments are available to you — for example a hosted simulator versus a physical vessel — and their endpoints, ports, and vessel_ids are provisioned per engagement. Confirm these details with your Greenroom contact.

A common progression is to build and test against a simulator (simulated vessel state, perception, and mission execution) before connecting to a physical vessel on its own network. The SDK and your code are identical across both; only the endpoint changes.

TLS​

The Platform API is always served over TLS. How you configure trust depends on the deployment.

Public endpoints (CA-signed certificates)​

Standard TLS: the default channel credentials trust the system root certificates, so the setup in Authenticate needs no changes.

On-vessel or local-network endpoints (self-signed certificates)​

A vessel on a private network often presents a certificate signed by a private CA. Provide that CA certificate to the channel so verification still succeeds:

auth.py
import grpc, os

with open("vessel-ca.pem", "rb") as f:
    root_certs = f.read()

channel_creds = grpc.composite_channel_credentials(
    grpc.ssl_channel_credentials(root_certificates=root_certs),
    grpc.access_token_call_credentials(os.environ["PLATFORM_TOKEN"]),
)
channel = grpc.secure_channel(os.environ["PLATFORM_ENDPOINT"], channel_creds)
Don't disable verification

Obtain the vessel's CA certificate rather than turning off certificate verification. Disabling verification exposes the connection — and the credentials it carries — to interception. Treat it, at most, as a temporary local-debugging measure, never a deployed configuration.

Reuse one channel​

Open the channel once and share it across every service stub, rather than opening a channel per call. A gRPC channel multiplexes all RPCs — unary and streaming — over a single HTTP/2 connection, which is exactly what you want over a constrained link.

What's next​