HackASL

A hobby macOS-native AllStarLink simplex hotspot built on a single HackRF One.

This is not a product

It is a personal project, still under active development and testing. It was built for fun, on one desk, for one hotspot:

• no releases, no support, no stability promise — it changes whenever it needs to;
• parts are unfinished, and the development log below records the things that were tried and then abandoned or found wrong;
• do not put it on anything you care about, and read the disclaimers before transmitting with it.

---

What this project is

AllStarLink links amateur radio nodes over the internet. Each node connects to a hub with the IAX2 protocol, and radios in different places hear each other as if they shared a repeater. A hotspot is the small local end of that: a low-power radio that puts one handheld on the network.

HackASL is that local end — with no radio hardware except an SDR. The program is the node: it speaks AllStarLink/Asterisk's IAX2 radio-node protocol itself, and one HackRF serves as both the receiver and the transmitter, switched half-duplex. There is no Asterisk, no app_rpt, no chan_usrp, no sound card and no second network box. A Mac, a HackRF and an antenna are the whole station.

The chain, end to end

handheld ──467.5125 MHz NFM──► antenna ──► HackRF RX ──► IQ @ 2 Msps
                                                             │
                   ┌─────────────────────────────────────────▼───────────────┐
                   │ C++20 engine: channel filter → FM discriminator →      │
                   │ de-emphasis → CTCSS detect → squelch → 8 kHz µ-law     │
                   └─────────────────────────────────────────┬───────────────┘
                                                             │ voice frames
                                                             ▼
                                                   IAX2/UDP ──► AllStarLink hub

hub ──► IAX2/UDP ──► voice frames ──► µ-law 8 kHz ──► pre-emphasis + CTCSS + FM modulate
                                                             │ IQ @ 2 Msps
                                                             ▼
                             antenna ◄── HackRF TX ◄── 467.5125 MHz NFM ──► handheld

What happens when you key your handheld

1. Your voice arrives as narrowband FM. The HackRF digitises it at 2 Msps with its local oscillator parked 100 kHz above the channel, so the receiver's DC spike and LO leakage land outside the 12.5 kHz passband; the engine shifts the channel back to baseband in software.
2. The engine filters, discriminates and de-emphasises it, recovers the CTCSS tone, applies squelch, and encodes 8 kHz µ-law voice frames.
3. Those frames go to the hub as ordinary AllStarLink voice traffic, and the hub relays them to every other linked node.
4. Audio coming back is decoded, pre-emphasised, mixed with a locally generated CTCSS tone, FM-modulated and transmitted — on the same frequency, because this is a simplex hotspot. The transmit baseband sits 100 kHz above the LO while the LO sits 100 kHz below the channel, so the LO leakage and the 67 Hz harmonic comb fall outside the channel without moving the emitted frequency.
5. PTT is real AllStarLink keying: the hub's RADIO_KEY / RADIO_UNKEY drive the transmitter through a duplex state machine that arbitrates RX and TX, because one HackRF cannot do both at once.

What it is not

• Not a product, a service, or anything with a support contract.
• Not a bridge, gateway or proxy — nothing pretends to be a second node.
• Not a general-purpose SDR application — one channel of narrowband FM (12.5 kHz / 25 kHz), plus the DSP and the network link a hotspot needs, and nothing else.
• Not an MMDVM/DMR hotspot — this is analog FM voice over AllStarLink.

---

Status

Working end to end on one operator's bench — and nothing more is claimed than that.

• Audio relayed in both directions with real traffic (hub → RF and RF → hub), with PTT driven by real RADIO_KEY / RADIO_UNKEY.
• 401 test cases pass at the time of writing (6.5 M assertions), with ASan and TSan build trees alongside — that is evidence for the parts that are tested, not a promise about the parts that are not.
• Under active development. PROJECT_MEMORY.md is the development log: what was measured, what was concluded, and — repeatedly — what was concluded wrongly and then overturned. Open defects are listed there too. Read it before touching anything that decides whether the link is up.
• No releases and no stable interfaces. The config format, CLI flags and internal APIs change when the project needs them to; expect to rebuild from HEAD.

Hardware

Device	Role
HackRF One	the only runtime SDR. Clones work; this project was developed on an r6 clone.
RTL-SDR Blog V4 (optional)	calibration instrument only: TX carrier error, deviation, occupied bandwidth, modulation spectrum. Never a runtime dependency — the program runs with no RTL attached.

Plus an antenna for the band you are entitled to use.

Build

brew install hackrf gnuradio fftw boost spdlog fmt nlohmann-json libsamplerate portaudio catch2
brew install librtlsdr          # calibration tooling only, never a runtime dependency

cmake -S . -B build
cmake --build build -j8

./build/hackasl_tests           # unit + integration tests
./scripts/build-gui.sh          # -> build/HackASL.app  (Command Line Tools are enough; no full Xcode)

GNU Radio is required — its blocks are the reference DSP (frequency_modulator_fc, quadrature_demod_cf, fm_preemph, fir_filter, sig_source_f), used directly through work() rather than inside a flowgraph.

Tools built along the way: hackasl-node (headless node), hackasl-info (device report), hackasl-cal (calibration), hackasl-tone (on-air acceptance), hackasl-txprobe, hackasl-iaxhub (a minimal IAX2 test hub that streams a known µ-law tone and sends real RADIO_KEY/UNKEY).

Run

The GUI reads and writes exactly one file:

~/Library/Application Support/HackASL/config.json

Set the hub host/port and node number, the RF frequency and channel width, CTCSS, audio levels and gains, then press Start radio. The same engine runs headless:

./build/hackasl-node --seconds 30

No AllStarLink hub to test against? Run the test hub in one terminal and point the node at it — the whole chain can be exercised with no account, no RF partner and no hub:

./build/hackasl-iaxhub --port 4599 --tone 1000      # streams a known 1 kHz µ-law tone

Documentation

Path	What it is
PROJECT_MEMORY.md	development log and long-term memory — start here
docs/ARCHITECTURE.md, docs/DSP.md, docs/IAX2-ASL.md	how it works
docs/TEST-PLAN.md, docs/HARDWARE-TESTING.md	what is verified, and how it was measured
docs/DEPENDENCIES.md	every component, its licence, and what was rejected and why
docs/plans/	the plans, each with its measured outcome (index with a one-line summary each)
docs/research/	the research behind the protocol, RF and calibration decisions

Licence

GPL-2.0-or-later — see LICENSE and NOTICE.

A build with GNU Radio is a combined work and must be conveyed under GPL-3.0-or-later (GNU Radio is GPL-3.0-or-later and the DSP blocks require it). This project's own sources remain available under GPL-2.0-or-later either way.

Disclaimers

• Hobby project, no support. Issues and pull requests may be ignored. Do not use this for anything that needs to work, and do not expect the author to maintain it.
• Not affiliated with AllStarLink, Inc. or Great Scott Gadgets. "AllStarLink" and "HackRF" are their respective marks; this is an independent client that interoperates with them.
• Transmitting is regulated. The operator is responsible for holding the appropriate licence and for complying with the rules of the band in use. This project was developed on 467.5125 MHz, a licence-exempt FRS channel in Taiwan, at low power with the RF amplifier off — that is a description of the development setup, not a recommendation.
• No warranty, as the GPL says.
• Documentation redactions. Hub addresses, device serial numbers and user paths in the documentation are placeholders (192.0.2.0/24, <serial redacted>, ~/). Real values live only in the operator's own configuration file.