badgemagic-firmware

Hardware details and information to build an open firmware for Bluetooth LED badges, compatible with Badge Magic app

Supported Hardware

Warning: Flashing this firmware on an unsupported badge can brick it permanently. The OEM firmware is read-protected and cannot be dumped, so there is no recovery path once overwritten. See #59 for a real example of this happening.

This firmware targets one specific badge variant:

Chipset: WCH CH582M (RISC-V)
Display: 11×44 LED matrix
OEM BLE name often: LSLED

After flashing this firmware, the default BLE device name is LED Badge Magic.

Am I using the right badge?

Many LED badges look identical on the outside and often ship with OEM firmware advertising the same BLE name (LSLED), but differ internally in chipset or LED grid size (e.g. 11×44 vs 11×55). Identical appearance and OEM BLE name do not guarantee compatibility.

To verify your badge before flashing:

Open the badge and locate the chip marking on the PCB — it should read CH582M
Count the LED columns — there should be 44 (not 48, 55 or any other number)
If you are unsure, do not flash this firmware

For hardware photos and further identification help, see CH582.md.

Note: Compatibility with other badge variants (e.g. LeSun B1144 or other Alibaba sourced clones) is not established. Pinout reverse engineering for those boards is still in progress.

Installation

Install wchisp.

Download prebuilt binaries from release or the latest development builds.

Make the chip enter bootloader mode (ISP mode) by power cycling the chip while the boot pin is pulled down in one of two ways:

Disconnect the battery, press and hold KEY2 (the button near the USB port) while plugging in the USB to enter the bootloader.
Alternatively, connect the USB, press and hold KEY2, then short and release the C3 capacitor using metal tweezers or a wire.

See CH582.md for a technical explanation on why both the above methods work.

If the badge has successfully entered ISP mode, a single pixel roughly in the middle of the display will be lit. The badge will stay in ISP mode for approximately ten seconds before rebooting into normal mode.

On Linux, you can also check dmesg if the chip has entered the ISP mode with idVendor=4348 and idProduct=55e0.

Note: The photos shown below for option 2 show two different hardware revisions (Micro-USB and USB-C). C3 is in a different position on each board - Identify your revision before proceeding.

With the badge in ISP mode, run:

wchisp config reset
wchisp flash badgemagic-ch582.bin

Windows

On Windows, you have the option to install and run wchisp studio instead of the wchisp CLI tool. Connect the badge via USB and enter bootloader mode, per the instructions above.

The device will automatically appear in the UI.

Select the badgemagic-ch582.bin file and click 'Download'.

Where badgemagic-ch582.bin is the binary downloaded above, the .elf file also works.

Updating

Once the open source firmware is installed, there is no further need to remove the battery or short-circuit C3 to enter ISP mode. Simply long-press KEY2 to enter ISP mode. Then, flash updated firmware with

wchisp config reset
wchisp flash badgemagic-ch582.bin

Usage

For usual usages, please refer to badgemagic-app and led-name-badge-ls32.

Transferring Bitmap

over BLE

See BadgeBLE.md.

over USB HID

From the device perspective, the data format is just the same as the BLE Data Format. The only difference is the data width. It's 64 bytes, while BLE, is only 16.

Located at Interface 0x00 and Endpoint 0x01. Interface Number and Enpoint Address might not be always fixed, any app using this should check them before using.

For more detail about USB HID, please refer to USB HID Device Class Definition.

over USB CDC ACM

Similar to USB HID, but more convenient. From the host's perspective, it appears as a serial device, which can be interacted directly without the additional library. e.g. A bitmap.bin file with a format just like the BLE Data Format can be transferred to the badge by:

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

For more detail about USB CDC ACM, see Class definitions for Communication Devices 1.2.

Read firmware version from the badge

over BLE

This firmware was implemented following the BLE Device Information standard. Any device with BLE-capable can easily get the version by reading the value of the Firmware Revision String Characteristic (0x2A26) in the Device Information Profile (0x18A).

over USB

The version can be read from USB by reading the USB Serial Number String.

from the screen

While the badge is in charging state, it display a animation followed by a version repeatedly.

Development

Tools

GNU make
MounRiver Toolchain (removed)
MounRiver Toolchain (community mirror), specifically:
- MRS_Toolchain_Linux_x64_V1.92.tar.xz
wchisp

Build

Set the toolchain location, e.g.:

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

Simply run make to build the firmware for the second generation version (previously known as the USB-C version), with the output directed to the build/ directory. To build for the Micro USB version of the badge and specify a custom output directory:

