Yamcs
Workflow forecasts appear in your Yamcs as events, timeline items and parameters, and on a Constellation Forecast page. A bridge next to Yamcs pulls them from Constellation and writes them through Yamcs's API. Delivering to Yamcs needs the Operator plan.
| Constellation sends | In Yamcs |
|---|---|
| Each result that spans time, such as a pass or a MODCOD plan | A timeline item in the workflow's band, in the "Constellation forecast" view. A rerun updates the same item. |
| Each result as a line someone reads | An event, source Constellation forecast unless the workflow changes it. Swaps are WARNING. A swap approved in Constellation starts "Approved in Constellation:" and is at least WARNING; one held for approval writes no event (tagged awaiting-approval on the timeline when it is on), and a rejected one writes no event (its timeline item is re-tagged rejected). |
| The next pass and the next 24 hours | Parameters under /ConstellationForecast/ |
| The whole run, with its ledger | The Constellation Forecast page |
What each workflow writes is set on its mission control output in the workflow builder: which of these objects, their names and messages, and when an event is a WARNING. The defaults per template are what the table above describes. Everything the bridge writes is labelled a forecast, and its parameters sit in their own ConstellationForecast system, so nobody mistakes a predicted pass for a scheduled contact or measured telemetry.
1. Install
Download yamcs-constellation-<version>.tar.gz from Downloads and unpack it. It holds constellation-yamcs.jar, which carries Constellation's ten parameters and the Constellation Forecast page, and compose.yaml and .env.example for the bridge.
-
Copy
constellation-yamcs.jarinto Yamcs'slib/ext/. -
Restart Yamcs. The jar adds the
/ConstellationForecastparameters to every instance by itself, with no configuration:GET /api/mdb/<instance>/parameters?system=/ConstellationForecastlists ten. -
Beside the unpacked
compose.yaml, save.env.exampleas.envand fill it in once:CONSTELLATION_API_KEY(a live key withpredictions:read),YAMCS_URL(where the bridge reaches Yamcs, such ashttp://yamcs:8090) andYAMCS_INSTANCE(the instance it writes into). Then:docker compose up -dCompose reads
.envon every laterup,restartor recreate, so nothing needs exporting in the shell. All three are required: compose stops and names the one missing. For an enterprise API, addCONSTELLATION_API_URLto.env. The bridge keeps its state in a named volume at/var/lib/constellation. Add any other variable below to the compose file'senvironment.
The parameters are dataSource="local", the only kind Yamcs accepts values for over its API. Without them events and timeline items still arrive, but parameters are refused.
An instance restarted on its own from Yamcs's admin page, rather than Yamcs as a whole, reloads its mission database without the parameters. To keep them through that, also add the loader to the instance's mdb list in etc/yamcs.<instance>.yaml:
mdb:
# ... your existing loaders ...
- type: "space.constellation.yamcs.ConstellationMdb"
Your instance needs org.yamcs.timeline.TimelineService among its services for timeline items.
2. The bridge
The bridge is published as the image ghcr.io/constellationhq/yamcs-bridge (amd64 and arm64), as yamcs-bridge.pyz, one file that runs with Python 3.11 or newer, and in the Python SDK. It runs as a non-root user. The compose file pins the version it was released with.
Without Docker, set the same variables and run it from the Python SDK with the CLI, or from the single file:
pip install constellation-space
constellation bridge run yamcs # or: python3 yamcs-bridge.pyz
| Variable | Value |
|---|---|
CONSTELLATION_API_URL | https://api.constellation.space, or your enterprise API. Plain http only to this machine (localhost): the bridge stops at start rather than send the key over plain http to another host. |
CONSTELLATION_API_KEY | A live key with predictions:read |
YAMCS_URL | Your Yamcs, as the bridge reaches it, such as http://yamcs:8090 |
YAMCS_INSTANCE | Your instance name |
YAMCS_PROCESSOR | realtime unless you use another |
CONSUMER | This connection's name, yamcs-bridge unless you run more than one Yamcs. A workflow's mission control output names it. |
YAMCS_CLIENT_ID, YAMCS_CLIENT_SECRET | When Yamcs has security on: a Yamcs service account for the bridge. Or YAMCS_USERNAME and YAMCS_PASSWORD. |
CREATE_VIEWS | 0 stops the bridge creating its bands, the "Constellation forecast" timeline view and the parameter list |
POLL_SECONDS | How often it reads results. Default 15. |
STATE_DIR | Where the bridge keeps its state: its results position and the approved actions it announced. /var/lib/constellation in the image, a volume; outside it, constellation in your user state folder ($XDG_STATE_HOME, or ~/.local/state). |
ACTED_FILE | Where the bridge keeps the approved actions it has announced, so a later run or a restart never writes an action's event twice. Default yamcs-bridge-acted.txt in STATE_DIR. |
YAMCS_URL is resolved inside the container. When Yamcs runs in Docker, put the bridge on its network and use its container name; when it runs on the host, use http://host.docker.internal:8090 (on Linux, add extra_hosts: ["host.docker.internal:host-gateway"] to the service).
Give the bridge's Yamcs account only what it writes: WriteEvents, ControlTimeline, WriteParameter on /ConstellationForecast/*, and ManageBucket on the constellation bucket for the page. The Yamcs credentials stay in your network.
The bridge needs outbound HTTPS to Constellation and HTTP to Yamcs, nothing inbound. It keeps the last results position it applied in STATE_DIR, and also in the /ConstellationForecast/feed_cursor parameter, so a restart resumes where it stopped, and a first start applies the newest run. ACTED_FILE is on the same volume, so a recreated container never announces an approved action twice. The bridge checks in again every 5 minutes, so the Platform can tell it is still running.
3. Send a workflow to Yamcs
On Integrations, Results out, choose Add connection, then Yamcs (or open its row once it is in Connections). Under Send, pick the workflow and choose Send Pass yield to Yamcs (the button names both): it saves a new version of the workflow with a Yamcs output, wired from the step that feeds /predictions, and the right pane then says the workflow sends its results to Yamcs. Its connection is yamcs-bridge; if you set another CONSUMER, set the same connection on the output. The output turns Live once the bridge checks in.
4. The Constellation Forecast page
The jar also adds a Constellation Forecast page to the Yamcs web interface. It shows each workflow's latest run with the layout the workflow chose: summary tiles, swap warnings with their cancel-by time, the results, and the ledger for the one selected. It reads the constellation bucket the bridge writes, through the operator's own Yamcs session.
After the restart, GET /api lists the plugin constellation-yamcs, and the bridge reports the page as installed at its next check-in. The page uses Yamcs's web extension hook, which Yamcs marks experimental.
To see the forecasts in Open MCT as well, add the Open MCT plugin.
Check it works
- Run a workflow with the Yamcs output.
GET /predictions?run_id=saysdone. - Within one poll, 15 seconds by default, the bridge logs
applied {...}, cursor <cursor>, counting what it wrote (events, timeline items, parameters). - In Yamcs, Events shows one
Constellation forecastevent per pass, Timeline shows the passes, and/ConstellationForecast/next_pass_expected_gb_p50has a value.
How it fails
- Yamcs refuses a write. The bridge logs which one. At check-in it tells Constellation what its account may write and whether the page is installed, and the workflow builder shows both.
- An output it cannot apply, for another system or a mapping version newer than it reads, is skipped, logged and reported as
refused. The runs after it still apply. - The bridge was offline for more than 7 days. Its cursor is older than the oldest run Constellation holds. The log says the runs in between expired unread, and the bridge reads on from the oldest.
- Yamcs restarted without persistent storage. At its next poll the bridge applies each workflow's newest run again, so the page, timeline and parameters come back without waiting for a run.
- Parameters show the refresh time, not the pass time. Yamcs stamps a parameter set over the API with the time it was set.