Sat ir link

COR-SAT

COR-SAT turns natural-language mission requests into tested Python mission packages for a Raspberry Pi satellite payload. It combines AI-assisted generation, deterministic evaluation, a supervised runtime, a Python hardware SDK, a Rust HAL, camera capture, and prototype infrared communications hardware.

Experimental project. Generated missions are limited to the capabilities and checks documented below.

System overview

flowchart LR
    A[Mission request] --> B[Typed requirements]
    B --> C[Minimal generator]
    C --> D{Evaluator}
    D -->|Pass| H[Mission package]
    D -->|Fail| E[Robust generator]
    E --> D
    D -->|Both fail| F[Repair once]
    F --> D
    H --> I[Runner]
    I --> J[Python SDK]
    J --> K[Rust HAL]
    K --> L[Pi camera]

    M[IR breadboard] -. prototype .-> N[KiCad PCB]

Model calls return text only and never write project files. The controller validates requirements, evaluates behavior, writes the package, derives manifest.json, and validates the final package against the runner schema.

Project status

Repository map

Requirements

Development and mission generation

• Git
• Python 3.11+
• Ollama
• qwen3:4b-instruct

Physical payload runtime

• Raspberry Pi running Linux or Raspberry Pi OS
• Rust 1.85+ and Cargo
• Raspberry Pi camera stack with rpicam-still
• IMX219 NoIR camera for the current HAL tuning configuration

Optional optical flow

• OpenCV
• NumPy

Mission generation and tests can run without camera hardware. Physical mission execution and runner supervision are intended for Linux or the Raspberry Pi.

1. Clone and install

git clone https://github.com/dmarcr1997/COR-SAT.git
cd COR-SAT
python -m venv .venv

Activate the environment:

Commands below use python. On Raspberry Pi OS, use python3 if python is not available.

Install the SDK and generation dependencies:

python -m pip install --upgrade pip
python -m pip install -e . ollama requests

For missions that calculate optical flow:

python -m pip install opencv-python numpy

2. Configure Ollama

Pull the model used by the generator:

ollama pull qwen3:4b-instruct

Start Ollama if it is not already running:

ollama serve

The generator expects Ollama on its default local endpoint and uses qwen3:4b-instruct. The model is configured in agents/generator.py. There is currently no project CLI flag for changing the model or Ollama host.

3. Verify the software setup

python -m unittest discover -s tests -v
cargo test --manifest-path hal/Cargo.toml

The Python suite mocks model calls, camera hardware, time delays, and OpenCV behavior. It does not require Ollama or a connected camera. The Cargo command tests the Rust HAL.

4. Generate a mission

python -m agents.cli "Capture seven images at three-second intervals and send a heartbeat before every capture." --candidate demo

Generated files:

agents/candidates/demo/
|-- manifest.json
`-- mission.py

Use a new candidate name for each run. Existing candidate directories are not overwritten.

Supported request examples

Capture one image.
Capture five images at two-second intervals.
Capture twenty images and calculate sparse optical flow in four groups.
Capture seven images, heartbeat before each capture, and handle shutdown signals.

Requests for communications, IMU, or actuator behavior are rejected before generation.

5. Prepare the Raspberry Pi

Install the camera module and use a current Raspberry Pi OS release. Raspberry Pi OS includes the standard rpicam-* tools. See the official camera setup guide.

Install Rust with rustup, then select an edition 2024-compatible toolchain:

curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
source "$HOME/.cargo/env"
rustup update stable
rustc --version

Rust 1.85 or newer is required.

Confirm that the camera stack can see the sensor:

rpicam-still --list-cameras

The current HAL uses the Raspberry Pi 5 IMX219 NoIR tuning file. Confirm it exists:

test -f /usr/share/libcamera/ipa/rpi/pisp/imx219_noir.json

Earlier Raspberry Pi models store tuning files under /usr/share/libcamera/ipa/rpi/vc4/. Update the HAL tuning path before building if you use one of those models.

Build the HAL:

cargo build --release --manifest-path hal/Cargo.toml

Start the HAL from the repository root:

cargo run --release --manifest-path hal/Cargo.toml

The service listens on 0.0.0.0:3000. The Python SDK connects to http://localhost:3000 by default, so the runner and HAL should run on the same Pi unless the client configuration is changed.

Verify the HAL

curl http://localhost:3000/v1/system/health
curl http://localhost:3000/v1/system/status
curl http://localhost:3000/v1/system/capabilities
curl -X POST http://localhost:3000/v1/camera/capture

Camera captures are written to hal/caps/ when the HAL is started from the repository root.

6. Run a mission

Run the included camera mission:

python -m runner.cli supervise periodic-camera

Run a generated candidate:

python -m runner.cli supervise demo --candidate

supervise monitors the process, checks heartbeats, and restarts one unexpected failure. Use start when supervision is not needed.

supervise stays in the foreground. Open a second terminal to inspect status or logs, or to stop the mission.

Runtime controls

Runtime artifacts:

runtime/<mission-name>/
|-- heartbeat.json
|-- mission.log
`-- state.json

Mission-generated files are stored beside the mission code:

Optical-flow missions write JPEG results to that outputs/ directory.

Validation pipeline

Every candidate must pass:

1. Validated typed requirements
2. Python syntax checks
3. Import and file-write safety checks
4. Fake SDK execution
5. Capture, timing, heartbeat, and output checks
6. Mission-specific optical-flow checks when requested
7. Runner manifest validation

If both generated candidates fail, the highest-scoring failure is repaired once and evaluated again. A failed repair stops the pipeline without creating a package.

Hardware

The camera payload is connected through the Rust HAL. The infrared link is a separate hardware prototype and is not yet exposed through the SDK or mission generator.

Presentation demo

Open demo/index.html in a browser. The presentation works offline and includes keyboard navigation, speaker notes, the software demonstration, and project hardware images.

Troubleshooting

License

MIT