BUILD_DIR=custom-dir HARDWARE_REV1=1 make

To build for the third generation hardware, simply replace HARDWARE_REV1=1 with HARDWARE_REV3=1.

[!NOTE]

Switching HARDWARE_REV* will require a clean build to make sure the new build does not contain the previous build blob. To rebuild:
make clean all

To flash the firmware, enter the bootloader, then run:

BUILD_DIR=custom-dir-if-needed make isp

Building and flashing per hardware variant

This firmware supports two independent build choices — you need to know both before building or downloading:

Board revision — controlled by HARDWARE_REV1 / HARDWARE_REV3 (see the Build section above for what each targets).
Button count — controlled by the new KEY_COUNT flag: KEY_COUNT=4 (default) or KEY_COUNT=2.

If you're not sure which board revision or button count your badge has, see CH582.md for identification help before flashing.

Building from source

Set the toolchain location first, as described in Build:

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

4-key badge, second-gen hardware (default):

make

4-key badge, Micro USB (first-gen) hardware:

BUILD_DIR=custom-dir HARDWARE_REV1=1 make

2-key badge, second-gen hardware:

BUILD_DIR=custom-dir KEY_COUNT=2 make

2-key badge, Micro USB (first-gen) hardware:

BUILD_DIR=custom-dir HARDWARE_REV1=1 KEY_COUNT=2 make

[!NOTE] Switching KEY_COUNT, like switching HARDWARE_REV*, requires a clean build so the new build doesn't contain the previous build's blob:
make clean all
This only matters if you're reusing the same BUILD_DIR for different variants. Building each variant into its own BUILD_DIR avoids the need for make clean between builds.

To flash directly after building, enter the bootloader (see Installation above), then:

BUILD_DIR=custom-dir-if-needed make isp

Flashing a pre-built release binary

Download the binary matching your hardware from releases:

badgemagic-4key-<rev>.bin — 4-key badges
badgemagic-2key-<rev>.bin — 2-key badges

Where <rev> matches your board revision, per CH582.md.

Then, same as any firmware update:

wchisp config reset
wchisp flash badgemagic-<variant>.bin

Long-press KEY2 to enter ISP mode first if the badge isn't already there. Flashing the wrong KEY_COUNT variant won't damage the badge, but menu navigation will be incomplete or stuck, since some button handlers expect hardware that isn't present — reflash the correct variant to fix it.

Debugging

Logging over UART

Currently, only the UART1 with baudrate=921600 is used for debugging. To enable the log from UART, set the DEBUG=1 when building the project.

Any USB to UART dongle will work. Use your favorite terminal emulator to see the log, e.g.:

picocom -b921600 /dev/ttyUSB0 --imap lfcrlf

The badgemagic-hardware have this UART wired over USB-C. So it can be used without opening the case, but required an aditional hardware to split the serial lines from USB-C.

Logging over USB CDC-ACM

This is convenient as it doesn't require additional hardware, but it may not be useful for early logging when the USB is not yet initialized, and the user cannot open the serial port quickly enough.

Use cdc_tx_poll() to log to this serial channel.

On-chip Debugging

This is a mystery.

Add a new BLE Profile

To create a new custom data exchange channel, add a new BLE profile to the firmware by duplicating /src/ble/profile/legacy.c and reconfig it. Rename xxx_registerService() function. Call this function after peripheral_init() to register your new profile.

For more detail of how to config a gatt service, see BLE GATT.

Add a new USB Composite Device

To add a new custom USB Composite Device (e.g., keyboard, mouse, speaker, etc.), duplicate src/usb/composite/hiddev.c. Rename and configure the file according to the Device Class you intend to implement, then call your device's xxx_init() function in usb_start() to initialize it. Each device class has specific specifications, so be sure to refer to them when implementing your new device.

Hardware Information

BadgeMagic target hardware features a custom 11x44 LED matrix display, Bluetooth LE and low power consumption.

Chipset

The design relies on a single MCU. MCU type has changed depending on manufacturer batches.

ARM M0 variant based on MM32L062PF
ARM M0 variant based on MM32W062
RISC-V variant based on CH582M

See specific pages regarding each version of the hardware below

Display

The custom 11x44 LED dot matrix displays using persistence of vision.

Bitmaps are drawn using 24 pins in [charlieplexing](https://en.wikipedia.org/wiki/Cha

badgemagic-firmware

工具介绍