Skip to main content

Your own connector

Your mission control system (MCS), ground station software or scheduler is not one of ours? Write a connector for it. It is one small program next to your system: it pulls your account's workflow results from Constellation and writes what workflows forecast into your system, the way the Yamcs, COSMOS and Lattice connectors do. It belongs to your account alone: no other Constellation account ever sees it. Delivering to your own connector needs the Operator plan.

your network Constellation (your account only)
───────────────────────────── ──────────────────────────────────────
your bridge + connector.json ─ 1. checks in with its manifest ──▶ "My MCS asks for
│ your results"
│ 2. someone approves it in the Platform
│ 3. a workflow sends it results (an output)
│ ◀── 4. pulls results as its connection ───
▼
your system's API ── 5. reports what it wrote ──▶ the Platform shows it Live, and what it wrote

1. Start from a scaffold​

constellation bridge new my-mcs-bridge --lang python # or ts, or go
cd my-mcs-bridge
pip install --require-hashes -r requirements.txt # npm ci for ts, go mod tidy for go

The constellation CLI writes a working bridge: the bridge itself, built on the Bridge base class of the SDK (the results protocol, done), connector.json (your manifest), a test and a Dockerfile. You write two functions: apply(), which writes a run's items into your system, and act(), which carries out an approved action. Build a connector walks through it in Python, TypeScript and Go. In another language, or without the SDK, Receive results is the same loop over plain HTTP.

2. Write the manifest​

connector.json names your connector and the settings an operator sets per workflow.

{
"name": "my-mcs-bridge",
"title": "My mission control",
"description": "Forecast passes proposed into my mission control's schedule.",
"version": "0.1.0",
"settings": {
"min_p10_gb": {"type": "number", "title": "Only passes forecast to deliver at least (GB, p10)", "default": 0, "minimum": 0, "maximum": 10000},
"label": {"type": "string", "title": "Label on what the bridge writes", "default": "Constellation forecast", "max_length": 80},
"show_swaps": {"type": "boolean", "title": "Write rain-fade swap advice", "default": true}
}
}
FieldRule
nameYour connection's name and the bridge's consumer: lowercase letters, digits and -, at most 63 characters. Workflows send results to it by this name.
title, descriptionWhat the workflow builder shows: 1 to 80 characters, and up to 300
versionYour bridge's version. The bridge sends it as bridge_version and keeps it out of the manifest it checks in with.
settingsUp to 20, keyed in lowercase snake_case. The workflow builder draws a form from them on each workflow's output.

Each setting has a type, a title (up to 80 characters), a default, and optionally a description (up to 300):

typeTakesBounds
numberAny numberminimum, maximum
integerA whole numberminimum, maximum
booleantrue or false
stringTextmax_length: default 200, at most 2,000
enumOne of options, 1 to 20 strings

The default must be a valid value. Constellation checks every workflow's settings against your manifest when the workflow is saved and fills in the defaults for any left out, so your bridge always receives every setting, typed as declared.

Use a setting for what can differ per workflow. Keep what is fixed per install, such as your system's URL and token, in your bridge's own configuration. For something per site, such as which of your antennas a Constellation antenna is, use a string setting your bridge parses, for example comma-separated constellation_id=your_id pairs.

3. Check in, then approve​

On start the bridge checks in with POST /predictions/feed/checkin as a custom connector:

{"consumer": "my-mcs-bridge", "system": "custom", "manifest": {"name": "my-mcs-bridge", "title": "...", "description": "...", "settings": {"...": {}}}, "bridge_version": "0.1.0", "target": "My mission control"}
  • A name the account has not seen registers the connector as pending. Integrations, Results out lists it as Waiting for approval, and the builder's Deliver to as "My mission control asks for your results", each with Approve and Remove.
  • Approving needs a person or key that may edit workflows. The bridge's own key, with only predictions:read, can propose a connector, never enable one.
  • A changed manifest, such as a new setting or a changed bound, sends it back to pending, so an operator approves what it now asks for. Checking in with the same manifest changes nothing.
  • It lives in the account the key belongs to. Another account never sees it, cannot approve it, and cannot send it a workflow's results.
  • Until it is approved, a workflow cannot add it as an output, so no results are sent to it; the bridge keeps polling.

