Mayhem — Installation and the Update Flow

Getting Mayhem onto a HackRF and PortaPack has two independent parts: obtaining a firmware image, and writing it to the device. Most operators do neither by hand — they download a prebuilt release and flash it on-device from the SD card — but the from-source and desktop-flashing paths matter for development and for recovering a device that will not boot.

3.1 Getting an image: nightlies vs building

Prebuilt nightly (recommended). Mayhem publishes automated nightly releases on its GitHub releases page, each dated (for example nightly-tag-2026-09-16). A nightly is the current development state — “the latest and greatest, although may not be the most stable,” in the project’s own words. Formal tagged stable releases exist but are infrequent; the last was v2.0.1 in April 2024, so in practice a current install comes from a recent nightly. Each release ships several assets: the firmware image itself and one or more ..._COPY_TO_SDCARD archives that carry the matching SD-card contents (one version bundles the ADS-B world map, a smaller one omits it for routine updates).

Building from source. The repository builds through Docker, which pins the toolchain so the build is reproducible without installing an ARM cross-compiler by hand. This is the route for developing an app, testing an unmerged change, or producing a custom image. The output is the same kind of firmware binary the nightlies ship, flashed by any of the methods below.

3.2 The firmware update flow

Mayhem supports several ways to write an image; they differ in whether a computer is needed and in what gets updated.

1 — On-device Flash Utility (no computer needed). The simplest path once the device already runs Mayhem:

1. Copy the firmware file to the SD card (or extract the release’s ..._COPY_TO_SDCARD archive to the card root, which places the firmware in FIRMWARE/ and refreshes the external apps in APPS/).
2. On the PortaPack, open Utilities → Flash Utility.
3. Select the firmware file on the card and confirm.
4. Wait for the flash to complete and let the device reboot.

The firmware may be a plain .bin (firmware only) or a .ppfw.tar bundle that updates both the flashed firmware and the external SD apps together.

2 — Desktop flashing over USB (hackrf_spiflash). The classic method, needed to install Mayhem onto a HackRF that is not yet running it:

1. Connect the device by USB and put it in HackRF mode from the on-screen menu (this presents it to the host as a plain HackRF).
2. On Linux or macOS, run hackrf_spiflash -w <firmware>.bin. On Windows, the release includes a mayhem_flasher.bat helper that wraps the same tool.
3. Reboot the device.

With this method the SD-card contents are not updated automatically — they must be refreshed separately from the release’s COPY_TO_SDCARD archive.

3 — Browser-based updater (hackrf.app). A Web-USB page, https://hackrf.app/, can flash a device that is already running Mayhem: connect over USB (with data enabled), open the page, connect the device, and choose a stable, nightly, or custom .ppfw image from the “Manage Firmware” section. As with desktop flashing, SD-card contents still need to be kept in sync separately.

3.3 First install onto a bare HackRF

The order that avoids confusion for a first install:

1. Prepare the SD card first (Volume 4): format FAT32 (or exFAT) and extract the release’s ..._COPY_TO_SDCARD archive with the world map to the card root.
2. Flash the firmware to the HackRF over USB with hackrf_spiflash (method 2), since the device is not yet running Mayhem and cannot use the on-device Flash Utility.
3. Insert the SD card, reboot, and confirm the Mayhem menu appears.
4. From then on, update with the on-device Flash Utility (method 1) and only re-extract the SD archive when a release calls for new card contents.

3.4 Recovering a device that will not boot

Because the desktop hackrf_spiflash path talks to the HackRF directly rather than through the PortaPack UI, it is the reliable recovery route: put the device in HackRF mode (or use the hardware DFU button if the screen is unresponsive) and rewrite a known-good .bin. A mismatch between a very new firmware and old SD-card contents is a common cause of missing apps or odd behavior after an update; refreshing the card from the matching release’s archive usually resolves it.

Continue to Volume 4 for the SD-card layout and file formats.