README.md

# Gonk

[TOC]

## Getting Started

> **NOTE:** If you are using a `gonk_tools.zip` bundle follow the instructions in
> the `//tools` directory:
> https://pigweed.googlesource.com/gonk/+/refs/heads/main/tools/

1. Clone the repo

   ```sh
   git clone https://pigweed.googlesource.com/gonk
   ```

2. Source `bootstrap.sh` to download all compilers and tooling into the
   `environment` directory:

   ```sh
   . ./bootstrap.sh
   ```

   This should init all git submodules for you.

3. From here on the Pigweed environment is activated. You can activate the
   environment in a new shell without re-running bootstrap by sourcing
   `activate.sh`

   ```sh
   . ./activate.sh
   ```

## Capture ADC samples and plot

1. First bootstrap, run `pw build` and flash gonk using DFU.

   ```sh
   . ./bootstrap.sh
   ```

   ```sh
   pw build
   ```

   Unplug gonk from USB and replug with MODE button held down.

   Run `gonk-flash` on the MCU binary. This uses `pyfu-usb`.

   ```sh
   gonk-flash ./out/gn/arduino_size_optimized/obj/applications/gonk/gonk.bin
   ```

2. Start capturing ADC samples with:

   ```sh
   gonk \
     --bitstream-file DEFAULT \
     --log-to-stderr
   ```

   - Press `Enter` to stop or start ADC continuous updates. It will begin automatically on startup.
   - Press `ctrl-c` to quit.

3. Plot the logs from `gonk-csv-log.txt` with:

   ```sh
   python tools/gonk_tools/plot.py -i gonk-csv-log.txt -o plot.svg
   ```


## Compilation Details

Build for the host and device by running:

```sh
pw build
```

This is mostly a shortcut with nice output for running `gn gen out/gn` and
`ninja -C out/gn`.

The build commands are defined in: `//tools/gonk_tools/build_project.py`.

## Gonk Verilog Build

The Verilog build requires the following to be installed on Linux:

```sh
sudo apt install fpga-icestorm nextpnr-ice40 yosys
```

Running `pw build` will run the FPGA toolchain if these commands are available on the `$PATH`:

- `icepack`
- `icetime`
- `nextpnr-ice40`
- `yosys`

The bitstream files will be written with the `.bin` extenson under
`./out/gn/obj/fpga/*/*.bin` along with log output files.

For example:

```sh
$ ls ./out/gn/obj/fpga/toplevel/
nextpnr-log.txt
toplevel.asc
toplevel.bin
toplevel.json
toplevel_timing_report.json
toplevel_timing_report.txt
yosys-log.txt
```

## Gonk Firmware Build

Flash the stm32f7 and launch the `gonk.py` script on a bitstream file.

### Flash via DFU

1. Unplug gonk from USB and replug with MODE button held down.

1. Run `gonk-flash` which uses `pyfu-usb`. The `--bin-file` argument is optional.

   ```sh
   gonk-flash --bin-file ./out/gn/arduino_size_optimized/obj/applications/gonk/bin/gonk.elf
   ```

### Alternative: Flash with BlackMagic Probe

This is more useful if you are doing firmware debugging.

```sh
./scripts/flash-with-blackmagic-probe.sh ./out/gn/arduino_size_optimized/obj/applications/gonk/bin/gonk.elf
```

## Generating the Gonk Python Bundle

This is a distibutable python wheel that can be used without the Gonk
source checkout or compiling anything.

On Linux with the FPGA toolchain available run:

```sh
pw build
```

The zip file containing all the dependencies for the gonk python tooling is located in:

```sh
out/gn/obj/gonk_bundle.zip
```

Inside are the Python wheels for `gonk_dist`, `gonk_firmware`, and all
third_party dependencies.

```
gonk_bundle
├── python_wheels
│   ├── appdirs-1.4.4-py2.py3-none-any.whl
│   ├── astroid-3.0.1-py3-none-any.whl
│   ├── ...
│   ├── gonk_dist-0.0.1+20240305140627-py3-none-any.whl
│   ├── gonk_firmware-0.0.1+20240305140542-py3-none-any.whl
│   ├── ...
│   └── wheel-0.40.0-py3-none-any.whl
├── requirements.txt
├── setup.bat
└── setup.sh
```

## Appendix

### CSV Log Format

#### Fields

1. Host timestamp with format `%Y%m%d %H:%M:%S.%f`
2. Delta microseconds (elapsed microseconds since the last ADC read) on the STM32 microcontroller side.
3. 7 Voltage values
4. 7 Current values
5. 7 Power values
6. Comment text

Example separated into multiple lines (with an empty comment field)
```
20240813 14:16:35.176433,
283,
0.8148437500000001, 0.8892578125, 5.212109375000001, 1.087109375, 0.8904296875000001, 3.3820312500000003, 1.8125,
0.058447916666666676, 0.031546875, 0.13443125, 0.015902343750000002, 0.0009143518518518518, 0.16081250000000002, 0.004143750000000001,
0.04762591959635418, 0.02805330505371094, 0.7006703784179689, 0.01728758697509766, 0.0008141660337094908, 0.5438729003906251, 0.007510546875000001,

```

