Skip to content

Troubleshooting FAQ

Jump to bottom
knoinok edited this page May 7, 2026 · 2 revisions

Troubleshooting & FAQ

Toolkit doesn't see the radio

Checklist:

  1. Is the cable USB-data, not USB-power-only? Many cheap USB cables, especially USB-C-to-USB-A, are charge-only. Try a known-good cable (e.g. one that carries data for a phone).
  2. Is the radio powered on and in normal mode? (LCD shows the boot logo / channel display, not blank.)
  3. Does the OS see the device?
    • Windows: Device Manager → Ports (COM & LPT) — look for an entry like USB-SERIAL CH340 (COM3) (CH340 cable) or USB Serial Device (COM3) (UV-K1 native).
    • macOS: ls /dev/cu.* — look for cu.usbserial-XXXX (CH340) or cu.usbmodemXXXX (UV-K1 native).
    • Linux: dmesg | tail after plugging in — should mention ch341-uart or cdc_acm.
  4. On Windows: do you have the CH340 driver? Windows 10/11 ships it via Update; older Windows needs manual install: https://www.wch-ic.com/downloads/CH341SER_EXE.html.
  5. On macOS: do you have the WCH driver? Required for CH340/CH9102 cables: https://www.wch-ic.com/downloads/CH34XSER_MAC_ZIP.html.
  6. On Linux: are you in the right group? groups | grep -E 'dialout|uucp'. If not: sudo usermod -aG dialout $USER and log out/in.

If all of the above check out and python -m quansheng_toolkit info still fails, open an issue with the OS, cable type, radio model, and the exact error.

Apply Changes fails / verification mismatch

The toolkit performs byte-for-byte readback verification of every 64-byte block during apply. If a block doesn't match the intended image, the toolkit retries it. If retries are exhausted, you get an error.

Causes, in rough order of frequency:

  1. Bad cable — same cause as "doesn't see the radio". Marginal cables drop bytes mid-write but the connection still survives. Replace the cable.
  2. USB hub between PC and radio — connect directly to a motherboard USB port. Hubs (especially passive ones) introduce latency that the protocol doesn't tolerate.
  3. Stock K5 V3 — the firmware silently rejects writes. See the next section.
  4. Power-saving / USB selective suspend — Windows can suspend the USB port during a long write. Power Options → Change advanced → USB settings → USB selective suspend → Disabled.

If you see a per-block error message in the log, that block's address is shown. Do not power-cycle the radio — re-run apply-full and the retry will pick up where it left off. The image on the radio is in a partially-written state until the apply completes successfully.

DFU mode doesn't start / dfu-info fails

DFU mode is a precise key combination:

  1. Power off.
  2. Connect USB cable (powered).
  3. Hold PTT and Side Key 2 firmly.
  4. While holding both, rotate the power knob to on.
  5. LCD must stay completely blank — no logo, no backlight.

Tip

A trick: start holding the keys before turning the radio on. If you start holding after, the firmware may have already booted past the bootloader-handoff window.

If the LCD lights up: you missed the timing. Power off, wait 2 seconds, try again.

If the LCD stays blank but dfu-info reports "no response": the cable, the OS device entry, or the driver. Run the doesn't see the radio checklist.

If dfu-info works but flashing fails: see the cable / hub / power-suspend points above.

Stock K5 V3: writes succeed but nothing changes

The Quansheng stock firmware on UV-K5 V3 (versions 7.00.x) silently rejects EEPROM writes at the firmware level. The protocol acknowledges, the toolkit's verify also matches because the radio echoes the buffer it would have written — but the persistent EEPROM is never modified. After a power-cycle, your edits are gone.

This isn't a toolkit bug. Every open-source toolkit (Multi-UVTools, UVTools2, CHIRP-with-K5-driver) hits the same wall on stock K5 V3. The only known fix is to flash F4HWN, which is open-source and writes work normally.

The toolkit detects this scenario after apply-full (the post-write read shows the original bytes) and prints a warning.

Windows SmartScreen blocks the .exe

SmartScreen flags any unsigned executable from an untrusted source. The toolkit's .exe isn't code-signed (signing certs are paid; on the roadmap).

Workaround: More info → Run anyway. To verify the file is genuine, compare its SHA-256 against the value listed on the Releases page:

  • Windows: certutil -hashfile quansheng-toolkit.exe SHA256
  • PowerShell: Get-FileHash quansheng-toolkit.exe

The .exe takes ~10 seconds to start

PyInstaller's --onefile mode unpacks the bundled Python interpreter and Qt to a temporary directory on every launch. First launch is slowest because the OS hasn't cached the files yet; subsequent launches are quicker.

