quansheng_toolkit

• 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

• 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.

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

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.

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.

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:

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

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

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

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

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 --eeprom patched.bin
# Bootloader & DFU
python -m quansheng_toolkit dfu-info # bootloader detection (DFU mode)
python -m quansheng_toolkit dfu-flash --eeprom firmware.bin --target k1 --yes-i-understand

pip install -e ".[dev]"
pytest -q

377 unit tests covering protocol framing, channel/settings encoders, DFU brick-protection, DTMF contacts, display-mirror parser, hex-dump formatter, firmware-bundle loader. No hardware needed. CI runs the full matrix on every push.

quansheng_toolkit/
├── kradio/ # protocol, memory, settings, dfu, firmware
├── gui/ # PySide6 app
│ ├── views/ # one tab per concern
│ ├── workers.py # QThread workers for radio I/O
│ └── main_window.py
├── firmwares/ # bundled F4HWN + Quansheng .bin images
│ └── manifest.json # sha256-pinned list, per-target metadata
├── assets/ # app icon
├── cli.py # argparse subcommands
└── tests/ # offline pytest suite

CI builds Windows and macOS artifacts on every vX.Y.Z tag and attaches them to a draft GitHub Release:

git tag v0.3.0
git push origin v0.3.0
# → dist/quansheng-toolkit.exe (Windows)
# → dist/quansheng-toolkit (macOS)

The Windows .exe includes Python 3.13, PySide6, the toolkit code and all 9 bundled firmwares — no separate downloads needed.

To build locally:

pip install -e ".[dev,gui]" pillow
pyinstaller --onefile --windowed \
 --name quansheng-toolkit \
 --icon assets/quansheng-toolkit.ico \
 --collect-submodules quansheng_toolkit \
 --add-data "firmwares;firmwares" \
 --add-data "assets;assets" \
 launcher.py

(On macOS/Linux replace ; with : in --add-data.)

This project is licensed under Apache-2.0 — see LICENSE and NOTICE.

Read CONTRIBUTING.md for:

• the radio-safety policy (no destructive operation without explicit user confirmation; the anti-brick allowlist is sacrosanct);
• the bootloader-mapping process for new radios;
• the F4HWN channel-attribute trap that cost an evening of debugging on the UV-K1(8) v3 (band=7 marks an empty slot — encoding the actual band 0–6 from frequency is mandatory for the radio to recognise channels).

Bug reports and feature requests welcome via Issues. For longer discussions, use Discussions.