Skip to main content

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 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) 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)

Source distribution for singularis-rf 0.1.0
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)

Table of built distributions (wheels) for singularis-rf 0.1.0
File Interpreter ABI Platform Actions
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.

Release history Release notifications | RSS feed

This release

0.1.0 This release

2 release files No provenance

Anthropic, PBC Visionary sponsor Bloomberg Visionary sponsor Hudson River Trading Visionary sponsor Meta Visionary sponsor NVIDIA Visionary sponsor Microsoft Sustainability sponsor Depot Continuous Integration AWS Cloud computing and Security Sponsor Datadog Monitoring Fastly CDN Google Download Analytics Sentry Error logging StatusPage Status page