kv4p-ht: building the handheld ham radio firmware and Android app yourself

One repository holding a radio and a phone app

kv4p-ht is described simply as an open source handheld ham radio project, and the interesting engineering fact is that the radio is only half of it. The device is an ESP32 based handheld, and it is driven by an Android application. Both the microcontroller code and the phone software live in this repository, which is why the build instructions insist on producing both from one git revision.

The audience is specific. Someone who wants to run a handheld radio as shipped can install a public release from the project site at kv4p.com, and the README says the site is for that purpose. The repository is for the other case: a builder who wants to compile the firmware, modify the app, or work with the hardware design files. The repository's primary language is Java, which fits the Android side of the project.

The top level layout makes the split obvious. There is a microcontroller-src directory for the radio, an android-src directory for the phone application, and alongside them the physical design work: pcb for board files and 3d-print-case for the enclosure. A website-src directory holds the site source, and a .devcontainer directory is present for containerised development. That last entry matters more than it looks, since the build already spans two toolchains and a third one is not unusual.

Cloning the project and the two build targets

The clone step is conventional.

git clone https://github.com/VanceVagell/kv4p-ht.git
cd kv4p-ht

From there the work splits into two independent build targets that have to be kept aligned. The firmware is an ESP32 program built from microcontroller-src, and the app is an Android application built from android-src. PlatformIO is the preferred environment for the firmware, and the Arduino IDE is documented as an alternative in microcontroller-src/README.md. The Android app is built with JDK 17 in Android Studio, or from the command line.

The firmware build has one instruction that will trip you up if you miss it: open microcontroller-src as the project folder, because that is where platformio.ini lives, and do not open the repository root in PlatformIO. The root contains a lot that PlatformIO has no use for, and pointing it there is the difference between a build that starts and one that never does.

Because the two halves are separate builds, a plain clone gives you no guarantee that they match. The README is explicit that compiling the repository yourself means building both the ESP32 firmware and the Android app from the same git revision, which is the central instruction for anyone building from source here.

Building the ESP32 firmware with PlatformIO

The firmware instructions are deliberately short, and the detail is delegated to microcontroller-src/README.md, which the README points to as the place where PlatformIO and the Arduino IDE are both documented. Nothing about the firmware can be repeated here that is not in that file, and the repository does not give a release build command at this level.

What the repository layout does tell you is the shape of the firmware work. The microcontroller-src directory contains the platformio.ini file that PlatformIO expects, and it is a self contained PlatformIO project rather than a subfolder of a larger one. Whatever board definition and library versions that file pins are what your build will use, and there is no indication in the README that these are overridden at the command line.

Two practical consequences follow from the instructions as written. First, the Arduino IDE path is documented but secondary, so a first build with PlatformIO is the one the maintainer expects. Second, because there is no firmware compatibility check in a source build, a firmware that compiles cleanly is not the same as a firmware that matches the app you built. The next section deals with that gap, because it is the one that bites people who flash and pair without thinking.

The documentation stops at the boundary of the microcontroller directory. It does not describe a flashing utility, a boot mode, or a serial configuration, so anyone without an ESP32 toolchain already will need to read microcontroller-src/README.md before starting.

Assembling the Android app and finding the debug APK

The Android side has JDK 17 as its stated requirement and two ways to build it. In Android Studio you open android-src/KV4PHT. From a shell, the wrapper script does the work.

cd android-src/KV4PHT
./gradlew assembleDebug

The resulting debug APK has a fixed location in the tree, which the README spells out: android-src/KV4PHT/app/build/outputs/apk/debug/app-debug.apk. That path matters because a source build gives you an unsigned debug artifact rather than a release package, and the public release distributed on kv4p.com is a different thing entirely.

There is no mention in the README of a release variant, signing configuration or release task for the Android app. If you need a distributable build rather than something for your own device, you would be filling that gap yourself, and the README offers no guidance on it.

