ham-rs

Pure Rust tools for amateur-radio control.

Workspace

Crate	Purpose
ham-audio	Linux PipeWire device discovery and gated voice-audio bridge
ham-radio	Vendor-neutral radio types, state, capabilities, and async control trait
icom-civ	Icom CI-V frames, streaming decoder, BCD frequencies, and mode encoding
ic7100	IC-7100 command construction and exclusive async serial controller
mfj-226	MFJ-226 PC Mode serial client and documented wire-format types
mfj-226-cli	MFJ-226 interactive TUI and one-shot text/JSON automation CLI
ham-cli	ham command-line utility and interactive terminal UI
ham-api	Reusable Axum router and the hamd HTTP server
nwr-same	NOAA Weather Radio channels, stations, and SAME/EAS alert parsing

The dependency direction is intentionally one-way: applications depend on the radio abstractions and protocol codec, while neither library depends on a UI or network server.

IC-7100 voice console

The MVP targets Linux with PipeWire and an Icom IC-7100 connected over USB. On Debian-family systems, install the native build dependency first:

sudo apt install libpipewire-0.3-dev

Start the console with the repository's just recipe:

just run

The first-run setup enumerates the serial, IC-7100 audio, and Focusrite audio devices and stores stable IDs in ~/.config/ham-rs/config.toml. The IC-7100's uniquely named Port A (USB1/CI-V), the IC-7100 USB codec, the Scarlett Solo input/output, and its channel 1 XLR microphone input are selected automatically. The application configures and reads back all four IC-7100 USB voice settings over CI-V before transmit can be armed.

On subsequent runs, just run uses Hamlib's established rigctl utility and its stable IC-7100 backend (model 3070) before and after the TUI. The read-only check confirms the radio identity, enforces RX before startup, and reports the frequency, mode, repeater shift and offset, transmit tone, and tone state. Run just validate for the same check without opening the TUI. Hamlib does not expose the IC-7100's USB connector menu through its standard API, so the Rust IC-7100 backend configures and verifies those settings directly through CI-V.

Inside the console, W applies and reads back the WX4EMA VHF FM preset (147.015 MHz, +600 kHz, 88.5 Hz), A arms transmit, Space toggles PTT, and X forces receive. Transmission is audio-gated until the radio acknowledges PTT, has a 60-second software limit, and requires the radio's three-minute hardware time-out timer as an independent backstop.

Press Tab to open the receive-only NWR / SAME tab. Use Up/Down and Enter to tune and save one of the seven NOAA Weather Radio channels, or press S to scan all seven and save the channel with the strongest IC-7100 S-meter reading. The saved channel is restored when the tab is opened on a later run. The tab records the IC-7100 receive audio in durable 12-second WAV chunks and shows a slightly delayed, local Whisper transcription. It also demodulates the SAME AFSK data directly: watch alerts turn the NWR outline yellow, warnings turn it red, and the SAME end-of-message clears the alert outline.

NWR sessions are stored under $XDG_STATE_HOME/ham-rs/recordings (or ~/.local/state/ham-rs/recordings) with chunk-NNN.wav, transcript.md, and alerts.jsonl files. The first chunk triggers a one-time download of the checksum-verified base.en Whisper model. Set HAM_RS_WHISPER_MODEL to use a local model; MEETRS_MODEL and a verified model in ~/.meetrs/models are also reused automatically.

Run ham tui --setup to repeat device selection. Automated tests use a serial emulator and never open or key physical radio hardware.

Development

cargo fmt --all --check
cargo clippy --workspace --all-targets
cargo test --workspace

Try the command-line tools:

cargo run -p ham-cli -- info
cargo run -p ham-cli -- encode-frequency 147015000
cargo run -p ham-cli -- encode-frame 88 e0 03
cargo run -p ham-cli -- tui --help

Run the API server on its default loopback address, 127.0.0.1:8080:

cargo run -p ham-api --bin hamd
curl http://127.0.0.1:8080/health
curl http://127.0.0.1:8080/v1/radio

Override the listener with HAM_API_ADDR.