tools/README.md

# Gonk Python Tools Bundle

[TOC]

## 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 these log files are created:

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

**Note:** Log files are always erased on startup whenever running
`gonk`. You can append instead with `--no-truncate-logfiles`.

Logs are not normally written to the terminal but can be using `--log-to-stderr`.

Optionally you can add ADC json output with `--json-logfile gonk-device-logs.json`.
That will produce a json lines file with each line corresponding to one ADC

### Start Logging ADC Measurements

```sh
gonk --log-to-stderr
```

This will provision the FPGA if necessary and begin logging ADC measurements.

1. If necessary the FPGA bitstream file is sent over serial first. This normally
   occurs once per power cycle.

   ```
   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. ADC measurements begin logging.

   ```
   20240927 13:17:33 [gonk] INF host_time: 20240927 13:17:33.861429 size: 72 delta_microseconds: 283 vbus: 0.7992187500000001, 1.0109375, 5.1365234375, 1.0869140625, 0.9955078125000001, 3.3822265625, 1.8113281250000002 vshunt: 0.3496354166666667, 0.048240625, 0.28776875, 0.07383203125, 0.13364583333333332, 0.2599479166666667, 0.005157500000000001 power: 0.27943518066406253, 0.0487682568359375, 1.4781309289550784, 0.08024907302856445, 0.13304547119140625, 0.8792027486165367, 0.009341924804687502
   ...
   20240927 13:17:33 [gonk] INF host_time: 20240927 13:17:33.861758 size: 72 delta_microseconds: 287 vbus: 0.8146484375, 0.995703125, 5.1365234375, 1.0869140625, 0.9955078125000001, 3.3822265625, 1.7966796875000002 vshunt: 0.34727083333333336, 0.048484375, 0.24190000000000003, 0.07353125, 0.1345138888888889, 0.26787500000000003, 0.00515625 power: 0.282903641764323, 0.04827604370117188, 1.2425250195312503, 0.07992214965820313, 0.13390962727864586, 0.9060139404296876, 0.009264129638671877
   ```

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

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

   Followed shortly by a message from Gonk stopping continuous reading:

   ```
   20241003 16:39:04 [gonk] INF Stopping ADC Continuous Reads. -- applications/gonk/main.cc:134
   20241003 16:39:05 [gonk] INF ADC Idle; Press Enter to start/stop reading -- applications/gonk/main.cc:86
   20241003 16:39:06 [gonk] INF ADC Idle; Press Enter to start/stop reading -- applications/gonk/main.cc:86
   20241003 16:39:07 [gonk] INF ADC Idle; Press Enter to start/stop reading -- applications/gonk/main.cc:86
   ```

   Pressing `Enter` again will resume continuous reading.

   `Ctrl-C` will exit the gonk app.


## Plot the CSV data

You can create an SVG of the plot data stored in `gonk-csv-log.txt` with:

```sh
gonk-plot -i gonk-csv-log.txt -o plot.svg
```

Omit the svg output option to start an interactive matplotlib window:

```sh
gonk-plot -i gonk-csv-log.txt
```