Documentation updates

.gitattributes

@@ -0,0 +1,3 @@
+* text=auto
+
+mosquitto.conf text eol=lf

.gitignore

@@ -1,2 +1,3 @@
 /target
-/dsp/target
+/dsp/target
+vpy/

book/README.md

@@ -9,9 +9,9 @@ cargo install mdbook-linkcheck
 ```
 
 To build the user manual locally, build docs for the firmware, copy them into the book source
-directory, and then sere the book:
+directory, and then serve the book:
 ```
-cargo doc --no-deps -p miniconf -p stabilizer -p dsp -p ad9959
+cargo doc --no-deps -p miniconf -p stabilizer -p idsp -p ad9959
 mv target/thumbv7em-none-eabihf/doc book/src/firmware
 cd book
 mdbook serve

book/src/getting-started.md

@@ -21,15 +21,21 @@ desired application.
 ```bash
 git clone https://github.com/quartiq/stabilizer
 ```
-1. Get [rustup](https://rustup.rs/)
+2. Get [rustup](https://rustup.rs/)
     * The minimum supported Rust version (MSRV) is 1.52.0
-1. Install target support
+
+3. Install target support
 ```bash
 rustup target add thumbv7em-none-eabihf
 ```
-1. Build Firmware with an optionally-specified MQTT broker IP.
+4. Build Firmware with an optionally-specified MQTT broker IP.
 ```bash
+# Bash
 BROKER="10.34.16.10" cargo build --release
+
+# Powershell
+# Note: This sets the broker for all future builds as well.
+$env:BROKER='10.34.16.10'; cargo build --release
 ```
 
 ## Uploading Firmware
@@ -51,12 +57,16 @@ cargo install cargo-binutils
 rustup component add llvm-tools-preview
 ```
 
-1. Generate the binary file
+2. Generate the binary file
 ```bash
-cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin`
+# Bash
+BROKER="10.34.16.10" cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
+
+# Powershell
+$env:BROKER='10.34.16.10'; cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
 ```
 
-1. Copy `dual-iir.bin` into the ST-Link drive on your computer.
+3. Copy `dual-iir.bin` into the ST-Link drive on your computer.
 
 
 ### Alternative: Using USB
@@ -82,11 +92,15 @@ For an interactive flash experience with live logging, utilize `probe-run` as fo
 ```bash
 cargo install probe-run
 ```
-1. Build and run firmware on the device
+2. Build and run firmware on the device
 ```bash
-cargo run --release --bin dual-iir
+# Bash
+BROKER="10.34.16.10" cargo run --release --bin dual-iir
+
+# Powershell
+$Env:BROKER='10.34.16.10'; cargo run --release --bin dual-iir
 ```
-1. When using debug (non `--release`) mode, decrease the sampling frequency significantly.
+3. When using debug (non `--release`) mode, decrease the sampling frequency significantly.
   The added error checking code and missing optimizations may lead to the code
   missing deadlines and panicing.
 
@@ -105,12 +119,13 @@ Stabilizer utilizes a static IP address for broker configuration. Ensure the IP
 We recommend running Mosquitto through [Docker](https://docker.com) to easily run Mosquitto on
 Windows, Linux, and OSX. After docker has been installed, run the following command from
 the `stabilizer` repository:
-```
+```bash
+# Bash
 docker run -p 1883:1883 --name mosquitto -v `pwd`/mosquitto.conf:/mosquitto/config/mosquitto.conf -v /mosquitto/data -v /mosquitto/log eclipse-mosquitto:2
-```
 
-> _Note_: The above command assumes a bash shell. If using powershell, replace `` `pwd` `` with
-> `${pwd}`
+# Powershell
+docker run -p 1883:1883 --name mosquitto -v ${pwd}/mosquitto.conf:/mosquitto/config/mosquitto.conf -v /mosquitto/data -v /mosquitto/log eclipse-mosquitto:2
+```
 
 This command will create a container named `mosquitto` that can be stopped and started easily via
 docker.

book/src/usage.md

@@ -13,14 +13,15 @@ Settings are specific to an application. If two identical settings exist for two
 applications, each application maintains its own independent value.
 
 ## Installation
-Install the Miniconf configuration utilities:
+Install the Miniconf configuration utilities using a virtual environment:
 ```
-python -m pip install git+https://github.com/quartiq/miniconf#subdirectory=miniconf-py
+python -m venv --system-site-packages vpy
+./vpy/Scripts/pip install -r scripts/requirements.txt
 ```
 
 To use `miniconf`, execute it as follows:
 ```
-python -m miniconf --help
+./vpy/Scripts/python -m miniconf --help
 ```
 
 Miniconf also exposes a programmatic Python API, so it's possible to write automation scripting of
@@ -40,7 +41,7 @@ used:
 * `value` = `{"ip": [192, 168, 0, 1], "port": 4000}`
 
 ```
-python -m miniconf --broker 10.34.16.10 dt/sinara/dual-iir/00-11-22-33-44-55 stream_target='{"ip": [10, 34, 16, 123], "port": 4000}'
+./vpy/Scripts/python -m miniconf --broker 10.34.16.10 dt/sinara/dual-iir/00-11-22-33-44-55 stream_target='{"ip": [10, 34, 16, 123], "port": 4000}'
 
 Where `10.34.16.10` is the MQTT broker address that matches the one configured in the source code and `10.34.16.123` and `4000` are the desire stream target IP and port.
 ```

hitl/run.sh

@@ -11,13 +11,10 @@
 set -eux
 
 # Set up python for testing
-python3 -m venv --system-site-packages py-venv
-. py-venv/bin/activate
+python3 -m venv --system-site-packages vpy
 
-# Install Miniconf utilities for configuring stabilizer.
-python3 -m pip install -e py/
-python3 -m pip install git+https://github.com/quartiq/miniconf#subdirectory=py/miniconf-mqtt
-python3 -m pip install gmqtt
+# Install Miniconf and other utilities for configuring stabilizer.
+./vpy/Scripts/pip install -r scripts/requirements.txt
 
 cargo flash --chip STM32H743ZITx --elf target/thumbv7em-none-eabihf/release/dual-iir
 
@@ -31,12 +28,12 @@ sleep 30
 ping -c 5 -w 20 stabilizer-hitl
 
 # Test the MQTT interface.
-python3 -m miniconf dt/sinara/dual-iir/04-91-62-d9-7e-5f afe/0='"G2"'
-python3 -m miniconf dt/sinara/dual-iir/04-91-62-d9-7e-5f afe/0='"G1"' iir_ch/0/0=\
+./vpy/Scripts/python -m miniconf dt/sinara/dual-iir/04-91-62-d9-7e-5f afe/0='"G2"'
+./vpy/Scripts/python -m miniconf dt/sinara/dual-iir/04-91-62-d9-7e-5f afe/0='"G1"' iir_ch/0/0=\
 '{"y_min": -32767, "y_max": 32767, "y_offset": 0, "ba": [1.0, 0, 0, 0, 0]}'
 
 # Test the ADC/DACs connected via loopback.
-python3 hitl/loopback.py dt/sinara/dual-iir/04-91-62-d9-7e-5f
+./vpy/Scripts/python hitl/loopback.py dt/sinara/dual-iir/04-91-62-d9-7e-5f
 
 # Test the livestream capabilities
-python3 hitl/streaming.py dt/sinara/dual-iir/04-91-62-d9-7e-5f
+./vpy/Scripts/python hitl/streaming.py dt/sinara/dual-iir/04-91-62-d9-7e-5f

py/setup.py

@@ -1,6 +1,7 @@
-from setuptools import setup
+from setuptools import setup, find_packages
 
 setup(name='stabilizer',
+      packages=find_packages(),
       version='0.1',
       description='Stabilizer Utilities',
       author='QUARTIQ GmbH',

scripts/requirements.txt

@@ -0,0 +1,3 @@
+py/
+git+https://github.com/quartiq/miniconf#subdirectory=py/miniconf-mqtt
+gmqtt