If startup is consistently slow: try a non-system drive (e.g. SSD), or build from source which avoids the unpack step.

Wheel scroll changes settings instead of scrolling the page

The toolkit's wheel-edit guard is supposed to prevent this, but in older versions it didn't catch all widget types. Update to the latest release.

If you can repro on the latest version, open an issue with the page name and the widget you scrolled over.

GUI looks broken / fonts wrong / dark theme white

  • Wrong-looking fonts on Linux: install a system fallback font like fonts-inter or fonts-liberation.
  • High-DPI scaling weird on Windows: Settings → System → Display → Scale. Try 100%, 125%, 150%. Qt sometimes mis-handles fractional ratios on multi-monitor setups.
  • Dark theme not applying: Toolkit Settings → Theme. The cockpit themes default to Dark; if you see Light, the theme system fell back to OS native. Re-pick a cockpit family from the dropdown.

CSV import: scan-list assignments not preserved

Make sure you're using --derive-from-comment (CLI) or Channels → Import CSV → Derive scan list from Comment column (GUI). Without that flag, scan-list assignments aren't read from the Comment column and default to OFF.

I bricked my radio

See Flashing Firmware → Recovery. Most "bricks" are recoverable from DFU mode — re-flash the right firmware. If DFU mode itself is dead, the cable is the most common cause; try a different cable on a different USB port before assuming hardware failure.

Can I use the toolkit fully offline?

Yes — fully. Both the GUI and the CLI work without any internet connection.

  • The single Windows .exe ships everything bundled (Python interpreter, Qt, the toolkit code, all 9 firmware images and the manifest) — no network calls during normal operation.
  • From-source installs depend on the network only at install time (pip install); after that, run python -m quansheng_toolkit.gui from anywhere.
  • The only thing that touches the network is clicking a release-link inside one of the firmware info cards (those open in your default browser).

Tip

Carry a USB stick with quansheng-toolkit.exe and a folder of per-radio backups. You have a complete portable maintenance kit you can plug into any Windows PC at a hamfest, club meeting or remote site — no internet required.

Does it support [some other radio]?

See Hardware Compatibility for the full matrix. Short version:

  • Yes: UV-K1, UV-K1(8) v3 Mini Kong, UV-K5 V3 (PY32F071 family).
  • Untested but should work read-only: UV-K5, UV-K5(8), UV-K6, 5R+ (DP32G030 family — same protocol, different MCU).
  • Roadmap: UV-TK11 Taiko Kong.
  • Out of scope: UV-5R+, Baofeng / Radtel / TYT clones.

If your radio talks the same EEPROM protocol but isn't on the matrix, python -m quansheng_toolkit info will tell you. Don't write or flash without confirming the bootloader version first.

How does it differ from CHIRP / Multi-UVTools / UVTools2?

quansheng_toolkit CHIRP Multi-UVTools UVTools2
Channels CSV ✅ (CHIRP-compatible) ✅ ❌ ❌
F4HWN settings ✅ ~76 entries ❌ ✅ partial ✅
Calibration backup/restore ✅ with diff ❌ ❌ ✅
DFU firmware flashing ✅ anti-brick allowlist ❌ ✅ web-based ✅
Bundled firmwares ✅ 9 images ❌ ❌ download separately ❌ download separately
Live LCD mirror ✅ ❌ ❌ ✅
DTMF phonebook ✅ 16-slot editor ❌ ❌ ✅
Hex viewer ✅ ❌ ❌ ❌
Single-file .exe ✅ ✅ ❌ web-only ✅
Fully offline ✅ everything bundled ✅ ❌ requires browser + Web Serial ✅
Open source ✅ Apache-2.0 ✅ GPL-3 ✅ GPL ✅
Cross-platform ✅ Win/Mac/Linux ✅ ✅ web ⚠️ Windows-first

The toolkit's distinctive points:

  • Bundles 9 verified firmwares with sha256 manifest — one-click flash, no separate downloads, fully offline.
  • CHIRP-compatible CSV format — drop in your existing CHIRP exports without conversion.
  • Anti-brick DFU allowlist with three-stage confirmation.
  • Calibration diff — verify a flash didn't touch your factory tuning.

If you have a question not covered here, please start a Discussion. Common questions get folded back into this FAQ.

quansheng_toolkit · Apache-2.0 · Open-source desktop toolkit for Quansheng UV-K1, UV-K1(8) v3 Mini Kong and UV-K5 V3 radios · Fully offline.

quansheng_toolkit

Home

Getting started

Operations

Reference

Source · Releases · Issues · Discussions

Clone this wiki locally