# 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
```

- 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.

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
```