Skip to content

FAROTECH/orbitfabric

BranchesTags

Repository files navigation

OrbitFabric

Model-first Mission Data Fabric for small spacecraft

Define telemetry, commands, events, faults, modes, packets, payload contracts, data products and operational scenarios once.
Validate them, document them, and execute deterministic mission scenarios from the same source of truth.

Overview

OrbitFabric is a model-first Mission Data Fabric for small spacecraft.

It lets teams define mission data contracts once, using a structured Mission Model, and then reuse that contract across validation, documentation, testing, simulation and future onboard/ground integration artifacts.

OrbitFabric is not a flight software framework, not a ground segment, and not a spacecraft dynamics simulator.

It is the contract layer between:

mission design
onboard software
simulation
testing
documentation
ground integration

Define once. Validate. Simulate. Test. Document. Integrate.

Current Status

OrbitFabric is currently at v0.3.0 — Data Product and Storage Contracts.

The current repository includes:

  • the v0.2.1 — Payload Contract Model vertical slice;
  • the v0.2.3 — Mission Data Chain Roadmap Alignment direction;
  • the v0.3.0 — Data Product and Storage Contracts vertical slice.

The current vertical slice is functional:

  • Mission Model YAML loading;
  • optional payloads.yaml loading;
  • optional data_products.yaml loading;
  • structural validation;
  • semantic linting;
  • engineering lint rules;
  • payload contract lint rules;
  • data product contract lint rules;
  • JSON lint report generation;
  • generated Markdown documentation;
  • generated payload contract documentation;
  • generated data product contract documentation;
  • scenario YAML loading;
  • scenario reference validation;
  • deterministic scenario execution;
  • minimal payload lifecycle simulation;
  • simulation JSON report generation;
  • simulation plain-text log generation;
  • synthetic demo mission: demo-3u.

Current verified baseline:

ruff check .
-> passing

pytest
-> passing

mkdocs build --strict
-> passing

What OrbitFabric Is

OrbitFabric is a Mission Data Contract framework.

It models:

  • telemetry;
  • commands;
  • events;
  • faults;
  • operational modes;
  • packets;
  • scenarios;
  • persistence and downlink policies;
  • optional Payload / IOD Payload Contracts;
  • optional Data Product and Storage Contracts.

A payload contract describes mission-specific or IOD payload behavior as a declarative contract. It may reference:

  • telemetry produced by the payload;
  • commands accepted by the payload;
  • events generated by payload activity;
  • possible payload faults;
  • lifecycle states;
  • command preconditions;
  • expected effects;
  • generated payload documentation.

A data product contract describes a mission-data object produced by a payload or subsystem. It may define:

  • producer reference;
  • product type;
  • estimated size;
  • priority;
  • storage intent;
  • retention intent;
  • overflow policy;
  • downlink intent;
  • generated data product documentation.

Payload and Data Product Contracts are part of the Mission Data Contract. They do not describe payload firmware, payload drivers, hardware buses, onboard services, physical payload simulation, real storage execution or real downlink runtime behavior.

From that model, OrbitFabric currently provides:

Mission Model YAML
        -> structural validation
        -> semantic lint
        -> JSON lint report
        -> generated Markdown docs
        -> scenario validation
        -> scenario loading
        -> deterministic scenario execution
        -> simulation JSON report
        -> simulation log file

Optional Payload Contract Model
        -> payload reference validation
        -> payload lifecycle validation
        -> payload documentation generation
        -> payload-aware scenario behavior

Optional Data Product Contract Model
        -> producer reference validation
        -> storage intent validation
        -> downlink intent validation
        -> data product documentation generation

What OrbitFabric Is Not

OrbitFabric is not:

  • a flight-ready onboard runtime;
  • a replacement for cFS or F Prime;
  • a replacement for Yamcs or OpenC3;
  • a spacecraft physics simulator;
  • a Basilisk alternative;
  • a CCSDS/PUS/CFDP implementation;
  • a hardware abstraction layer;
  • a CubeSat tutorial;
  • a ground segment;
  • a payload firmware framework;
  • a payload driver framework;
  • a payload physical simulator;
  • a payload data processing pipeline;
  • an onboard storage runtime;
  • a downlink runtime.

