Table of contents

• Highlights
• Download
• Supported hardware
• Quick start
• Flashing firmware
• Install — from source
• CLI
• Run the test suite
• Project layout
• Building distributable binaries
• Roadmap
• License & credits
• Contributing

Highlights

• Fully offline, portable, no installer. The Windows .exe (~71 MB) bundles the Python interpreter, Qt, the toolkit code and all 9 firmware images — drop it on a USB stick and you have a complete radio-maintenance kit you can plug into any PC at a hamfest, club meeting or field site without touching a network.
• One-click flashing of bundled firmwares. The Firmware tab ships 9 verified .bin images — F4HWN open-source builds and Quansheng stock — with an anti-brick allowlist that refuses any combination not matching the live bootloader version.
• Live LCD mirror over USB. See the radio's screen in real time on the desktop, save PNG screenshots. Verified end-to-end on F4HWN UV-K1(8) v3 / UV-K5 V3.
• CHIRP-compatible channel CSV. Import and export the channel grid in the same 21-column format CHIRP uses, with scan-list assignments encoded in the Comment column for clean round-trip.
• Calibration dump · verify · restore. One-click backup of the per-unit RF trim, plus a Verify pass that re-reads the radio and diffs it byte-for-byte against the saved .bin so you know the dump is stable before you ever rely on it. Two-dialog confirmation on restore, profile-aware byte-count check, jump-to-region hex viewer.
• DTMF contacts editor. Full 16-slot phonebook at EEPROM 0x1C00, with validated input (printable ASCII names, DTMF chars 0–9 A–D * #).
• Settings editor. Every named setting in the F4HWN 5.x and stock registries (~110 entries combined), with live search, modified counter and one-click revert.
• Read-only hex viewer with jump-to-address and hex-pattern search — the right tool when you need to look at something the GUI doesn't surface yet.
• Anti-brick DFU flash — bootloader allowlist, three-stage confirmation, validated on UV-K5 V3 (F4HWN 4.3 / 5.4) and UV-K1 standard (F4HWN 5.4).
• Cockpit-themed UI (5 palette families × Light/Dark), wheel-edit guard on numeric fields so you don't accidentally change a value while scrolling the page.
• 377 offline tests + CI on Windows / macOS / Linux × Python 3.11 / 3.12 / 3.13. No hardware needed for the test suite.

Download

[!TIP] Windows users — easiest path. A single self-contained .exe is published on every release. Python interpreter, Qt and all 9 bundled firmwares are embedded — no installer, no internet needed after download.

1. Open Releases.
2. Download quansheng-toolkit.exe from the latest tagged release (~71 MB).
3. Double-click to launch.

[!NOTE] First launch on Windows. SmartScreen will warn about an "unrecognised publisher". Click More info → Run anyway. The binary isn't code-signed yet (signing certificates are paid; on the roadmap).

Fully offline by design

The toolkit makes zero network calls during normal operation — read/write EEPROM, edit channels, flash firmware, dump calibration, mirror the LCD: everything happens locally. The bundled firmware images live inside the binary; the SHA-256 manifest is shipped with the package; even the help text is local.

The only thing that ever touches the network is clicking a release-link inside one of the firmware info cards (those open in your default browser, outside the toolkit).

This makes the toolkit ideal for:

• 🛠️ Field maintenance — a USB stick with quansheng-toolkit.exe is a complete portable kit
• 🛡️ Air-gapped environments — emergency-comms setups, restricted networks
• 🔒 Privacy-conscious users — your radio data never leaves your machine
• 🌐 Bad-internet locations — hamfests, contests in remote sites, basements

For macOS and Linux, build from source — see Install — from source. The from-source install needs the network only for pip install; after that it's fully offline too.

Supported hardware

Quick start

1. Connect the radio via USB-C (K1 family) or CH340/CH9102 cable (K5 family).
2. Launch the toolkit:
   • Windows: double-click quansheng-toolkit.exe
   • From source: python -m quansheng_toolkit.gui
3. Open Dashboard → Read EEPROM to pull the radio's current state into memory.
4. Edit channels / scan lists / settings / DTMF contacts / boot logo as you like — every change is buffered locally, nothing is written to the radio yet.
5. Click Apply Changes (top-right of the window) to upload the modified image. The upload is verified byte-for-byte against a re-read; if any 64-byte block didn't persist, it's automatically retried.

[!IMPORTANT] Always do a Read first before editing. The Dashboard shows the live image — if you edit before reading, you're working against an empty buffer and Apply will overwrite the radio with zeros.

Flashing firmware

[!CAUTION] Flashing is destructive and irreversible. The wrong firmware can brick the radio. The toolkit's allowlist verifies the bootloader version before allowing the flash, but if you bypass that with Custom .bin, you're on your own.

The Firmware tab guards the destructive flash path with three layers of confirmation and an anti-brick allowlist that refuses incompatible bootloader/firmware combinations.

To flash:

1. Power off the radio with the USB cable connected.
2. Hold PTT + Side Key 2 while powering on. The LCD stays blank — that's bootloader (DFU) mode.
3. In the toolkit, click Detect DFU bootloader. The toolkit reads the bootloader version, identifies the radio, and filters the bundled-firmware dropdown to compatible builds.
4. Either pick a bundled firmware (F4HWN or Quansheng stock) and click Flash selected bundled firmware, or use Custom .bin for an external file.
5. Three confirmation dialogs (DFU reminder → optional file picker → last-chance confirm) before any byte is written.

Validated combinations:

Install — from source

Required: Python 3.10 or newer.

git clone https://github.com/knoinok/quansheng_toolkit.git
cd quansheng_toolkit
py -3.13 -m pip install -r requirements.txt PySide6
py -3.13 -m quansheng_toolkit.gui

brew install python@3.13
git clone https://github.com/knoinok/quansheng_toolkit.git
cd quansheng_toolkit
python3 -m pip install -r requirements.txt PySide6
python3 -m quansheng_toolkit.gui

[!NOTE] CH340/CH9102 cable users: install the WCH driver from https://www.wch-ic.com/downloads/CH34XSER_MAC_ZIP.html. The UV-K1's native USB-C bridge needs no driver.

sudo apt install python3 python3-pip python3-venv     # or distro equivalent
git clone https://github.com/knoinok/quansheng_toolkit.git
cd quansheng_toolkit
python3 -m venv .venv && source .venv/bin/activate
pip install -r requirements.txt PySide6
python3 -m quansheng_toolkit.gui

Add yourself to the serial-port group:

sudo usermod -aG dialout $USER     # Debian/Ubuntu
sudo usermod -aG uucp $USER        # Arch/Fedora
# log out and back in

For a stable USB-C device name, drop a udev rule:

echo 'SUBSYSTEM=="tty", ATTRS{idVendor}=="36b7", ATTRS{idProduct}=="ffff", MODE="0660", GROUP="dialout", SYMLINK+="quansheng_uvk1"' | sudo tee /etc/udev/rules.d/99-quansheng.rules
sudo udevadm control --reload-rules && sudo udevadm trigger

CLI

Every GUI feature is also available headless — handy for scripting and CI.

python -m quansheng_toolkit info             # handshake + firmware version
python -m quansheng_toolkit read -o cur.bin  # full EEPROM dump
python -m quansheng_toolkit list             # decode channels (live or --from-file)
python -m quansheng_toolkit show-settings    # every named setting
python -m quansheng_toolkit list-settings    # every key `make-bin --set k=v` accepts

# CSV-driven channel patch with scan-list assignment derived from the Comment column
python -m quansheng_toolkit make-bin -i cur.bin --csv ch.csv \
    --derive-from-comment -o patched.bin --show

python -m quansheng_toolkit apply-full --