Support CH58x family

[chrysn]

Description

There's a RISC-V (RV32IMAC) chip family called CH58x (sometimes also CH5xx, prominently CH582 and CH583) from Nanjing Qinheng Microelectronics Co., Ltd. (https://www.wch.cn/ / http://www.wch-ic.com/).

The chips runs at 32MHz, feature around 0.5MiB flash, 30KiB RAM, BLE radio and dual USB (host and device), and uses as little as 1.8V at some devices. According to the data sheet, it uses a QingKe implementation of RISC-V.

Applications / boards

The chips are cheap in their category (LCSC has CH582 at 1.11USD single piece / 0.70USD in at 1000pcs).

A prominent example is the BadgeMagic badge also promoted as fossasia badge, which is a board with a 11x44 monochrome LED matrix, battery, and BLE/USB connectivity. The actual manufacturer is rarely ever mentioned, a Python application indicates it could be ShenZen LeSun Electronics Co.Ltd. Beware that there are different versions of what looks like the same badge with completely different hardware. (I have one of those to test with, as do @maribu and @nica-f).

Resources and qualities of implementation

This is what I found when quickly looking around, not comprehensive resources.

• There is what looks like a functional firmware replacement for the BadgeMagic at https://github.com/fossasia/badgemagic-firmware, which includes the BLE functionality and has basic USB support in a PR.
• Data sheets and further docs are available in English. It's not too verbose, but appears to be complete enough on the system side (interrupt description etc) and small peripherals. The USB documentation is terse (mostly registers), but that might suffice for users who have used a few USB hardware implementations already. The BLE part is not documented in detail (see below)
• The BLE radio is supported only through a vendor header file and a precompiled static library.
  I don't know the authoritative source of that one -- but it is included in the badgemagic repository.
• For the other peripherals, there is a nonfree but source-available implementation provided.
  I don't know the authoritative source of that one -- but it is included in the badgemagic repository.
  From putting the names of the object files in the static libraries with s/.o$/.c/ into search engines, there is no source for that one.
• There is a Rust hardware abstraction crate that provides a hardware abstraction layer, including embassy support. That one llinks in a lot of shipped precompiled static libraries. I didn't check whether there is source available for them.
• Debugging does not use standard JTAG/SWD techniques, but some custom protocol (WLINK/WLINKE?) that is loosely SWD based for which there are custom hardware and software tools. At least for the software there is a wlink command line tool that also has a good references section, and some work around making it available in OpenOCD.
• There exists a USB bootloader, at least in the badgemagic devices. I can't tell yet whether that is custom to the board manufacturer, provided by the chip manufacturer or even part of its ROM.
• Peculiarities
  • Perusing the badgemagic code shows that there are some BLE interrupt handler functions loaded as "high code" which are copied into and executed from RAM. I can't tell yet whether that is just a speed / power optimization, whether all interrupt code has to be executed from RAM, or whether something else is going on.
  • I didn't find any documentation on flash ROM writing / erasing outside the firmware update process.

Next steps

I don't have immediate plans of adding support; gathering data here so that we have a spot to gather data and interest inside RIOT.

[chrysn]

A few notes from digging further:

• Original programmer seems to be available through AliExpress only, eg. as WCH-LinkE from "WCH Official Store" (LCSC lists it as well, but doesn't have it).
  • Apart from vendor Windows tools, there are two that support that hardware: a dedicated wlink implementation and probe-rs. Generally be careful around the hardware and software, because the programmer comes in variants, the CHxxx devices are all but homogenous, and not every device is supported by every programmer. The wlink implementation docs contain an overview sheet.
    On the long run I'd hope that tools such as probe-rs or the blackmagic probe will also speak the protocol, at least big-banging through the host (IDC how slow it is if it means I don't have to go through AliExpress again).

[chrysn]

A few field notes for anyone who wants to do this:

• I got my hands on what is advertised as the CH582M-EVT / CH582M/CH583M Evaluation Board, labelled "[WCH logo] [something Chinese] https://wch.cn" "CHM582M-R0-1v0" and no other silkscreen print other than parts (via the AliExpress "WCH Official Store", part)
  • I didn't find its pinout, although most is self-explanatory from the silkscreen. There is a "documented" (Chinese text but it has at least a low-resolution bitmap image of the schematic) board on OSHWhub that looks very similar, is not identical (button positions, ceramic antenna instead of printed), but my best guess is that someone made a pin-compatible clone board -- that's where I got the LED pins from.
• The bootloader seems to be pretty universal in that it is not just on the badgemagic devices, it is also present on that board. With the shipped firmware USB does nothing when plugged in, but when pressing the "Download" (S3) button on power-up (via power switch), the bootloader is visible for a few seconds as a USB device.
• The Wlink programmer I got (ordered "Wlink", got "WlinkE"?) is recognized by probe-rs, but has two modes, and the wlink tool can switch between them. Default mode is DAP. probe-rs recognizes it in DAP mode, wlink itself does things mainly in the RV mode. I didn't get wlink to do anything more than to do switching, though, presumably because the debug port is off by default and has to be enabled through the USB bootloader. At that point I stopped using Wlink and focused on what can be done through the bootloader (esp. because I expect that for the bulk of RIOT use, that bootloader would be relevant).
• The USB bootloader can be accessed with wchisp (to which also the wlink tool documentation points); it recognizes the device in the few seconds after boot when the Download button was pressed, can read some EEPROM, and show configuration registers (eg. that the debug port is disabled and the bootloader is enabled).
• There is some nice example code at https://github.com/Slappy2022/ch58x-hal. In particular, the blinky example can be built and flashed with cargo run --example=blinky, which calls out to wchisp.
  • The board is a bit odd (not bad but unusual) in that the LEDs connected to the header pins LED0 and LED1 are not connected to the MCU. If you want to see the LED blink, you have to pick the right GPIO pin (by default PB4) and wire it up to one of the LED pins with an F-F jumper cable.

Here's a udev rules file that is serving me well (/etc/udev/rules.d/54-wch-link.rules):

# WCH-Link debug probe
# 8012 is the default DAP mode, 8010 is when it is switched to RV mode (using `wlink mode-switch --rv` with tool from https://github.com/ch32-rs/wlink)
SUBSYSTEMS=="usb", ATTRS{idVendor}=="1a86", ATTRS{idProduct}=="801[02]", GROUP="plugdev", MODE="0660"
# WCH devices in bootloader mode
SUBSYSTEMS=="usb", ATTRS{idVendor}=="4348", ATTRS{idProduct}=="55e0", GROUP="plugdev", MODE="0660"

[chrysn]

Beware that the referenced ch58x-hal is an older version, nowadays https://github.com/ch32-rs/ch58x-hal provides that crate. Which is nice because it also has BLE support (based on a statically linked library; same goes for their EEPROM access and flash write access), but the blinky example only works half (it flashes the LED and then doesn't do anything further), which I haven't tried to debug yet.