badgemagic-firmware targets one chip and 44 columns, and a wrong flash is permanent

One variant, and the check is two numbers

The compatibility scope is unusually narrow and stated as such: one specific badge variant, with a WCH CH582M RISC-V chipset and an 11x44 LED matrix, whose OEM firmware commonly advertises the Bluetooth name `LSLED`.

After flashing, the default BLE device name becomes `LED Badge Magic`, which is how you tell open firmware from OEM firmware over the air.

The problem the README spends most of its warning budget on is that many badges look identical and ship with the same `LSLED` name, while differing internally in chipset or grid size, for example 11x44 against 11x55. Identical appearance and identical OEM BLE name do not guarantee compatibility.

So there is a verification procedure, and it is two physical checks:

1. Open the badge and read the chip marking on the PCB. It must read CH582M. 2. Count the LED columns. There must be 44, not 48, not 55, not anything else.

If you are unsure, the instruction is to not flash. Hardware photos and further identification help are in CH582.md.

Compatibility with other variants such as the LeSun B1144 and other Alibaba-sourced clones is not established, with pinout reverse engineering still in progress. That sentence is doing a lot of work: it means the project knows the hardware it works on and says plainly that it does not know the hardware it does not.

The consequence of guessing is stated without hedging. The OEM firmware is read-protected and cannot be dumped, so once overwritten there is no recovery path, and issue #59 is cited as a real example of a badge being bricked this way.

Two ways into ISP mode, and one of them is gone after the first flash

The WCH CH582M enters its ISP bootloader when the boot pin is pulled low during power-up. The README gives two physical procedures.

The first is the straightforward one: disconnect the battery, press and hold KEY2, the button near the USB port, and plug in USB.

The second keeps the battery connected: connect USB, hold KEY2, then short and release the C3 capacitor using metal tweezers or a wire. CH582.md explains electrically why both work.

The second method has a hardware trap. The photos show two different revisions, Micro-USB and USB-C, and C3 sits in a different position on each board. Identifying your revision first is not optional if you are going to short a capacitor.

You know you are in ISP mode when a single pixel roughly in the middle of the display lights up. The badge stays there for about ten seconds before rebooting into normal mode, which is a short window if you are fumbling with tweezers.

On Linux you can confirm from the kernel log rather than by eye, looking for the device with `idVendor=4348` and `idProduct=55e0`:

dmesg

The good news is that this difficulty is temporary. Once the open firmware is installed, the README says there is no further need to remove the battery or short C3, because a long-press of KEY2 enters ISP mode directly.

That is a genuinely useful property of the open firmware: it removes the sharpest edge of the installation process for anyone updating later.

Flashing with wchisp, and a reset step before the write

Flashing is two commands with wchisp:

wchisp config reset
wchisp flash badgemagic-ch582.bin

The `config reset` before the write is not cosmetic. It clears the chip configuration so the new firmware starts from a known state rather than inheriting whatever the OEM firmware left behind.

You need wchisp installed, and you need a binary: either from the releases page or from the `bin` branch, which carries the latest development builds. The `bin` branch is the one to use if you are reproducing a bug against current development rather than shipping.

On Windows there is a GUI alternative, wchisp studio from WCH. Connect the badge over USB, enter ISP mode as above, and the device appears in the interface on its own. You select the `badgemagic-ch582.bin` file and click Download. The `.elf` file also works, which matters if you built the firmware yourself and want to flash the unstripped artifact.

Build the firmware with make, and the toolchain is a community mirror of MounRiver Studio rather than a vendor download, pinned to version 1.92:

export PREFIX=../MRS_Toolchain_Linux_x64_V1.92/RISC-V_Embedded_GCC/bin/riscv-none-embed-

The vendor's own MounRiver download is struck through in the tools list as removed, which is why the community mirror exists and why the pinned version number is stated exactly.

Hardware variants are selected with make variables. The default builds the second generation, previously known as the USB-C version. `BUILD_DIR=custom-dir HARDWARE_REV1=1 make` targets the Micro-USB version, and `HARDWARE_REV3=1` the third generation. The Makefile also carries `KEY_COUNT`, defaulting to 4 and settable to 2 for two-key hardware, and a `DEBUG = 1` line commented out. Switching `HARDWARE_REV*` requires a clean build, which the README flags in a note.

Three transfer paths, and the serial one is the easy one

Once flashed, a bitmap can reach the display three ways, and the differences are about data width and convenience.

Over BLE the data format is documented in BadgeBLE.md, and the width is 16 bytes per chunk.

Over USB HID the format is identical, only 64 bytes wide instead of 16. The endpoint is at Interface 0x00 and Endpoint 0x01, with the README warning that interface number and endpoint address might not always be fixed and that any application should check them before using. That warning is about exactly the failure mode HID libraries produce when these values shift between revisions.

Over USB CDC ACM, which the README calls similar to HID but more convenient, the device appears as a serial port and you can write to it with no library at all:

stty -F /dev/ttyACM0 raw && cat bitmap.bin > /dev/ttyACM0

One command, no dependency, the same bitmap format. If you are scripting something against this hardware, this is the path to use.

The version of the running firmware is readable three ways, which matters more than it sounds: a badge with old firmware installed is hard to identify otherwise. Over BLE it follows the Bluetooth Device Information service, reading the Firmware Revision String characteristic `0x2A26` in the Device Information Profile `0x18A`. Over USB it comes from the USB Serial Number String. And on the device itself, while charging, it displays an animation followed by the version repeatedly.

Normal usage is documented elsewhere: badgemagic-app is the companion mobile app, and led-name-badge-ls32 is the other FOSSASIA project in this family.

The version stamp is taken from git, so a dirty tree builds dirty

The Makefile has a detail that tells you how releases are cut.

VERSION = $(shell git describe --tags --dirty)
VERSION_ABBR = $(shell git describe --abbrev=0 --tags 2>/dev/null || echo "unknown")

with a guard that emits a Make warning when no tag can be determined. So the version baked into the firmware is whatever `git describe` returns, including the `-dirty` suffix when the working tree has uncommitted changes.

That means a build from an untagged tree still identifies itself, which is the right behaviour for firmware: if a badge reports a version, that string tells you whether it came from a release or from someone's half-finished working tree.

There is one release, v0.1, tagged on 2024-09-08 and titled for a first release with Micro-USB only. Since then the repository has continued to change: the last push was on 2026-08-28, and the README documents second and third generation hardware variants that postdate the tag.

So the released binary and the documented hardware support are not the same thing. The `bin` branch with its development builds exists precisely for the gap, and anyone targeting USB-C or third generation hardware should be building from source rather than trusting v0.1.

The source layout has a vendored `CH5xx_ble_firmware_library/` directory with the WCH standard peripheral driver sources listed explicitly in the Makefile, `src/` for the firmware itself, `assets/` for the images, and `example/streaming.sh`. Licence is Apache-2.0, and the project homepage is https://badgemagic.fossasia.org.

Editorial conclusion

badgemagic-firmware is the right choice if you own one of the CH582M badges with 44 columns and want Bluetooth and USB control under open firmware rather than the vendor's, since both the BLE bitmap format and the USB CDC ACM path are documented. It is the wrong choice if you cannot confirm the chip marking and the column count, because the README states the OEM firmware cannot be dumped and there is no recovery path. Before running `wchisp flash badgemagic-ch582.bin`, open the badge and check that the PCB marking reads CH582M and count 44 columns, and if either check fails, stop.

Frequently asked questions

Official sources

1. fossasia/badgemagic-firmware on GitHub
2. License: Apache-2.0
3. Project website
4. README
5. Releases