XZG Multi-tool

---

📖 About

The XZG Multi-Tool is a browser-based flashing solution that enables hobbyists and developers to program Texas Instruments, Silicon Labs, Espressif, Arduino and Telink devices. It provides a simple, polished web UI that enables users to flash adapters directly from the browser, eliminating the need for client software installation.

The web front end performs local flashing via the WebSerial and WebUSB APIs, offering automatic device detection and convenient firmware flashing features. The bridge component (WebSocket ↔ TCP) enables headless or remote hosts to expose local serial ports via TCP and connect them to the web UI. The bridge also supports connecting to remote TCP-based adapters, enabling access to networked adapters from any browser.

⭐ Features

• 🔌 Work with various devices locally via WebSerial/WebUSB or remotely via bridge.
• 📂 Flash firmware from a local file or select from a provided list.
• 📝 List of cloud firmware with descriptions
• 🦾 Automatically detects chip model, flash size, IEEE, and firmware version
• 💾 Backup, restore, and erase NVRAM

💻 Supported Chips

For a complete, up-to-date list of supported devices, features, and device-specific notes, see the devices table.

🏗️ Architecture

🚀 Quick start

🔌 Local USB

🌐 Open: mt.xyzroe.cc
from Chrome or Edge

📡 Remote (TCP or remote USB/serial)

Because browsers don't support TCP connections you need to use WebSocket ↔ TCP bridge that can forward WebSocket clients to TCP hosts and as option expose local serial ports over TCP.

You have some options:

🏠 Home Assistant Add-On

Just click on the button above or add this repository to your Home Assistant add-on store manually and then install the add-on to expose remote TCP / host serial devices to the web UI.

🐳 Docker images

Prebuilt multi-arch images are published to GHCR on each release.

Latest image: ghcr.io/xyzroe/XZG-MT:latest
Special version image: ghcr.io/xyzroe/XZG-MT:<tag> (e.g. v0.1.1)

Running instructions:

- Run (basic):

docker run --rm -p 8765:8765 ghcr.io/xyzroe/XZG-MT:latest

• Run with mDNS:

docker run --rm --network host ghcr.io/xyzroe/XZG-MT:latest

• To expose a host serial device to the container add --device (Linux):

docker run --rm --network host \
  --device /dev/ttyUSB0:/dev/ttyUSB0 \
  ghcr.io/xyzroe/XZG-MT:latest

• Customize port, advertised host, disable serial scan and enable debug logs:

docker run --rm \
  -e PORT=9000 \
  -e ADVERTISE_HOST=192.168.1.42 \
  -e DEBUG_MODE=true \
  -p 9000:9000 \
  ghcr.io/xyzroe/XZG-MT:latest

📦 Prebuilt binaries

Download a ready-to-run binary from Releases, make it executable (Linux/macOS), and run.

⚡ How to run:

Windows:

• Run: XZG-MT-windows-*.exe or double click

Linux:

Select the correct binary for your platform

• linux/arm64 — aarch64_generic, aarch64, arm64
• linux/arm — armhf, arm_cortex-a7_neon-vfpv4, arm_cortex-a9_neon
• linux/amd64 — amd64
• linux/386 — i386 / 32-bit x86
• linux/mips — mips_24kc
• linux/mipsle — mipsel_24kc
• linux/mips64 — mips64
• linux/mips64le — mips64le

Note: linux/arm targets ARMv7 (GOARM=7). MIPS and MIPSLE builds use GOMIPS=softfloat for compatibility with older devices (for example, MT7688).

1. Make executable:

chmod +x ./XZG-MT-linux-*

2. Run: ./XZG-MT-linux-* or double click

macOS:

1. Make executable and remove quarantine:

chmod +x ./XZG-MT-darwin-*
xattr -d com.apple.quarantine ./XZG-MT-darwin-*

2. Run: ./XZG-MT-darwin-* or double click

To run on custom port: ./XZG-MT-* 9999

📚 Where to read more

For step-by-step guides and detailed documentation, explore the following:

• 📚 How-To Guides: Start here
• 🌐 Web UI: README
• 🚀 WebSocket bridge — README
• 🏠 Home Assistant add-on: README
• 🤖 AI Generated Wiki: DeepWiki

👥 Community

💖 Support

If you find this project useful and want to support further development, you can sponsor or donate to the author:

Thank you — every little contribution helps keep the project alive and maintained. 🙏

🌟 Star History

If you find this project useful, please consider giving it a ⭐ on GitHub!

🛠️ Tech badges

Below are key technologies used across the projects (click the badges for quick context):

📁 Repository structure

• web-page/ — The web frontend. Contains source TypeScript, build scripts, favicon and static assets.
• bridge/ - The small Go app that bridges WebSocket ↔ TCP, supports mDNS discovery and exposing local serial ports as TCP servers.
• xzg-multi-tool-addon/ — Home Assistant add-on wrapper for the bridge.
• docs - Folder consisting the documentation about this project.
• LICENSE — License for the whole repository (MIT).
• repository.json — repository metadata.

📜 License

MIT — see LICENSE for details.

🙏 Acknowledgements

Built on the shoulders of giants:

• Texas Instruments CCXX52 and CC2538 — inspired by
  • cc2538-bsl by Jelmer Tiete
  • zigpy-znp by Open Home Foundation
• Silicon Labs — inspired by
  • universal-silabs-flasher by Nabu Casa
• Espressif Systems — powered by
  • esptool-js by Espressif Systems
• Texas Instruments CC25XX
  • СС Debugger — inspired by
    • cc-tool by Scott Gustafson
  • СС Loader — inspired by
    • CC Loader by RedBearLab
    • CC Loader fork by Timo Kokkonen
• Arduino — inspired by
  • arduino-web-uploader by David Buezas
• Telink - inspired by
  • TlsrComProg825x by pvvx Viktor
  • TlsrComProg by pvvx Viktor
  • TLSRPGM by pvvx Viktor

---

_{Made with ❤️ from Berlin!}

---