112 lines
4.1 KiB
Markdown
112 lines
4.1 KiB
Markdown
# ch32v203-bms
|
||
|
||
A simple battery management controller software.
|
||
|
||
## WeActStudio BluePill Plus CH32 Pin Labels
|
||
|
||
The BluePill Plus CH32 board from WeActStudio uses standard MCU port naming printed on the PCB silkscreen:
|
||
|
||
- PAx: GPIO Port A pins, labeled PA0 .. PA15
|
||
- PBx: GPIO Port B pins, labeled PB0 .. PB15
|
||
- PCx: GPIO Port C pins, commonly PC13 .. PC15 are broken out
|
||
- Other labels typically present: 3V3, 5V, G (GND), NRST (reset), BOOT (BOOT0), and SWD/RVSWD pads for programming/debug (SWCLK/SWDIO or similar).
|
||
|
||
For the exact header layout and picture of the silkscreen labels, please refer to the official WeActStudio documentation:
|
||
|
||
- https://github.com/WeActStudio/WeActStudio.BluePill-Plus-CH32
|
||
|
||
Pins used by this firmware (as referenced in `src/main.rs`):
|
||
|
||
- PA1: ADC analog input (combined Trigger/Threshold in the 555-timer example)
|
||
- PB0: Digital output (Q in the 555-timer example)
|
||
|
||
If you need to map a label to code, use the same letter+number as in the silkscreen. For example, `p.PA1` in code corresponds to pin labeled "PA1" on the PCB header, and `p.PB0` corresponds to "PB0".
|
||
|
||
## Building
|
||
|
||
``` sh
|
||
cargo build --release
|
||
```
|
||
|
||
## USB CDC Console (optional)
|
||
|
||
This project includes an optional software USB CDC-ACM device stack using embassy-usb. It runs on the CH32V203’s USB device peripheral but implements the protocol fully in software (no built-in USB class firmware is required).
|
||
|
||
How to enable:
|
||
- Build with the `usb-cdc` feature: `cargo build --release --features usb-cdc`
|
||
- Wire the MCU’s USB pins to a USB connector:
|
||
- D+ (PA12)
|
||
- D− (PA11)
|
||
- GND and 5V (as appropriate for your board; ensure you have a data-capable cable)
|
||
|
||
After flashing and powering via USB, your OS should enumerate a virtual serial port (e.g., /dev/ttyACM0 on Linux, COMx on Windows, /dev/tty.usbmodem* on macOS). Open it with any terminal program (baud setting is ignored by CDC but 115200 is fine).
|
||
|
||
Example:
|
||
- Linux: `screen /dev/ttyACM0 115200`
|
||
- macOS: `screen /dev/tty.usbmodemXXXX 115200`
|
||
- Windows: Use PuTTY on the shown COM port.
|
||
|
||
Notes:
|
||
- The firmware currently implements an echo console: bytes you type are echoed back. You can extend it to print logs or interact with your application.
|
||
- If you don’t see a device, ensure D+ (PA12) and D− (PA11) are connected and the cable supports data.
|
||
|
||
## Flash
|
||
|
||
You can flash the built ELF using wchisp (WCH ISP tool):
|
||
|
||
``` sh
|
||
wchisp flash target/riscv32imc-unknown-none-elf/release/bms
|
||
# or, if using a wrapper on your system/container, the command may be:
|
||
# wchip wchisp flash target/riscv32imc-unknown-none-elf/release/bms
|
||
```
|
||
|
||
## Unlock / Remove MCU Protection (fix "checksum error")
|
||
|
||
Some CH32 devices ship with flash protection enabled. When protected, tools may report a checksum error and refuse to program. You can clear the protection by performing a full chip erase with wchisp. This will erase all flash contents.
|
||
|
||
Steps:
|
||
|
||
- Ensure WCH-Link/WCH-LinkE is connected to the target and your OS has permissions to access it.
|
||
- Verify connection and current status:
|
||
|
||
``` sh
|
||
wchisp info
|
||
```
|
||
|
||
- Mass erase the chip (this also clears protection/lock bits):
|
||
|
||
``` sh
|
||
* start the device (while pressing boot)
|
||
wchisp erase
|
||
* powercycle the device (while pressing boot)
|
||
wchisp config reset
|
||
* powercycle the device again (while pressing boot), flash should not work
|
||
```
|
||
|
||
- Flash your firmware again:
|
||
|
||
``` sh
|
||
wchisp flash target/riscv32imc-unknown-none-elf/release/bms
|
||
```
|
||
|
||
Notes:
|
||
- The target used in this project is CH32V203C8T6; wchisp detects it automatically with WCH-Link.
|
||
- If your wchisp version differs, run `wchisp --help`, `wchisp erase --help`, or consult the tool's README for the exact flag name.
|
||
- If the tool still reports protection, look for commands named `unprotect` or `protect --off` in `wchisp --help`. The mass/chip erase is the typical way to clear protection.
|
||
|
||
## Debugging
|
||
|
||
For debugging purposes a container file is provided together with wrapper scripts to start the containerized `openocd` and `riscv-gdb` transparently. The wrapper scripts assume that `podman` is setup.
|
||
|
||
Starting Debug server
|
||
|
||
```
|
||
./bin/openocd
|
||
```
|
||
|
||
Connecting with gdb for interactive debugging
|
||
|
||
```
|
||
./bin/gdb -f target/riscv32imc-unknown-none-elf/release/bms
|
||
```
|