To approve and remove from code: POST /predictions/connectors/{name}/approve with the manifest_sha256 you were shown (409 manifest_changed when the bridge has since sent another), and DELETE /predictions/connectors/{name}. GET /predictions/connectors lists them under custom.

4. What apply() receives​

The base class pulls results as your connection and hands apply() each run:

  • items: the run's results in the constellation.item/v2 shape. A forecast pass has entity.type pass, its satellite, antenna and station ids, target_at (AOS), until (LOS), value (expected GB as p10, p50 and p90), explain (each step's numbers) and entity.track (the ground under the satellite from AOS to LOS). A rain-fade swap is a pass with an action. With an approve policy an item also carries action_status (approved, pending or rejected; see the protocol). Write every item in apply(); carry out actions only in act(), which receives each approved action once, after apply(), and never one in any other state.
  • settings: your manifest's settings as the workflow set them, every one present.
  • run: the workflow, its version, the run, and the window it answers for (window_from, window_to). The run is the whole answer for that window: what you wrote for the same workflow inside it that items no longer carries is withdrawn.

apply() returns what it wrote, such as {"passes": 12}. The base class reports it after each run, and the workflow builder shows it on the workflow's output.

5. Rules for what you write​

These keep a forecast from ever being mistaken for your own data.

  1. Never write over your own objects. Write forecasts where your system keeps proposals, plans or forecasts, or as new objects of your own, clearly labelled.
  2. Propose, never schedule. A forecast pass goes in as proposed, or your system's equivalent; an operator promotes it.
  3. Label forecasts as forecasts. Name, tag or source everything so an operator reads it as Constellation's forecast at a glance.
  4. Key writes on entity.id. A rerun updates what the last run wrote, in place, and withdraws what it no longer carries in its window.
  5. What an operator took is theirs. Once an operator schedules or otherwise takes over a forecast you wrote, stop updating or withdrawing it.
  6. Retry what may succeed, skip what never will. Raise when your system is unreachable or failing (5xx): the base class retries that run on the next poll and never moves past it. Skip an item your system refuses for good (4xx) and count it in what you report, such as {"refused": 1}, so one bad item never stops the results.

6. Check it, then go live​

constellation conformance -- python bridge.py

The conformance check runs your bridge against a mock Constellation API on your machine, kills it and starts it again. Point the bridge at a test instance of your system: apply() and act() really run. It checks, from the outside, that the bridge checks in with a valid manifest, pulls as its own connection, survives a failed poll, reports each run it applied once, starts at the newest run on a first start, never reports a run in an item shape it was not built for, acts on each approved action exactly once and on nothing else, never past its cancel deadline, acts again on a new approval of the same action, and resumes from its cursor after a restart without acting again. It prints conformant when every check passes. What conformance checks lists all 21.

Then run the bridge against Constellation with a live key that has predictions:read, approve it in the workflow builder, add it as an output to a workflow, and run the workflow.

Contributing a connector​

A connector for your own system needs nothing from us but the CLI and an SDK. To add a system Constellation ships to everyone, open a pull request on the connectors repository. Start from the Yamcs or Lattice bridge, in clients/python/src/constellation_space/bridges/, and follow the same rules: pull from the cursor you last applied and keep it in the target system, read only your connection's resources and the item schema you were built for, write idempotently on entity.id, check in and report deliveries, and never fail the loop. It must pass constellation conformance.

Sign off every commit (git commit -s, the Developer Certificate of Origin). The contract comes from Constellation's API as a pinned release, its files under contract/ and their hashes in contract.lock: to propose a change to it, open an issue, and we make it upstream. Report a security problem privately to security@constellation.space, never in a public issue.