Those may become future integration targets or generated artifacts, but they are not part of the current development preview.

Demo Mission: demo-3u

The repository includes a synthetic clean-room demo mission:

examples/demo-3u/
├── mission/
│   ├── spacecraft.yaml
│   ├── subsystems.yaml
│   ├── modes.yaml
│   ├── telemetry.yaml
│   ├── commands.yaml
│   ├── events.yaml
│   ├── faults.yaml
│   ├── packets.yaml
│   ├── policies.yaml
│   ├── payloads.yaml
│   └── data_products.yaml
└── scenarios/
    └── battery_low_during_payload.yaml

The demo includes a synthetic IOD payload contract:

demo_iod_payload
        subsystem: payload
        profile: iod
        lifecycle: READY -> ACQUIRING -> READY

The demo also includes one synthetic payload data product:

payload.radiation_histogram
        producer: demo_iod_payload
        type: histogram
        estimated size: 4096 bytes
        storage: science, retention 7d, drop_oldest
        downlink: next_available_contact

This demonstrates the relationship:

Payload Contract
        -> Data Product Contract
        -> Storage Intent
        -> Downlink Intent

The demo contains:

  • OBC mock;
  • EPS mock;
  • Payload mock;
  • Radio mock;
  • modes: BOOT, NOMINAL, PAYLOAD_ACTIVE, DEGRADED, SAFE, MAINTENANCE;
  • one executable scenario: battery_low_during_payload.

The scenario demonstrates:

payload.start_acquisition
→ payload.acquisition_started
→ NOMINAL → PAYLOAD_ACTIVE
→ battery voltage degradation
→ eps.battery_low
→ PAYLOAD_ACTIVE → DEGRADED
→ payload.stop_acquisition automatically dispatched
→ payload.acquisition_stopped
→ payload.acquisition.active = false
→ SCENARIO PASSED

Installation for Local Development

Create and activate a Python virtual environment:

python3 -m venv .venv
source .venv/bin/activate
python -m pip install --upgrade pip
python -m pip install -e ".[dev]"

Verify the CLI:

orbitfabric --version
orbitfabric --help

Expected:

orbitfabric 0.3.0

Run Mission Lint

Run semantic mission linting:

orbitfabric lint examples/demo-3u/mission/

Generate a machine-readable lint report:

orbitfabric lint examples/demo-3u/mission/ \
  --json generated/reports/lint_report.json

Expected result:

Result: PASSED

Generated artifact:

generated/reports/lint_report.json

Generate Mission Documentation

Generate Markdown documentation from the Mission Model:

orbitfabric gen docs examples/demo-3u/mission/

Generated files:

generated/docs/
├── telemetry.md
├── commands.md
├── events.md
├── faults.md
├── modes.md
├── packets.md
├── payloads.md
└── data_products.md

These files are generated from the validated Mission Model. Do not edit them manually.

Run Scenario Simulation

Run the demo scenario:

orbitfabric sim examples/demo-3u/scenarios/battery_low_during_payload.yaml

Generate both a JSON report and a plain-text timeline log:

orbitfabric sim examples/demo-3u/scenarios/battery_low_during_payload.yaml \
  --json generated/reports/battery_low_during_payload_report.json \
  --log generated/logs/battery_low_during_payload.log

Expected result:

Result: PASSED

Example timeline excerpt:

[00:00] MODE=NOMINAL
[00:05] COMMAND payload.start_acquisition -> ACCEPTED
[00:05] EVENT payload.acquisition_started severity=INFO
[00:05] MODE TRANSITION NOMINAL -> PAYLOAD_ACTIVE reason=payload.acquisition_started
[00:30] INJECT eps.battery.voltage=6.7
[00:31] INJECT eps.battery.voltage=6.7
[00:32] INJECT eps.battery.voltage=6.7
[00:32] EVENT eps.battery_low severity=WARNING
[00:32] MODE TRANSITION PAYLOAD_ACTIVE -> DEGRADED reason=eps.battery_low_fault
[00:32] COMMAND payload.stop_acquisition -> AUTO_DISPATCHED
[00:32] EVENT payload.acquisition_stopped severity=INFO
[00:40] SCENARIO PASSED

