singularis-rf
Singularis Prime over amateur-radio text modes — the receive-only station.
Decodes Singularis Compact (SP1) 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
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:
{"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
Tframes; 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 forack nfrom the addressee, retrying up toRF_APRS_RETRIES(3) everyRF_APRS_ACK_TIMEOUT_S(30 s); a message to*goes toALLwith no ack expected. Incoming messages addressed to us with{n}are acked automatically (RF_APRS_AUTO_ACK). - Identity by construction. The guard requires
RF_CALLSIGNto be a valid AX.25 callsign (≤6 chars, optional-SSID), andrun-rx.shrenders Direwolf'sMYCALLfrom 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) 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
(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 — 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.
Metadata
Release files for singularis-rf 0.1.0
For a detailed explanation of source distributions (sdists) and built distributions (wheels), please see the package formats documentation.
Source distribution (sdist)
| File | Size | Uploaded | Provenance | Actions |
|---|---|---|---|---|
| singularis_rf-0.1.0.tar.gz | 44.0 kB | Without provenance | Details for singularis_rf-0.1.0.tar.gz |
Built distribution (wheel)
| File | Interpreter | ABI | Platform | Actions Reset |
|---|---|---|---|---|
| singularis_rf-0.1.0-py3-none-any.whl | Python 3 | none | any | Details for singularis_rf-0.1.0-py3-none-any.whl |
Total release size: 82.6 kB
Release files / singularis_rf-0.1.0.tar.gz
| Download URL | singularis_rf-0.1.0.tar.gz |
|---|---|
| Size | 44.0 kB |
| Tags | Source |
|
SHA-256 checksum How to use checksums |
7b36666d07733c70b298bae05c2762db69b4c9a563a479838e1406f8870bf6fb
|
|
BLAKE2b-256 checksum How to use checksums |
3438e2b2b3e16c782d40ee732805e96b1f939b101482e99a5d3033f973f36728
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.3
|
Release files / singularis_rf-0.1.0-py3-none-any.whl
| Download URL | singularis_rf-0.1.0-py3-none-any.whl |
|---|---|
| Size | 38.6 kB |
| Tags | Python 3 |
|
SHA-256 checksum How to use checksums |
c0dbfcdc1adc84dd0238b8b0dfe0fc6d5ad692900e05fbd986e1fd382e7dee80
|
|
BLAKE2b-256 checksum How to use checksums |
ba8dfca794d50edea466acb8f245a8a66f91a84fa0ad5eba6b28395db7ab68d3
|
| Upload date | |
|
Uploaded using Trusted Publishing? What is trusted publishing? |
No |
| Uploaded via |
twine/7.0.0 CPython/3.14.3
|
Security for singularis-rf 0.1.0
Provenance
Provenance describes where a file came from. On PyPI, provenance is shared via attestations, which provide a verifiable record of the build or publishing details. View details, limitations and caveats.
No provenance found
None of the files in this release were uploaded with provenance metadata.
A note on package security
PyPI is a repository for distributing packages, not a service for auditing them. While third-party security researchers and our staff do their best to detect and remove malicious packages, PyPI cannot guarantee the quality, security or suitability of any given package.
To learn more about protecting yourself from malicious actors, visit our package security documentation.