#### GPIO assert events in the CSV

When GPIOs are pulled LOW (to ground) a line in the CSV will appear
with delta_micros = 0 and empty measurement values. The Comment field will
contain the GPIO assert log message.

Example:

```
20240813 14:12:32.930888, 0,
,,,,,,,
,,,,,,,
,,,,,,,
Header pin assert: 2
```


### Compiling the FPGA Toolchain

#### yosys

See https://github.com/YosysHQ/yosys for more instructions.

On Ubuntu/Debian install the deps:
```sh
sudo apt-get install build-essential clang lld bison flex \
    libreadline-dev gawk tcl-dev libffi-dev git \
    graphviz xdot pkg-config python3 libboost-system-dev \
    libboost-python-dev libboost-filesystem-dev zlib1g-dev
```

Activate the bootstrap environment `. ./bootstraph.sh` then compile yosys.

```sh
git clone https://github.com/YosysHQ/yosys
cd yosys
git submodule update --init
make config-clang
make -j8
```

Install it to a known directory and add it to your `$PATH`:

```sh
make DESTDIR=$HOME/ice40-fpga-tools install
export $PATH=$PATH:$HOME/ice40-fpga-tools/usr/local/bin
```

#### fpga-icestorm

TODO: Document compiling from source.

#### nextpnr-ice40

TODO: Document compiling from source.

### Updating STM32Cube

Checkout the desired commits in each of these submodules:

```
third_party/stm32cube_f7/cmsis_core
third_party/stm32cube_f7/cmsis_device
third_party/stm32cube_f7/hal_driver
```

Then run from Gonk root:

```sh
python -m pw_stm32cube_build gen_file_list third_party/stm32cube_f7
```

### Gonk Pin Maps

#### Misc

| Net    | STM32 Pin | STM32 Function | Function |
|--------|-----------|----------------|----------|
| STATUS | PB13      | GPIO_Output    | STAT LED |

### Top 6 pin header (0.1inch pitch 2x3)

Visual header pin positions:

```
                             +-------------
+------+--------+-----+      |
|  2   | Ground |  6  |      |    USB-C
+------+--------+-----+      |    Port
|  1   |   3    | VCC |      |
+------+--------+-----+      +-------------
```

| Header Pin | Net         | STM32 Pin |
|------------|-------------|-----------|
|          1 | SPI_HDR_IO3 | PB0       |
|          2 | SPI_HDR_IO1 | PA2       |
|          3 | SPI_HDR_IO2 | PA3       |
|          4 | GND         |           |
|          5 | VCC_GONK    |           |
|          6 | SPI_HDR_IO0 | PA1       |

### SPI Flash Connection

| Net          | FPGA IO# | STM32 Pin | STM32 Function | Flash Pin  |
|--------------|----------|-----------|----------------|------------|
| ICE_SPI_SS   |       71 | PD2       | GPIO_Output    | S#         |
| ICE_SPI_MISO |       68 | PB4       | SPI1_MISO      | DQ1        |
| ICE_SPI_MOSI |       67 | PB5       | SPI1_MOSI      | DQ0        |
| ICE_SPI_SCK  |       70 | PB3       | SPI1_SCK       | C          |
| FLASH_HOLD   |       63 | PC11      | GPIO_Output    | HOLD#/DQ3  |
| FLASH_WP     |       64 | PC12      | GPIO_Output    | W#/VPP/DQ2 |

### FPGA Connection

| Net               | Function | FPGA IO# | STM32 Pin | STM32 Function | Notes               |
|-------------------|----------|----------|-----------|----------------|---------------------|
| FPGA_IO_SPARE_0_2 | rst_i    |      135 | PA0       | GPIO_Output    | Active high         |
| FPGA_IO_SPARE_0_0 | mode_i   |      137 | PB11      | GPIO_Output    | FPGA operation mode |
| DSPI_CS           | valid_o  |       75 | PB6       | GPIO_Output    | Data/Transfer Valid |
| FPGA_IO_SPARE_1_1 | miso_i   |      101 | PC2       | SPI1_MISO      |                     |
| FPGA_IO_SPARE_1_0 | mosi_i   |       99 | PC3       | SPI1_MOSI      |                     |
| I2C_O_SDA         | cs_n     |       79 | PB9       | SPI1_NSS       |                     |
| FPGA_IO_SPARE_0_1 | sclk_i   |      136 | PB10      | SPI1_SCK       |                     |
| FPGA_IO_SPARE_2_0 |          |       49 | PA7       |                |                     |
| FPGA_IO_SPARE_2_1 |          |       48 | PA6       |                |                     |
| FPGA_IO_SPARE_2_2 |          |       47 | PA5       |                |                     |
| FPGA_IO_SPARE_2_3 |          |       45 | PA4       |                |                     |