Hacker's Ham Shack¶
Hammunition turns a Debian-family computer you already have into an amateur radio, software-defined radio and RF workstation. Parrot OS is the primary target; Debian 13, Ubuntu, Kali and Raspberry Pi OS are supported too. It is not a distribution and does not replace your system: it adds to it, using your distribution's own packages wherever they exist.
These pages are the manual. The standard they are written to: a licensed ham with moderate Linux experience gets from a fresh install to a working digital-modes station without asking anyone a question or reading a forum thread. A step that needs knowledge these pages do not give is a bug in them, and worth an issue.
Start here, in this order¶
New to Hammunition? Read these four, in order. Each is written so you can finish it without asking anyone a question.
- Installation. A numbered walkthrough from a fresh machine: the engine, the health check, your callsign and grid, the dry run and how to read it, the real install, and how to undo it. Every command is written out with the output it prints.
- Profiles. All nineteen bundles of software, what each installs and leaves out, and a "which profile do I want" table by goal.
- Guides. One task each, start to finish: rig control, radio audio, FT8, Winlink, APRS, SDR, satellites, offline maps.
- Troubleshooting. By symptom, when something does not do what a page said it would.
Also: The Hammunition suite (the engine, Tray, Hill, Bunker, Console and GPS Tether, and how they fit), Applications by activity, EMCOMM preparation and field use and what to download before a deployment, and load every area ahead, activate where you are.
Five minutes to a plan¶
The short form of step 1, for someone who has done this before:
git clone https://github.com/Renegade-Penguin/Hammunition.git
cd Hammunition
./bootstrap.sh
hammunition install station --dry-run
The last line changes nothing. It prints every package, every file and
every system change the install would make. Read it, then run it again
without --dry-run. Installation walks the
whole path, and How much disk you need says
what to have free first: about 5 GB for one or two profiles, about 55 GB for
the whole catalog.
What do you want to do?¶
Find your situation, then follow the link. Each guide says what to install, what to run and what you should see.
| I want to… | Start here | Profile |
|---|---|---|
| Make FT8, JS8 or PSK contacts | FT8 and the digital modes | digital-modes |
| Let every program control my radio | Rig control (CAT) | station |
| Get audio between radio and computer right | Radio audio | — |
| Send email by radio when the internet is down | Packet and Winlink | packet |
| Report my position, see who is around | APRS | packet |
| Listen with a cheap SDR dongle | SDR first steps | sdr, listening |
| Track and hear satellites | Satellites | satellite |
| Know when a band is open | Propagation | propagation |
| Navigate with no network at all | Offline navigation | navigation |
| Keep the clock right with no network | Time and position | station |
| Switch the GPS, a modem or a service off to save power | The tray's Controls panel | station |
| See repeaters, airfields and hospitals on an offline map | Offline navigation | navigation |
| Read Wikipedia and the ICS forms with no network | Offline reference | reference |
| Study wireless security | RF security | rf-security |
| Use an SDR dongle I already own | SDR first steps, then the device's page, for example RTL-SDR | sdr |
| Find my radio or adapter and see what Linux needs for it | Hardware | — |
| Know how big a disk to buy | How much disk you need | — |
| Run this on Ubuntu, Kali, Mint, a Pi or a desktop other than Plasma | What works on which desktop, then Getting started | — |
| Understand what an install will do to my machine | Your first profile: read the plan, then run it | — |
| Fix something that broke | Troubleshooting, by symptom | — |
| Add a program or a device's identifiers to the catalog | Contributing | — |
Every guide says which parts were measured on real hardware and which were not. Where it has not been measured, it says unmeasured rather than guessing.
How it treats your machine¶
- It shows you first.
--dry-runprints the complete plan: packages, builds, files, groups, udev rules, repositories. It is not an approximation. - It installs other people's software, verified. Distribution packages through apt. Anything else is pinned to a version and checked against a checksum before it runs; nothing unverified is installed, and nothing is ever piped into a shell.
- It records what it did.
hammunition statusshows every transaction, andhammunition uninstallreverses them. - It never guesses your callsign. Files that need your callsign or grid are written from values you set once, and skipped, by name, until you do.
- Transmit-capable security tooling needs your consent, typed, and
--yescannot give it for you.
The software is theirs¶
Hammunition writes none of the radio software it installs. The projects we install links every one of them to its home, and Credits names the projects whose years of curation this catalog stands on. When a program misbehaves, its page in the package reference says where to get real help with it.
Where things are¶
- Installation — the whole path from a fresh machine, with every command and what it prints.
- Profiles — the bundles, what each installs and what it leaves for you to set up, and which one you want.
- Guides — one task each, start to finish.
- Troubleshooting — by symptom.
- Getting started — the short pages: size your disk, the first profile, the first decode.
- Packages — every program, what it does, what it needs, its known problems.
- Hardware — radios, SDRs, GPS and the rest: what Linux needs to talk to each.
- What works on which desktop — the tray and the menus on Plasma, Xfce, LXQt, GNOME and the rest.
- Reference — the command line and the measurements everything here rests on.
- Contributing — add a program, send a device's identifiers.