Generated artifacts:

generated/reports/battery_low_during_payload_report.json
generated/logs/battery_low_during_payload.log

Run Tests

ruff check .
pytest
mkdocs build --strict

Current expected baseline:

ruff check .           -> All checks passed
pytest                 -> passing
mkdocs build --strict  -> passing

Generated Artifacts

The current vertical slice can produce:

generated/
├── docs/
│   ├── telemetry.md
│   ├── commands.md
│   ├── events.md
│   ├── faults.md
│   ├── modes.md
│   ├── packets.md
│   ├── payloads.md
│   └── data_products.md
├── reports/
│   ├── lint_report.json
│   └── battery_low_during_payload_report.json
└── logs/
    └── battery_low_during_payload.log

Generated artifacts are reproducible outputs. They are not the source of truth.

The source of truth remains:

examples/demo-3u/mission/*.yaml
examples/demo-3u/mission/payloads.yaml
examples/demo-3u/mission/data_products.yaml
examples/demo-3u/scenarios/*.yaml

Repository Layout

orbitfabric/
├── assets/
│   └── brand/
│       ├── orbitfabric-icon.png
│       ├── orbitfabric-logo-horizontal-light.png
│       ├── orbitfabric-logo-horizontal-dark.png
│       └── orbitfabric-social-preview.png
├── docs/
├── examples/
│   └── demo-3u/
├── src/
│   └── orbitfabric/
├── tests/
└── generated/

Documentation

Published documentation is available at:

https://farotech.github.io/orbitfabric/

Project documentation lives under:

docs/

Useful entry points:

  • docs/PROJECT_CHARTER.md
  • docs/CLEAN_ROOM_POLICY.md
  • docs/ARCHITECTURE.md
  • docs/ROADMAP.md
  • docs/DEVELOPMENT.md
  • docs/reference/mission-model-v0.1.md
  • docs/reference/payload-contract-model.md
  • docs/reference/data-product-contract-model.md
  • docs/adr/

Build the documentation site locally:

mkdocs build --strict

Preview locally:

mkdocs serve

Clean-Room Policy

OrbitFabric is developed as a clean-room open-source project.

Do not add:

  • proprietary mission data;
  • private architectures;
  • private protocols;
  • real operational logs;
  • non-public payload details;
  • real bus maps;
  • real pinouts;
  • employer/customer-owned code;
  • NDA-protected material.

All examples must be synthetic or based on public information.

See:

docs/CLEAN_ROOM_POLICY.md

Contributing

Contributions should stay aligned with the Mission Data Contract architecture.

Before contributing, read:

CONTRIBUTING.md

Required local checks:

ruff check .
pytest
mkdocs build --strict

Also verify the demo vertical slice:

orbitfabric lint examples/demo-3u/mission/ \
  --json generated/reports/lint_report.json

orbitfabric gen docs examples/demo-3u/mission/

orbitfabric sim examples/demo-3u/scenarios/battery_low_during_payload.yaml \
  --json generated/reports/battery_low_during_payload_report.json \
  --log generated/logs/battery_low_during_payload.log

License

OrbitFabric is licensed under the Apache License 2.0.

See:

LICENSE

About

Model-first Mission Data Fabric for small spacecraft.

Topics

python open-source yaml simulation spacecraft telemetry commands cubesat mission-data fault-management

Resources

Readme

License

Apache-2.0 license

Contributing

Contributing
Activity

Stars

2 stars

Watchers

0 watching

Forks

0 forks
Report repository

Releases 3

OrbitFabric v0.3.0 — Data Product and Storage Contracts Latest
May 1, 2026
+ 2 releases

Packages

 
 
 

Contributors

Languages