Skip to main content

OpenC3 COSMOS

Workflow forecasts arrive in COSMOS as telemetry of a CONSTELLATION target, so Telemetry Viewer, Telemetry Grapher, Limits Monitor and Data Extractor show them, and as the Constellation Forecast tool in COSMOS's navigation. Every value is a forecast: predicted passes and recommendations, not measured telemetry. Delivering to COSMOS needs the Enterprise plan.

PacketWhat it holdsFilled by
NEXT_PASSThe next predicted pass: satellite, antenna, AOS and LOS, expected GB p10 to p90, peak elevationA pass-yield run
NEXT_24HPredicted passes and expected GB over the next 24 hoursA pass-yield run
SWAPThe soonest rain-fade swap: the pass at risk, what it keeps if it rains, the backup to book, the cancel-by time and minutes left (yellow under 30, red under 15); STATUS says whether it was approved in Constellation (APPROVED) or only advised (ADVISED), APPROVED counts approved swaps open and PENDING those held for approvalA rain-fade-swap run. One advising nothing clears it.
CAPACITYOne day's capacity across the antennas, and the tightest antennaAn antenna-capacity run
MODCODThe next pass's MODCOD plan: its changes, the MODCOD at AOS and LOS, and the lowest planned SINRA modcod-plan run
RUNThe workflow, version and run the values came fromEvery run

Each kind of workflow fills its own packets and replaces only them.

How it works​

The openc3-cosmos-constellation plugin carries the packet definitions, the tool, and a bridge microservice. The bridge pulls your workflow results from Constellation outbound over HTTPS and injects the packets; nothing connects into your network, and the API key stays in COSMOS's secrets. It re-injects the packets every 15 seconds, so NEXT_PASS and the minutes left keep moving, and it reports to Constellation what it wrote, which the workflow builder shows. It signs in to the COSMOS API with COSMOS's own service password, so there is nothing to configure for that.

The bridge keeps the last results position it applied, and the forecast it held, in COSMOS's config bucket (<SCOPE>/constellation/bridge-<consumer>.json), so a restart or upgrade resumes with the same packets and never injects an older run again. A first install applies only the newest run for its connection; each other workflow's packets fill in with its next run.

Install​

Not tested in a COSMOS: CI builds the gem and unit tests the bridge's Python, but never installs it into COSMOS.

  1. In COSMOS, Admin › Secrets: add CONSTELLATION_API_KEY, a live Constellation key with predictions:read. Plugin variables cannot hold a secret, so the key goes in COSMOS's own secret store. This is the only place you type the key; to script it, COSMOS's secrets API takes it from a file or a pipe. The bridge reads it at each poll, so a key added or changed later is used within a minute.

  2. Download openc3-cosmos-constellation-<version>.gem from Downloads, or from RubyGems with gem fetch openc3-cosmos-constellation -v <version>. COSMOS installs a plugin only from an uploaded .gem file.

  3. Admin › Plugins › Install: upload the gem and set constellation_api_url (https://api.constellation.space, or your enterprise API), and consumer if you run more than one COSMOS.

    From a shell instead, in your COSMOS project folder (the one with openc3.sh) with the gem and variables.json copied into it, since the CLI container sees only that folder: ./openc3.sh cli load openc3-cosmos-constellation-<version>.gem --variables variables.json, with {"constellation_api_url": "https://api.constellation.space"} in variables.json.

  4. On Integrations, Results out, choose Add connection, then OpenC3 COSMOS (or open its row once it is in Connections). Under Send, pick the workflow and choose Send Pass yield to OpenC3 COSMOS (the button names both): it saves a new version of the workflow with the output, wired from the step that feeds /predictions. It is a mission control output whose connection is cosmos-bridge; if you set another consumer, set the same connection on the output. It shows Live once the bridge checks in.

The output saves on the workflow's graph as:

{"id": "cosmos", "kind": "output", "ref": "feed", "params": {"columns": ["expected_gb"], "sort": [], "connection": "cosmos-bridge", "mapping": {"system": "cosmos"}, "widget": null}}

Every workflow sent to COSMOS also appears in the Constellation Forecast tool, whatever its kind.

The Constellation Forecast tool​

The same view as the Yamcs page and the Open MCT plugin, in COSMOS's dark theme. Overview shows every workflow that delivers to this COSMOS, by category; each workflow also has its own page (/tools/constellationforecast/<workflow>). Per workflow: headline tiles, expected GB over the next 24 hours, where the GB lands per antenna, the swaps to decide, every result in a table, and the ledger for the selected row.

The tool reads only from COSMOS. For each run the bridge writes workflow-<workflow>.json and an index.json into COSMOS's config bucket under <SCOPE>/constellation/, and the tool reads them through COSMOS's storage API with the operator's own COSMOS session. No Constellation key reaches the browser.

Check it works​

  • Admin › Microservices lists DEFAULT__USER__CONSTELLATION-BRIDGE as RUNNING. Its log lines (constellation-bridge: injected <n> packets, <cursor> for each run it applied) are in the COSMOS operator container's log (docker logs of openc3-operator), not on that page.
  • Packet Viewer, target CONSTELLATION: the packets have values and a recent received time.
  • Constellation Forecast in the navigation shows the workflows. Bucket Explorer, config bucket, DEFAULT/constellation/ holds index.json and a workflow-<workflow>.json per workflow.
  • In the workflow builder on the Automations tab, the COSMOS output shows as checked in.

How it fails​

  • constellation_api_url is plain http to another machine. The bridge stops at start and says so: it sends the key only over https, or plain http to this machine. Install the plugin again with an https URL.
  • No key. The microservice log says so once a minute and the bridge waits. Add the secret.
  • Constellation rejects the key. The log says why once, and the bridge stops polling until the secret changes or the plugin restarts. Fix the secret.
  • Rate limited, locked out or out of plan (429 or 402). The log says why once and the bridge waits it out, so it never locks out the address.
  • The bridge was offline for more than 7 days. The log says the runs in between expired unread, and the bridge reads on from the oldest run Constellation holds.
  • A check-in Constellation did not take is tried again at the next poll.

The plugin uses COSMOS Core features only: targets, microservices, tools, buckets and secrets. COSMOS is licensed under the OpenC3 Builder's License; check your use with OpenC3.