PortaPack Mayhem: the firmware that turns a HackRF into a standalone radio

What Mayhem actually is, and who it is built for

Mayhem is firmware for the HackRF software defined radio when it is paired with a PortaPack, the add-on board that supplies a screen, controls and an SD card slot. The README describes it as a fork of the Havoc firmware, which was itself a fork of the original PortaPack firmware. The lineage matters, because it tells you the project did not start from a blank page: it inherited a codebase and then added features and fixes on top.

The audience is narrow and physical. You need a HackRF and one of the PortaPack variants the project supports, which the README lists as H1, H2, H4 and H4M. If you only have a HackRF connected to a laptop, this firmware does nothing for you, because it runs on the PortaPack hardware rather than on the host. The repository description states the target plainly: firmware for the HackRF+PortaPack H1/H2/H4/H4M.

The project is written in C and licensed GPL-3.0. The default branch is next, which is also the branch the nightly release workflow builds from. That single detail explains a lot about how the project expects to be used: contributors work against next, and users who want the newest features pull from the same place.

How the firmware, the SD card and the build system fit together

There are three layers worth separating. The first is the firmware image itself, which is compiled from the C sources under firmware/ and flashed onto the device. The second is the sdcard/ directory in the repository, which is the source of the app content that the firmware loads at runtime. The third is the build environment, which is containerised.

The build system is CMake based, with a CMakeLists.txt at the repository root, and the project ships several Dockerfiles: dockerfile, dockerfile-alpine, dockerfile-nogit, dockerfile-nogit-alpine and dockerfile-nogit-arm. The Alpine variants matter for anyone on a small machine, and the arm variant exists for ARM hosts. The docker-compose.yml maps a local ./bin directory into the container at /havocbin, so the build output lands somewhere you can reach from the host instead of disappearing inside the image. The name of that mount point is a leftover from the Havoc ancestry.

Alongside the Docker path there is a flashing/ directory and a tools/ directory. The repository also carries a hackrf submodule and a hardware/ directory. The presence of a .gitmodules file means a plain source download is not the same thing as a clone: the submodule has to come along or the build will not have everything it expects.

Installing Mayhem and running a first build

Most people should not build from source. The README points to the releases page for the current stable release and says to follow the instructions in the release description. The latest nightly builds live on the same releases page. If that is your path, stop here and read the release notes for your board.

Building is for people who want to change the firmware. The repository provides a compose file, and the service is named portapack-mayhem-dev:

docker compose build
docker compose run --rm portapack-mayhem-dev

The compose file builds from dockerfile-alpine and mounts ./bin to /havocbin. After a successful build, that local bin directory is where you look for output rather than inside the container. If you prefer plain Docker over compose, the repository also ships dockerize.sh, and the individual Dockerfiles can be built directly.

For code formatting there are format-code.sh and format-code.ps1 at the root, with a .clang-format file defining the style. The repository also carries AGENT.md, which the README flags at the top for automated coding tools. If you plan to send patches, read AGENT.md and CONTRIBUTING.md before you touch anything.

On the device side, the sdcard/ directory in the repository is the reference for what belongs on the card. Copying that content onto a card is the mechanism by which the app set becomes available, and the firmware reads it at startup.

The nightly channel is the real release model

The recent releases are nightly-tag builds dated 2026-09-20, 2026-09-18 and 2026-09-17, produced by a workflow named create_nightly_release.yml running against the next branch. The last push to the repository was on 2026-09-22. That is a release cadence measured in days, not months, and it shapes how you should think about stability.

A nightly is a build, not a promise. The README separates the two channels explicitly: the current stable release is on the latest release page, and the latest nightly release is on the releases index. If you want the stable path, you follow the release description. If you want a feature that landed this week, you take the nightly and accept that it was cut from whatever next contained that night.

There is a practical consequence. Pinning to a nightly means you are choosing a moving target, and the useful habit is to record which nightly-tag you flashed so you can say what you were running when something misbehaves. The project does not document a rollback procedure in the README, so plan your own way back to a known build before you start experimenting.

Where Mayhem is the wrong choice

The README is unusually direct about hardware risk, and the warning deserves repeating in plain terms. Sellers who ship their own firmware files, or their own setup instructions, are a signal that the board may not be compatible with current releases. The README states that all H3 models and clones of that version use their own firmware, that those changes are not contributed back, and that the buyer ends up with a device nobody maintains.

The second warning is about money. The README states that if you paid for Mayhem or a prepackaged version, you are being scammed, and that the only legitimate repository link is the portapack-mayhem organisation on GitHub. Anyone selling you the firmware as a product is selling something that is free under GPL-3.0.

Beyond hardware, there is the question of what you are trying to do. Mayhem is a self-contained device experience. If your work depends on host-side tooling, scripted capture, or tight integration with a desktop SDR application, the PortaPack form factor is a constraint rather than a feature. The firmware gives you a screen and buttons; it does not give you a scripting environment on the host.

Mayhem against the firmware it forked from

The honest alternative is Havoc, the firmware Mayhem forked from, which in turn forked the original PortaPack firmware. The README's own framing is that a fork is a derivative, and that this one has extra features and fixes compared with the older versions. So the difference is not architectural. Both run on the same HackRF plus PortaPack combination, and both descend from the same code.

The difference is where development happens and how fast it moves. Mayhem builds nightly from the next branch and publishes those builds, it maintains a wiki covering hardware versions and contribution process, and it has a Discord for coding questions. Havoc, by the project's own description, is the older version. Choosing between them is therefore a question of whether you want the current feature set and the nightly channel, or a codebase that has stopped moving.

The third option is the vendor firmware that ships with a board. That is the one the README warns about, because a seller-specific recipe diverges from upstream and does not receive upstream fixes.

Licence, maintenance and what an upgrade really costs

The repository is licensed GPL-3.0, and the file listing also includes a LICENSE.GPL-2.0-or-later file. Both are present in the tree. If you intend to redistribute a modified firmware, or ship a product built on it, the copyleft terms are the thing to read, and the two licence files in the root are the place to start. This is a description of what the repository contains, not legal advice, and the specifics of your distribution are a question for a lawyer.

The maintenance picture is straightforward from the repository metadata: the project is not archived, and the last push was on 2026-09-22. Releases are cut nightly from the next branch. For a user, that means upgrades are available constantly and there is no long support window attached to any single build. The cost of upgrading is the cost of reflashing plus whatever the release description says about that build, and the cost of not upgrading is missing fixes that only exist on next.

Contributors carry a different cost. The README points to Contributing Guidelines and a how-to-collaborate page on the wiki, and it asks people to spend time on documentation, bug fixes and issue answers rather than only on new functionality. It also notes that the hardware and firmware were built by many people, and asks contributors to collaborate before forking again. Given the project's own history of forks, that request is aimed at a real pattern.

Editorial conclusion

Adopt Mayhem if you already own a HackRF and a supported PortaPack and want the touchscreen app set that the stock firmware does not provide. Do not adopt it if you have no PortaPack, or if you bought an H3 or a clone whose seller ships a custom recipe, because the README warns those use their own firmware and get no upstream fixes. Before flashing, verify which release channel you are on, whether the seller's instructions match the current release description, and whether your board is one of the versions listed in the wiki.

Frequently asked questions

Official sources

1. License: GPL-3.0
2. portapack-mayhem/mayhem-firmware on GitHub
3. Project website
4. README
5. Releases