tools/README.md

# Gonk Python Tools Bundle

Unzip and install the bundle.

```sh
unzip gonk_bundle.zip
cd gonk_bundle
./setup.sh
```

## Flash a Gonk for the first time:

```sh
. ./python-venv/bin/activate
gonk-flash
```

or without activating the Python virtualenv:

```sh
./python-venv/bin/gonk-flash
```

## Log ADC measurements

### Logging

By default two log files are created:

- Host log messages are set to: `--logfile gonk-logs.txt`
- Device (logs from Gonk) are set to: `--device-logfile gonk-device-logs.txt`

You can add ADC json output with the `--json-logfile gonk-device-logs.json`
option.

That will produce a json lines file with each line corresponding to one ADC
measurement event. For example:

```
{
  "message": "host_time: 20240507 12:47:41.308278 size: 40 delta_microseconds: 204 vbus: 3,2,3,2,2 vshunt: 0,0,0,69,0",
  "levelno": 20,
  "levelname": "\u001b[35m\u001b[1mINF\u001b[0m",
  "args": [
    "20240507 12:47:41.308278",
    "40",
    "204",
    "3,2,3,2,2",
    "0,0,0,69,0"
  ],
  "time": "1715111261.308351",
  "time_string": "2024-05-07T12:47:41",
  "py_file": "gonk_log_stream.py:213",
  "py_logger": "gonk",
  "fields": {
    "host_time": "20240507 12:47:41.308278",
    "packet_size": "40",
    "delta_micros": "204",
    "vbus_values": "[0, 0, 0, 69, 0]",
    "vshunt_values": "[3, 2, 3, 2, 2]"
  }
}
```

### Start Logging ADC Measurements

```sh
./python-venv/bin/gonk --log-to-stderr --bitstream-file DEFAULT
```

This will provision the FPGA and begin logging ADC measurements.

1. The FPGA bitstream file is sent over serial first:

```
20240507 12:35:32 [gonk] INF Waiting for bitstream -- lib/fpga_control/fpga_control.cc:53
20240507 12:35:33 [gonk] INF Waiting for bitstream -- lib/fpga_control/fpga_control.cc:53
20240507 12:35:34 [host] INF Sending bitstream...
20240507 12:35:34 [gonk] INF Waiting for bitstream -- lib/fpga_control/fpga_control.cc:53
20240507 12:35:34 [gonk] INF Discard byte: 1 -- lib/fpga_control/fpga_control.cc:65
20240507 12:35:34 [gonk] INF Discard byte: 2 -- lib/fpga_control/fpga_control.cc:65
20240507 12:35:34 [gonk] INF Discard byte: 3 -- lib/fpga_control/fpga_control.cc:65
20240507 12:35:34 [gonk] INF Discard byte: 4 -- lib/fpga_control/fpga_control.cc:65
20240507 12:35:34 [gonk] INF Start Sequence found. -- lib/fpga_control/fpga_control.cc:71
20240507 12:35:35 [gonk] INF Got bytes: 4096 -- lib/fpga_control/fpga_control.cc:84
...
20240507 12:35:36 [gonk] INF Got bytes: 4096 -- lib/fpga_control/fpga_control.cc:84
20240507 12:35:36 [host] INF Done sending bitstream. Wrote 135100
20240507 12:35:37 [gonk] INF Got bytes: 4024 -- lib/fpga_control/fpga_control.cc:84
20240507 12:35:37 [gonk] INF All 135100 bytes recieved. -- lib/fpga_control/fpga_control.cc:92
20240507 12:35:37 [gonk] INF File ready: 135096 -- lib/fpga_control/fpga_control.cc:102
20240507 12:35:37 [gonk] INF First 12 bytes -- lib/fpga_control/fpga_control.cc:104
...
20240507 12:35:37 [gonk] INF Last 12 bytes -- lib/fpga_control/fpga_control.cc:109
...
20240507 12:35:37 [gonk] INF Sending bitstream file to the FPGA. -- lib/fpga_control/fpga_control.cc:118
20240507 12:35:37 [gonk] INF FPGA Config Success. -- lib/fpga_control/fpga_control.cc:162
```

2. SPI Flash and ADC communication is tested.

```
20240507 12:35:37 [gonk] INF Checking SPI Flash -- applications/fpga_config/main.cc:153
20240507 12:35:37 [gonk] INF SPI Flash JEDEC ID: 1f 84 1 -- applications/fpga_config/main.cc:158
20240507 12:35:37 [gonk] INF Init ADCs -- lib/adc/adc.cc:543
20240507 12:35:37 [gonk] INF ADC #01: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #01: VSHUNT = 00 00 00 = 3 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #01: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #02: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #02: VSHUNT = 00 00 20 = 2 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #02: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #03: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #03: VSHUNT = 00 00 30 = 3 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #03: VBUS   = 00 04 70 = 71 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #04: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #04: VSHUNT = 00 00 20 = 2 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #04: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #05: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #05: VSHUNT = 00 00 20 = 2 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #05: VBUS   = 00 04 60 = 70 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #06: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #06: VSHUNT = 00 04 f0 = 79 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #06: VBUS   = 00 04 70 = 71 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #07: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #07: VSHUNT = 00 00 30 = 3 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #07: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #08: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #08: VSHUNT = 00 00 20 = 2 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #08: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #09: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #09: VSHUNT = 00 00 30 = 3 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #09: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #10: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #10: VSHUNT = 00 00 30 = 3 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #10: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF ADC #11: ADC Config = b000 -- lib/adc/adc.cc:578
20240507 12:35:37 [gonk] INF ADC #11: VSHUNT = 00 00 20 = 2 -- lib/adc/adc.cc:502
20240507 12:35:37 [gonk] INF ADC #11: VBUS   = 00 00 00 = 0 -- lib/adc/adc.cc:517
20240507 12:35:37 [gonk] INF Selected ADC count: 5 -- lib/adc/adc.cc:224
```

3. ADC measurements begin logging.

```
20240507 12:35:37 [gonk] INF host_time: 20240507 12:35:37.585414 size: 70 delta_microseconds: 351574012 vbus: 3,-74,-74,-73,2 vshunt: 0,0,0,0,0
20240507 12:35:37 [gonk] INF host_time: 20240507 12:35:37.586015 size: 40 delta_microseconds: 226 vbus: 3,2,3,2,2 vshunt: 0,0,0,0,0
...
20240507 12:35:40 [gonk] INF host_time: 20240507 12:35:40.156319 size: 40 delta_microseconds: 194 vbus: 3,2,3,79,79 vshunt: 0,0,0,0,0
```

Measurements can be stopped by pressing Enter. This text should appear in the terminal:

```
 [Send: '\n']
```

Followed shortly by a message from Gonk stopping continuous reading:

```
20240507 12:35:40 [gonk] INF Stopping ADC Continuous Reads. -- applications/fpga_config/main.cc:134
20240507 12:35:41 [gonk] INF ADC Idle -- applications/fpga_config/main.cc:114
20240507 12:35:42 [gonk] INF ADC Idle -- applications/fpga_config/main.cc:114
20240507 12:35:43 [gonk] INF ADC Idle -- applications/fpga_config/main.cc:114
```

Pressing Enter again will resume continuous reading.
Ctrl-C will exit the gonk app.