# ENVIRONMENT
there is a docker image that contains the entire toolchain + flashing utility. first, you need to build the base docker image with the following script located in the ch32v-insert-coin directory:
```shell
$ ./init.sh
```
once built, you won't need to build this again. for the remainder of your development, you can use the following script to launch the environment shell:
```shell
$ ./launch.sh
```

this will launch the docker image and give you a shell which has all of the toolchains and flashing utilities installed. to build the firmware image and flash it to the ch32 (assuming you have a wch-linke attached) run the following from inside the env shell: 

```shell
$ ./build-run.sh
```
this will build the firmware image, and attempt to upload it to the board using `wlink`. once uploaded, it will attach a serial debugger. 

to exit the serial debugger simply use `ctrl-c`. to exit the environment shell use:

```shell
$ exit
```

# FLASHING
flashing is done using the [`wlink`](https://github.com/ch32-rs/wlink?tab=readme-ov-file#install) utility. `probe-rs` also works, but can be flaky, and does not support SDI prints very well.

the `wlink` utility will automatically detect the correct chip, but if it doesn't you can specify it with an additional argument. 

`wlink --help` lists all the options to the `wlink` utility. 

## DEVELOPMENT
when building using the rust toolchain, you can simply add the following to your `.cargo/config.toml`:
`runner = "wlink -v flash`

if you want to monitor prints via SDI, you can use the following instead:
`runner = "wlink -v flash --enable-sdi-print --watch-serial"`

## STANDALONE
when flashing standalone with the `wlink` utility, you can simply run the following:
`wlink -v flash <PATH_TO_BINARY>`


# CH32V MISC NOTES
## SLEEP / DEEP SLEEP
it turns out you can not put the chip into deep sleep and have it wake up correctly until you power cycle it. WHAT THE FUCK. see page 36 of the [qingkev3 processor manual](https://www.wch-ic.com/download/file?id=368) at the bottom of section 6.1 Enter Sleep


# EVAL BOARD NOTES
## PINOUT
WCHLinkE SWDIO -> PD1



# AUDIO NOTES
## LIMITS
we have ~9-10kB of space remaining on the chip.
i can likely squeeze out _maybe_ another kB by dropping every print, but
that appears to cause some lockup, i think because the SDI peripheral is
trying to attach, but unable to.

for how things sit currently, we have the following (conservative) limits
to fit within 9kB:

16ksps, 4b depth -> 64kbps -> 1.125s
8ksps, 4b depth -> 32kbps -> 2.25s
6ksps, 4b depth -> 24kbps -> 3.0s
4ksps, 4b depth -> 16kbps -> 4.5s

in reality, the numbers i have seen are a little smaller than this, likely due
to compiler optimizations when the dac is unloaded / there's no audio.

a 16ksps file has an _experimental_ max of 0.75s. applying that offset
everywhere, we get empirical limits of:

16ksps, 4b depth: 0.75s
8ksps, 4b depth: 1.875s
6ksps, 4b depth: 2.625s
4ksps, 4b depth: 4.225s

## FFMPEG
use the following command to convert an input .wav to a raw mono pcm_u8 with 8ksps:
```shell
ffmpeg -i input.wav -f u8 -c:a pcm_u8 -ar 8000 -ac 1 output.raw  
```


# PINOUTS
LED0:          PC3
LED1:          PD2
DAC:           PC4
COIN SWITCH:   PC2
BUTTON SWITCH: PD6
ADC:           PD4
GPIO:          any remaining pin

## FORBIDDEN:
PD1