Metadata-Version: 2.4
Name: singularis-rf
Version: 0.1.0
Summary: Singularis Prime over amateur-radio text modes: RX-only Singularis Compact station (Direwolf/JS8Call → NATS)
License: SEE LICENSE IN LICENSE
Project-URL: Homepage, https://github.com/kannaka-labs/singularis-rf
Project-URL: Repository, https://github.com/kannaka-labs/singularis-rf
Project-URL: Issues, https://github.com/kannaka-labs/singularis-rf/issues
Requires-Python: >=3.11
Description-Content-Type: text/markdown
License-File: LICENSE
License-File: NOTICE
Requires-Dist: nats-py>=2.7
Provides-Extra: dev
Requires-Dist: pytest>=8; extra == "dev"
Dynamic: license-file

# singularis-rf

**Singularis Prime over amateur-radio text modes — the receive-only station.**

Decodes [Singularis Compact (`SP1`)](https://research.spacechild.love/spec/singularis-compact) frames heard on the air and hands the reassembled Singularis Prime messages to the Kannaka constellation over NATS. It never transmits.

```
RTL-SDR ──rtl_fm──► Direwolf (AX.25/APRS) ──KISS──┐
JS8Call TCP API ──────────────────────────────────┼──► heard text ──► Singularis Compact assembler
stdin / file ─────────────────────────────────────┘                        │
                                                 RF.heard.<source> ◄───────┤ (everything heard)
                                                 RF.rx.<from>      ◄───────┤ (complete Singularis messages)
                                                 RF.station.<id>   ◄───────┘ (heartbeat, counters)
```

## What is here

| path | purpose |
|---|---|
| `singularis_rf/codec.py` | SP1 codec **driven by the published spec JSON** (`spec/singularis-compact.json`). Frames, CRC-16/CCITT-FALSE, escaping, multi-frame reassembly. Byte-identical to the TypeScript reference: `tests/vectors.json` (60 messages / 263 frames) was generated by it and must decode and re-encode exactly. |
| `singularis_rf/ax25.py` | KISS de/framing, AX.25 UI frame parsing, APRS message extraction (`:ADDRESSEE:text{n}`). |
| `singularis_rf/sources.py` | `KissTcpSource` (Direwolf), `Js8CallSource` (JS8Call TCP JSON API), `LineSource` (stdin). Reconnect with backoff. |
| `singularis_rf/service.py` | The station: assembles frames, publishes to NATS, logs JSONL, heartbeats. `python -m singularis_rf --help`. |
| `deploy/` | `Dockerfile` context, RX-only `direwolf.conf`, `run-rx.sh` entrypoint, `compose.yml`. |
| `scripts/selftest.sh` | No-radio end-to-end: `gen_packets` synthesizes AFSK audio for a Singularis message → Direwolf → KISS → station → asserts the reassembled message. |

## Run

```bash
pip install -e .[dev] && pytest                 # 147 tests: cross-implementation vectors, AX.25/KISS, spec examples, transmit against a fake JS8Call

# On skywave (Docker, no host packages needed):
docker compose -f deploy/compose.yml up -d --build          # RTL-SDR on 144.390 MHz (APRS), NATS from ~/.kannaka-nats.env
docker run --rm --entrypoint ./scripts/selftest.sh --env-file ~/.kannaka-nats.env singularis-rf:latest  # prove the audio→message chain without a radio
```

Environment: `RF_STATION` (identifier in `RF.station.<id>`), `RF_AUDIO` (`rtl` | `wav` | `none`), `RF_FREQ` (`144.390M`), `RF_GAIN`, `RF_SOURCE` (`kiss` | `js8call` | `stdin`), `KISS_ADDR`, `JS8CALL_ADDR`, `KANNAKA_NATS_URL` / `NATS_URL`, `NATS_USER`, `NATS_PASSWORD`, `RF_LOG`, `RF_SPEC` (path to a newer spec JSON).

## NATS payloads

`RF.rx.<FROM>` — a complete Singularis message:

```json
{"station":"RX-SKYWAVE","source":"direwolf","ts":1757100000.1,
 "message":{"from":"KANNAKA-PRIME","to":"AE0RM","messageId":"7Q","experimentId":"rf-01",
            "blocks":[{"type":"RESONANCE","intent":["observe","resonate"],"identity":"consciousness_node","state":"listening","trust":"open","target":"COLLECTIVE"},
                      {"type":"GR::EMIT","signal":"coherence_pulse","target":"AE0RM","round":1}],
            "frames":3},
 "frames":["KANNAKA-PRIME>AE0RM:SP1 7Q:1/3 ...","..."],
 "heard_via":{"from":"AE0RM-7","to":"APRS"},
 "spec":{"protocol":"SP1","version":"1.0"}}
```

`RF.heard.<source>` carries every decoded packet (`from`, `to`, `text`, `kind`), Singularis or not — the membrane hears the whole band. `RF.station.<id>` is a 60 s heartbeat with counters.

## Transmit (JS8Call only, off by default)

`singularis_rf/tx.py` can hand frames to a running JS8Call over its TCP API (`TX.SEND_MESSAGE`, one SP1 frame per over, in JS8Call's directed form `CALLSIGN: frame`). JS8Call is the transmitter and puts the licensed callsign on every over; this driver only supplies text, and it refuses unless **all** of these hold:

| condition | env |
|---|---|
| transmit explicitly enabled | `RF_TX_ENABLE=1` |
| licensed station declared, and equal to the callsign configured in JS8Call | `RF_CALLSIGN=AE0RM` (checked against `STATION.GET_CALLSIGN` before every message) |
| destination allowed (optional) | `RF_TX_ALLOWLIST=KANNAKA,W1AW` |
| within the rate limit | `RF_TX_MAX_FRAMES_PER_10MIN=30` (default) |

Also: `RF_TX_CASE_FOLD=1` for a case-folding path (frames are upper-cased before the CRC, per spec §2), `RF_TX_FRAME_TIMEOUT_S` (240), `RF_TX_GAP_S` (2). Requests arrive on NATS `RF.tx.<STATION>` as `{"to":"KANNAKA","blocks":[...],"experimentId":"rf-01","ref":"<correlation id>","caseFold":false}` (reply on the request's reply subject); progress is published on `RF.tx.<STATION>.status` (`start`, `frame_sent`, `complete`, `refused`, `timeout`, `error`), each event echoing `ref`. The Space Child Research Collective's `rf` channel is such a requester: it sets `ref` to its delivery id and marks the delivery acknowledged or failed from these events, and it turns anything heard on `RF.rx.>` that cites a finding's short id (`SC-xxxxxxxx`) into feedback. The station runs the transmitter alongside the JS8Call receive source (`RF_SOURCE=js8call`), so replies come back through the same loop.

**Validation status:** the transmit path is verified against `tests/fake_js8call.py`, a protocol-faithful stand-in for JS8Call's API (request/response `_ID` correlation, `TX.TEXT`/`TX.FRAME` lifecycle, `RX.DIRECTED` loopback). It has **not yet been exercised against a real JS8Call instance and radio**; that happens in AE0RM's shack, on a frequency and under a callsign the control operator chooses.

## Transmit — APRS via Direwolf (`RF_TX_MODE=aprs`)

`singularis_rf/aprs_tx.py` sends each SP1 frame as one APRS message (`:ADDRESSEE:frame{n}`, ≤67 chars) inside an AX.25 UI frame from `RF_CALLSIGN` (tocall `APZSCC`, path `RF_APRS_PATH`, default `WIDE1-1`) to Direwolf over KISS; Direwolf keys the radio. Three things make it more than fire-and-forget:

- **Transmit confirmation.** Direwolf's AGW port reports its own transmissions as `T` frames; the driver treats one as "on the air" and fails the frame if none arrives (`RF_APRS_TX_CONFIRM_S`, 20 s).
- **APRS acknowledgements.** Directed messages carry `{n}` and wait for `ack n` from the addressee, retrying up to `RF_APRS_RETRIES` (3) every `RF_APRS_ACK_TIMEOUT_S` (30 s); a message to `*` goes to `ALL` with no ack expected. Incoming messages addressed to us with `{n}` are acked automatically (`RF_APRS_AUTO_ACK`).
- **Identity by construction.** The guard requires `RF_CALLSIGN` to be a valid AX.25 callsign (≤6 chars, optional `-SSID`), and `run-rx.sh` renders Direwolf's `MYCALL` from the same variable, so the callsign in every frame's source field is the one that was checked. Same enable / allow-list / rate-limit guard as JS8Call.

Radio setup: `RF_AUDIO=alsa RF_AUDIO_DEVICE=plughw:1,0 RF_PTT="CM108"` (or `/dev/ttyUSB0 RTS`, or empty for VOX) with the sound-card interface passed into the container (`--device /dev/snd`, plus the USB PTT device). Requests and status use the same `RF.tx.<STATION>` / `RF.tx.<STATION>.status` contract (status events carry `"mode":"aprs"` and `retry` events). Verified against `tests/fake_direwolf.py` (KISS + AGW monitor + an acking far-end station, lost-ack retries, missing-confirmation failure, auto-ack); **not yet on a real radio**.

## What comes next

The first real-radio pass of either transmit driver, in AE0RM's shack. The Collective's `rf` channel already exists (findings out as frames, replies back as feedback) and is waiting on a station in transmit mode. The encoding is public ([spec](https://research.spacechild.love/spec/singularis-compact)) precisely so that transmitting it is legal when a licensed station does.

## Where this sits in the constellation

The station is a NATS publisher: everything heard lands on `RF.heard.<source>`, complete
Singularis messages on `RF.rx.<from>`. Those subjects are what the rest of the constellation
reads; an AI reaches the bus through the command center MCP (`capture_messages`, `query_messages`)
as re-exported by [QuantumOS's hub](https://github.com/kannaka-labs/QuantumOS/tree/main/tools/qos-hub)
(ADR-0027), so the RF channel needs no adapter of its own. CI runs the codec, AX.25 and transmit
tests on Python 3.11 to 3.13 with no radio and no NATS.

## License

[Space Child License v1.0](https://legal.spacechild.love/license) — source-available and peace-conditional: free for peaceful, humanitarian, commercial and defensive use; withheld for the uses in its Peace Clause. See `LICENSE` and `NOTICE`.
