# Autonomic Satellite Swarm

> A revived C++ research prototype for fail-safe coordination across hardware-independent satellite-swarm agents

- HTML version: https://robbiepalmer.me/projects/autonomic-satellite-swarm
- Status: in_progress
- Started: 2019-07-30
- Updated: 2026-10-09
- Source code: https://github.com/Robbie-Palmer/hq/tree/main/cpp/autonomic-satellite-swarm
- Live demo: https://robbiepalmer.me/satellite-swarm
- Research paper: https://doi.org/10.1109/SMC-IT.2019.00015
- Technologies: C++, CMake, Arduino, ESP32, Catch2, CesiumJS, Emscripten, WebAssembly, SGP4, GitHub Actions, clang-tidy
- Ideas: FLP Impossibility (https://robbiepalmer.me/ideas/flp-impossibility.md), The Two Generals Problem (https://robbiepalmer.me/ideas/two-generals-problem.md)

# Vision

Turn a summer-internship proof of concept into an honest, reproducible research artifact: preserve
the interesting idea, make the software understandable, and create safe seams for better hardware
and better science.

The project explores whether a swarm can assign a temporary mission to the best available agent and
withdraw an unhealthy agent's permission to participate. It calls that final fail-safe behavior
"apoptosis", borrowing the biological metaphor of programmed cell death.

In this implementation, apoptosis is a **safe-disabled software state** that lasts until reset. It
does not destroy or deorbit a satellite. The project is a research prototype intended only for
demonstration. Never treat it as flight software.

# Origin

I created the original C++ and three-Arduino demonstration, then called *Apoptotic Temporal
Satellite Swarms*, during a summer internship. The work
contributed to the paper [*Autonomic Providing Pre-Programmed Death of Cubesats for Avoiding Space
JUNK*](https://doi.org/10.1109/SMC-IT.2019.00015), published with Roy Sterritt at the 2019 IEEE
International Conference on Space Mission Challenges for Information Technology.

The prototype used infrared communication in place of a spacecraft radio and a rover in place of a
propulsion system. It demonstrated temporary-leader negotiation, agent scoring, quiescence under low
light, and fail-safe withdrawal after communication faults.

Returning to the code years later exposed a useful contrast. The concept was worth preserving, but
the repository relied on unsafe ownership and made stronger physical claims than its evidence
supported. Its tight integration of hardware, protocol, scoring, health, and coordination may also
have been a reasonable attempt to fit a small embedded target. The revival gives those concerns
explicit seams while retaining firmware-size checks so the abstraction cost remains measurable.

# Product requirements

## Users

* As a researcher, I want to replace the scoring or failure policy without rewriting radio code, so
  I can test a different hypothesis.
* As an embedded developer, I want the same coordination core to compile for old and modern boards,
  so hardware choice is an adapter decision.
* As a contributor, I want a deterministic host simulation and fast tests, so I can work without
  owning a three-device bench setup.
* As a reader of the paper, I want the repository to distinguish demonstrated behavior, historical
  assumptions, and unverified claims.
* As my future self, I want pinned tools, documented decisions, and one quality command, so returning
  to the project does not require reconstructing its development environment.

## Functional requirements

1. An idle node can initiate a mission for a geographic objective.
2. Available nodes produce a candidacy score through a replaceable policy.
3. A temporary leader collects bounded responses, acknowledges them, and assigns one node.
4. Equal top scores rotate deterministically across a stable set of eligible nodes.
5. Busy nodes do not accept another mission.
6. Health policy supports reversible quiescence and safe-disablement that lasts until reset.
7. Communication failures use bounded retries and explicit evidence before safe-disablement.
8. A versioned codec validates message size, type, coordinate range, score range, byte order, and
   integrity.
9. The portable core runs without Arduino, an operating system, heap allocation, or wall-clock
   access.
10. Reference adapters compile for the original Arduino Uno/infrared setup and a modern ESP32/
    ESP-NOW setup.
11. A mission key combines its origin node, the origin's boot epoch, and a sequence that never wraps
    within that epoch.
12. Telemetry export has a fixed frame, a configurable rate limit, explicit channel availability,
    and retry without removing a rejected record.

## Quality requirements

* CMake and Catch2 provide host builds, characterization tests, and a deterministic simulation.
* Arduino CLI profiles pin each board core and external library.
* Compiler warnings, clang-tidy, formatting, sanitizers, spelling, and workflow linting run in CI.
* Unsigned elapsed-time calculations remain correct across `millis()` rollover.
* Protocol fields use fixed-width types and explicit serialization rather than C++ object layout.
* Hardware compilation proves only that the firmware compiles; it does not prove physical integration.

# Architecture

The core owns a deterministic state machine and domain messages. Four narrow ports surround it:

* `Transport` moves messages through an in-memory bus, infrared, ESP-NOW, or a future radio.
* `HealthMonitor` converts platform observations into nominal, quiescent, or fatal health.
* `CandidacyScorer` ranks a node for an objective.
* `TelemetrySink` accepts diagnostic records after the platform grants output-channel access.

The original orbital-energy calculation survives as `HistoricalOrbitalScorer`. Tests preserve the
paper examples, but the type and documentation label it as a heuristic rather than validated
mission-cost mechanics. A simulation-only SGP4 adapter now propagates checked-in TLEs into the same
snapshot consumed by that scorer and into the Earth-fixed Cartesian position rendered by Cesium.
The portable core and firmware do not link SGP4. Better guidance and maneuver planning can replace
the heuristic without changing the negotiation protocol.

The legacy adapter fragments each validated packet across six NEC infrared frames. The modern
reference adapter sends the same packet over ESP-NOW. ESP-NOW is useful for a benchtop demonstration;
it is not presented as a spacecraft communication choice.

The controller records bounded telemetry and uses mission keys to rotate equal-score assignments. A
portable transmitter exports telemetry through a fixed frame at a configured rate. The reference
firmware uses its serial diagnostic link, separate from IR or ESP-NOW coordination. The next research
cycle still needs measured resource inputs, shared-radio budgets, a governed improvement loop, and a
platform safe-state action hook.

# Coordination under unreliable links

The hard part is not removing a central service. It is deciding what each node may do when no node
can know whether its last message arrived. The
[coordinated attack problem](https://www.cs.cornell.edu/home/halpern/papers/common_knowledge.pdf)
shows why another acknowledgement cannot create certainty over a lossy link. The
[FLP result](https://groups.csail.mit.edu/tds/papers/Lynch/pods83-flp-scanned.pdf) goes further: even
with reliable messages, a deterministic protocol in a fully asynchronous system cannot guarantee
that consensus terminates if one process may crash.

Those results do not make the project futile. They force the guarantee to match the operation:

* A node must enter a local safe state without waiting for the swarm.
* A repeatable observation may continue through a partition and reconcile duplicate work later.
* An exclusive assignment must prefer safety and become unavailable when it lacks enough current
  evidence.
* Telemetry and science payloads need eventual, verifiable delivery rather than global ordering.

Kafka offers useful techniques without offering a deployable architecture for this setting. Stable
producer identities, sequence numbers, idempotent handlers, append-only journals, and deterministic
replay all transfer. A continuously available partition leader, in-sync replica set, and one global
order do not. The swarm should begin with a bounded journal per node and admit that it has several
partial histories.

Software rollout is another distributed protocol. The current codec rejects every layout except its
single 18-byte version, so a future swarm must define how mixed software versions advertise
capabilities, interpret old messages, migrate durable state, stage activation, and roll back. NASA's
Starling experience shows why this matters: one spacecraft could not receive the autonomy software
update, leaving the experiment to run with three nodes.

Data transfer is a separate problem from mission agreement. The IETF
[Bundle Protocol](https://www.rfc-editor.org/rfc/rfc9171.html) provides store-carry-forward delivery
for disrupted links, while
[CCSDS schedule-aware routing](https://ccsds.org/Pubs/734x3b1.pdf) uses predicted contact windows.
The [CCSDS File Delivery Protocol](https://ccsds.org/Pubs/727x0b5e1.pdf) covers transfers to and from
spacecraft storage over intermittent, asymmetric, or one-way contacts. Flooding or epidemic routing
may improve delivery, but every extra copy consumes scarce radio time, storage, and energy.

NASA's [Starling flight results](https://ntrs.nasa.gov/citations/20240006994) make this concrete. Four
CubeSats demonstrated decentralized B.A.T.M.A.N. routing and inter-satellite file transfer. A radio
anomaly kept one craft out of the autonomy experiment, so its distributed planners ran as a
three-node network and tolerated periods in which they did not hold the same plan. That is a better
model for the next simulation than an always-connected cluster.

The [full research note](https://github.com/Robbie-Palmer/hq/blob/main/cpp/autonomic-satellite-swarm/docs/distributed-coordination-research.md)
turns these results into a sequence of experiments. The deterministic simulator can now drop,
delay, or duplicate a selected delivery, change one-way links, and reset a node. The browser exposes
the first experiment: it drops the winning assignment to show that the leader records an assignee
which never learns that it owns the mission. Missions now use an origin node, boot epoch, and mission
sequence as their stable key. Deterministic invariant checks cover loss, duplication, one-way links,
and resets. They also preserve two baseline failures: reset clears `safe-disabled`, and delayed
mission requests have no expiry. Bounded telemetry now records the reasons and stable mission keys
behind those outcomes. A six-mission equal-score replay uses that evidence to show two assignments
per eligible node, with identical native and WebAssembly results. A consensus algorithm comes later,
if an operation's evidence requirements justify one.
The note also compares TLA+, OMNeT++, DTNSim, Basilisk, and NASA NOS3, then defines how the CesiumJS
prototype can become a deterministic test-bed console with headless batch runs and comparable
mission-success measures.

# Non-goals

* Flight qualification, radiation tolerance, or safety certification
* A physically valid deorbit or self-destruction mechanism
* Flight-grade orbit determination, collision avoidance, or guidance/navigation/control
* Secure command and control; the prototype lacks authentication and replay protection
* Implemented multi-hop topology, consensus, Byzantine fault tolerance, or unbounded swarms
* Claims that compile-tested adapters have been verified on absent hardware

# Verification

Host tests cover CelesTrak SGP4 reference vectors to a one-metre bound, TLE validation, polar and
longitude-wrap cases, a bounded 60-second interpolation interval, the published score examples,
invalid inputs, exact-arrival behavior, message and
telemetry corruption, mission negotiation, stable keys, retries, telemetry rate limits, cyclic
equal-score allocation, busy nodes, health transitions, 32-bit clock rollover, explicit delivery
faults, asymmetric links, and volatile state after a node reset. The invariant suite checks local
assignment evidence and duplicate transitions, then records reset persistence and command expiry as
known failures. A three-node in-memory simulation reconstructs the central demonstration without
hardware.
The same runner builds with Emscripten, executes in a browser worker, and has a byte-for-byte parity
check against the native full-orbit fixture. A second parity run compares six equal-score
assignments and their telemetry byte for byte. A production browser audit checks both desktop and
CPU-throttled mobile profiles for page errors, failed resources, and external requests. CI also
compiles both firmware targets from pinned profiles, confirming that orbit propagation remains out
of the embedded dependency graph.

Physical timing, sensor calibration, radio behavior under load, real propulsion, and orbital
validity remain outside the current evidence boundary.

# Roadmap

1. Complete the software revival and retain the original paper examples as characterization tests.
2. Measure shared-radio capacity and duty cycle before moving the implemented serial telemetry export
   onto a coordination link. Add measured resource evidence through platform interfaces.
3. Feed validated resource and lifetime costs into candidacy scoring. Keep the implemented
   mission-keyed rotation as the final tie-break where candidates remain equal.
4. Add a narrow, idempotent platform hook for physical safe-state actions and verify it with fault
   injection before connecting an irreversible actuator.
5. Run packet-loss, network-partition (communication failure that splits the swarm into disconnected
   groups), event-storm, and biased-telemetry experiments in a richer simulator.
6. Evaluate policy changes through replay, independent adversarial review, shadow operation,
   limited canaries, authenticated rollout, and explicit rollback instead of live self-modification.
7. Define what a defensible mission-cost model would need to prove, using the deterministic SGP4
   replay as an environment input rather than evidence that the historical score is physically
   valid.
8. Select physical boards and radios only when there is a concrete experiment to run.
9. Add hardware-in-the-loop tests, authenticated messages, persistent identity, and reset recovery
   before treating the system as more than a bench prototype.

# Success

The revival succeeds when a contributor can clone the repository, run one setup path, reproduce the
coordination behavior without hardware, understand every safety and scientific caveat, and replace
one hardware or research assumption without disturbing the others.

## Architecture Decision Records

- [ADR 000: Arduino Uno Prototype Platform](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/000-arduino-uno-prototype-platform.md) — Accepted, 2016-07-01
- [ADR 001: C++ for the Embedded Agents](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/001-c-plus-plus.md) — Accepted, 2016-07-01
- [ADR 002: Infrared as the Bench Transport](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/002-infrared-bench-transport.md) — Accepted, 2016-07-01
- [ADR 003: Three-Agent Temporary-Leader Protocol](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/003-temporary-leader-mission-assignment.md) — Accepted, 2016-07-01
- [ADR 004: Displacement-Effort Candidacy Score](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/004-displacement-effort-score.md) — Accepted, 2016-07-01
- [ADR 005: Agent Health States for the Apoptosis Demonstration](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/005-agent-health-states.md) — Accepted, 2016-07-01
- [ADR 006: Host-Side Behavior Tests](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/006-host-side-behavior-tests.md) — Accepted, 2021-05-25
- [ADR 007: Portable Core and Hardware Adapters](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/007-portable-core-and-hardware-adapters.md) — Accepted, 2026-09-04
- [ADR 008: CMake and Arduino CLI Split Toolchain](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/008-cmake-and-arduino-cli.md) — Accepted, 2026-09-04
- [ADR 009: Explicit Versioned Wire Protocol](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/009-versioned-wire-protocol.md) — Accepted, 2026-09-04
- [ADR 010: Historical Orbital Score as a Replaceable Policy](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/010-historical-score-as-policy.md) — Accepted, 2026-09-04
- [ADR 011: Host-First Verification with Firmware Compile Gates](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/011-host-first-verification.md) — Accepted, 2026-09-04
- [ADR 012: qrpTracker for Embedded Orbit Propagation](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/012-qrptracker-embedded-orbit-propagation.md) — Rejected, 2026-09-06
- [ADR 013: Browser Simulation with CesiumJS and C++ WebAssembly](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/013-browser-simulation-with-cesiumjs-and-webassembly.md) — Accepted, 2026-09-12
- [ADR 014: Stable Mission Keys Across Nodes and Boot Epochs](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/014-stable-mission-keys.md) — Accepted, 2026-09-12
- [ADR 015: Mission-Keyed Cyclic Tie-Breaking](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/015-mission-keyed-cyclic-tie-breaking.md) — Accepted, 2026-09-13
- [ADR 016: Rate-Limited Telemetry Export](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/016-rate-limited-telemetry-export.md) — Accepted, 2026-09-13
- [ADR 017: Deterministic SGP4 Orbit Simulation](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/017-deterministic-sgp4-orbit-simulation.md) — Accepted, 2026-09-20
- [ADR 018: Deterministic Impulsive Maneuver Model](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/018-deterministic-impulsive-maneuver-model.md) — Accepted, 2026-09-23
- [ADR 019: Deterministic Network Model Boundary](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/019-deterministic-network-model-boundary.md) — Proposed, 2026-09-26
- [ADR 020: Project-Owned Deterministic Experiment Kernel](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/020-project-owned-deterministic-experiment-kernel.md) — Proposed, 2026-10-09
- [ADR 021: Bounded Contact-Plan Routing Model](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/021-bounded-contact-plan-routing-model.md) — Proposed, 2026-10-09
- [ADR 022: Host- and Bench-First Hardware-in-the-Loop Boundary](https://robbiepalmer.me/projects/autonomic-satellite-swarm/adrs/022-host-and-bench-first-hil-boundary.md) — Proposed, 2026-10-09

---

Markdown index of this site: https://robbiepalmer.me/llms.txt