Update README formatting
Change-Id: I1ac6fdfee54f92b4b434c83ba1f19046de5a930f
Reviewed-on: https://pigweed-review.googlesource.com/c/gonk/+/238425
Presubmit-Verified: CQ Bot Account <pigweed-scoped@luci-project-accounts.iam.gserviceaccount.com>
Lint: Lint 🤖 <android-build-ayeaye@system.gserviceaccount.com>
Commit-Queue: Auto-Submit <auto-submit@pigweed-service-accounts.iam.gserviceaccount.com>
Pigweed-Auto-Submit: Anthony DiGirolamo <tonymd@google.com>
Reviewed-by: Akira Baruah <akirabaruah@google.com>
diff --git a/tools/README.md b/tools/README.md
index 312e13c..ce12e1f 100644
--- a/tools/README.md
+++ b/tools/README.md
@@ -1,6 +1,8 @@
# Gonk Python Tools Bundle
-Unzip and install the bundle.
+[TOC]
+
+## Unzip and install the bundle.
```sh
unzip gonk_bundle.zip
@@ -31,36 +33,11 @@
- Device (logs from Gonk) are set to: `--device-logfile gonk-device-log.txt`
- CSV output is set to: `--csv-logfile gonk-csv-log.txt`
-Optionally you can add ADC json output with `--json-logfile gonk-device-logs.json`
+**Note:** Log files are always appended to whenever running `gonk`. You can truncate the
+files on startup with `--truncate-logfiles`.
+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
-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
@@ -70,107 +47,73 @@
This will provision the FPGA and begin logging ADC measurements.
-1. The FPGA bitstream file is sent over serial first:
+1. The FPGA bitstream file is sent over serial first. This should only be one
+ once per power cycle. You can skip this step by omitting the
+ `--bitstream-file` option.
-```
-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/gonk/main.cc:153
-20240507 12:35:37 [gonk] INF SPI Flash JEDEC ID: 1f 84 1 -- applications/gonk/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/gonk/main.cc:134
-20240507 12:35:41 [gonk] INF ADC Idle -- applications/gonk/main.cc:114
-20240507 12:35:42 [gonk] INF ADC Idle -- applications/gonk/main.cc:114
-20240507 12:35:43 [gonk] INF ADC Idle -- applications/gonk/main.cc:114
-```
-
-Pressing Enter again will resume continuous reading.
-Ctrl-C will exit the gonk app.
-
-
-4. Plot the csv data from `gonk-csv-log.txt` with:
-
- ```sh
- gonk-plot -i gonk-csv-log.txt -o plot.svg
+ ```
+ 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
```
- Omit the svg output option to start an interactive matplotlib window.
+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:
+
+ ```
+ 20240507 12:35:40 [gonk] INF Stopping ADC Continuous Reads. -- applications/gonk/main.cc:134
+ 20240507 12:35:41 [gonk] INF ADC Idle -- applications/gonk/main.cc:114
+ 20240507 12:35:42 [gonk] INF ADC Idle -- applications/gonk/main.cc:114
+ 20240507 12:35:43 [gonk] INF ADC Idle -- applications/gonk/main.cc:114
+ ```
+
+ 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
+```