The privacy policy file at the top level, android-privacy-policy.txt, is worth a glance if you distribute a build you made. The repository carries it as a separate file rather than folding it into the app, so it is presumably needed for store listings. That is a reminder that this project targets devices that talk over the air and connect to a phone, and the distribution paperwork belongs to whoever ships the build.

The mismatch hazard the release build closes and a source build reopens

This is the sharpest engineering point in the documentation. In a release, the Android app carries a firmware resource bundled from the last public release, and that bundle is not refreshed until the next release. A release also includes a firmware compatibility check, so a mismatched app and radio will not connect.

In a source build, both of those protections are gone. The README states that in a source build there is no firmware compatibility check, so the app and radio will still connect even if they are out of sync. In other words, building from source removes the guardrail that tells you the pairing is wrong, and replaces it with silent misbehaviour at runtime.

The instruction that follows is therefore load bearing: flash the firmware and build the Android app from the same commit. The README frames the whole build section around this, and the two-code-block sequence of clone, firmware build, then app build exists to produce a matched pair.

For most builders the practical rule is to finish one commit and never mix. Do not flash new firmware and keep using an app built weeks earlier, and do not update the app from a new checkout while the radio still runs an older flash. Neither is blocked by the tooling. A version check that only exists in the shipped release is a weaker guarantee than the one a disciplined build process gives you.

Hardware files, FAQ and the boundary of the documentation

Beyond code, the repository carries the physical project. The pcb directory holds the PCB files and 3d-print-case holds the enclosure designs, so a builder who wants a different case or a board spin has a starting point in the same tree as the firmware and the app. The artwork directory holds artwork, and other-licenses.txt records licensing information beyond the project's own licence.

For troubleshooting there is a dedicated document, FAQ.md, listed under common problems. It is the file to read before anything else, because the README does not describe failure modes of its own: no notes on pairing, no radio behaviour, no guidance for a device that will not connect.

The project site at kv4p.com covers installation of a public release. The README does not reproduce installation steps there, so anyone who wants the radio running today should read that site rather than this repository. The division is sensible but it does mean the repository alone is not a complete guide to the device. The two builds, the flashing step and the physical hardware are documented at different levels of depth, and only the pairing instruction, the platformio.ini location and the APK path are given with enough precision to follow without asking someone else.

Release cadence, licence and the cost of owning the hardware

The project is not archived and the last push was on 2026-10-17, so work on the repository is current. The recent release list shows a steady line of tagged builds: v2.0.0.0 on 2026-05-22, v2.0.0.1 on 2026-06-01, and a nightly tagged build on 2026-09-06. A nightly tag alongside versioned releases suggests that pre-release builds are cut from the main branch rather than only at fixed points, which fits a project with a public site that distributes binaries.

The licence is GPL-3.0, with the licence text in a LICENSE file at the root and additional licence details in other-licenses.txt. Under those terms the source can be modified and redistributed, and hardware derived from the published design files carries the same expectation of source availability. That is a point to check against your own plans for the PCB and case files before treating them as a starting point for a commercial unit, and it is a licensing question rather than a technical one.

The cost side is the hardware itself, and the project makes it explicit that the two halves of the software are only half the effort. Owning the design means owning an ESP32 device, flashing firmware onto it, and running an Android application beside it. The README does not publish a parts list, so the components are not something you can extract from the repository without opening the PCB files.

Editorial conclusion

Build kv4p-ht yourself if you need to change the radio firmware or the Android app, or if you want the PCB and 3D printed case files in the same tree as the code, and be prepared to flash hardware and follow the microcontroller-src instructions. Install the public release from kv4p.com instead if you just want a working radio, since the released bundle pairs a known firmware with the app and adds a compatibility check that a source build drops. Before compiling, read FAQ.md and microcontroller-src/README.md, and plan to flash the firmware and assemble the app from the same commit so the two halves do not drift apart.

Frequently asked questions

Official sources

1. Issues
2. License: GPL-3.0
3. README
4. Releases
5. VanceVagell/kv4p-ht on GitHub