trevor16gordon/flatsat

Purpose and deployment target

flatsat is a distributed flat-satellite testbed: Python flight software runs on a Jetson Orin Nano with a PREEMPT_RT kernel, connects to real or simulated devices, and supports a ground physics simulator plus two ADALM-Pluto SDRs. Its central demonstration is telemetry-driven ML-policy retraining, RF uplink during contacts, A/B-slot activation, and rollback. The deployable package is flatsat/; systemd units define the flight composition in units/generated/flatsat.target and units/flatsat-router.service.

Entry points and process composition

Applications are independently runnable daemons rather than a monolithic service. The principal operational processes are the sensor and actuator daemons, ADCS loop, FDIR, mode manager, telemetry recorder, link service, and uplink service:

• flatsat/apps/sensor_daemon.py

• flatsat/apps/control_loop.py

• flatsat/apps/actuator_daemon.py

• flatsat/apps/fdir.py

• flatsat/apps/link_service.py

• flatsat/apps/uplink_service.py

• flatsat/sim/run_mission.py

Core contracts, runtime bus, and configuration

The internal architectural boundary is typed protobuf messages over a shared runtime/bus, plus registries that resolve config-selected implementations. Common message contracts cover ADCS, HAL, health, telemetry, link, mode, and uplink domains:

• flatsat/core/bus.py

• flatsat/core/registry.py

• flatsat/core/rt.py

• flatsat/msgs/adcs.proto

• flatsat/msgs/hal.proto

• flatsat/vehicle.proto

Vehicle configuration declares physical properties, devices, estimators, controllers, and objectives. Device, mission, orbit, and vehicle files make system composition data-driven, allowing sim/bench/hardware substitutions without changing downstream loops:

• config/vehicles/flatsat_v1.txtpb

• config/devices/imu0.txtpb

• config/missions/detumble_3d.txtpb

Hardware abstraction and simulation

Sensor and actuator interfaces isolate applications from physical, synthetic, and Basilisk-backed implementations. Drivers publish the same typed messages regardless of source. The simulator constructs the plant and scenario from the same vehicle-oriented configuration boundary used by flight software:

• flatsat/hardware/sensor.py

• flatsat/hardware/actuator.py

• flatsat/hardware/drivers/basilisk_imu.py

• flatsat/sim/plant.py

• flatsat/sim/basilisk_hil.py

• flatsat/sim/scenario.py

ADCS control pipeline

The control loop consumes sensor state, applies an estimator and guidance/controller selection, then emits actuator commands. Available attitude-control implementations include B-dot detumble, momentum dumping, pointing, PID/rate damping, and an ML policy; these are selected through controller configuration rather than separate loops:

• flatsat/control/attitude/controller.py

• flatsat/control/attitude/guidance.py

• flatsat/control/attitude/estimators/triad.py

• flatsat/control/attitude/controllers/bdot.py

• flatsat/control/attitude/controllers/ml_policy.py

Modes, health, and fault containment

Mode management governs operational-state transitions and accepts requests from system actors. FDIR forms a sense-decide-act boundary: health rules evaluate valid/invalid telemetry, an arbiter groups/common-causes faults, and responses can restart, reconfigure, or request Safe mode. Safe behavior is intended to remain in the base flight release rather than be hot-swapped:

• flatsat/mode/machine.py

• flatsat/mode/manager.py

• flatsat/control/health/rules.py

• flatsat/control/health/arbiter.py

• flatsat/core/health.py

Communications, uplink, and telemetry lifecycle

The RF stack is store-and-forward and contact-scheduled rather than middleware tunneling. It layers slot scheduling, CCSDS framing/randomization/FEC, a swappable PHY/modem contract, and uplink handling; supported PHYs include loopback, KISS, and Pluto GMSK. Telemetry is recorded/exported with mission logs, providing the source material for analysis and ML retraining:

• flatsat/comms/link.py

• flatsat/comms/slots.py

• flatsat/comms/framing/ccsds.py

• flatsat/comms/phy/pluto_gmsk.py

• flatsat/comms/uplink.py

• flatsat/telemetry/recorder.py

• flatsat/telemetry/mission_log.py