Documentation, Manual, CLI

[jordens]

Just found https://github.com/airwoodix/sinara-stabilizer-notes from @airwoodix.

• IMO filter_design.py can be polished up a little and upstreamed here as a first-class user facing CLI for dual-iir. It's also a nice show case for rough edges or missing pieces in the API.
• The documentation should be integrated into the different components (i.e. Usage/dual-iir -> filter_design and and Preparation -> README or other docs structure rustdoc?)

[jordens]

User manual and infrastructure added as of #401.
Remaining:

• Hardware setup (powering, PoE etc)
• consider moving to mdbook (like rtic, rust book etc) Adding mdbook-based user manual #431
• More detailed and robust MQTT setup: let's try docker plus our config file, also on wsl2 Adding docker instructions #430
• Some nicer python library for IIR parameter calculation

[jordens]

@svrotter You took notes on a couple bugs in the current manual (divergences between docs and code) and missing/tricky bits in the setup instructions, especially on windows. Could you post them here?

[svrotter]

We found some issues while trying to set up Stabilizer for local use on my Windows 10 machine with the Getting Started Guide. I try to give a brief overview of what we encountered:

1. windows cmd and powershell don't seem to understand the BROKER=X part of the commands in 'Update Stabilizer' section but my MINGW64 bash apparently does
2. windows cmd and powershell are fine with cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin` in section 'Uploading firmware' but MINGW64 chokes when using the grave accent at the end of the command
3. the docker run ... command in 'Set up the Broker' section also behaves differently on different tools. While powershell acts likes expected, cmd does not allow pwd (chdir could do the trick) and MINGW64 starts the path with /c/... which corrupts the command

We wanted to set everything up for local use, as I don't have access to "10.34.16.10" as a broker. I try to give a quick rundown of what we needed to do in order to make it work. Forgive me, if my terminology may be a bit inaccurate here but networking is really not my strength.

1. Activate vEthernet (WSL) network adapter sharing: Go to vEthernet (WSL) network adapter Properties -> Sharing -> activate "Allow other network users to connect through this computer's Internet connection" -> choose "Ethernet" as Home networking connection. There is no need to have a specific IP address here
2. Set a fixed IP address for the Ethernet adapter: Go to Ethernet network adapter Properties -> Networking -> Internet protocol, Version 4 (TCP/IPv4) -> set a specific IP address eg 192.168.137.1 and subnet mask 255.255.2550
3. exchange the broker address in command BROKER="10.34.16.10" cargo build --release in 'Update Stabilizer' section with your own IP, eg BROKER="192.168.137.1" cargo build --release
4. cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin in section 'Uploading firmware' rebuilds the binary with 10.34.16.10 as broker. Specify the broker again in this command eg BROKER=192.168.137.1 cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
5. Allow Dokcer Desktop Backend to communicate through Windows Defender Firewall
6. set the Host field in MQTT Explorer to localhost

There were also some issues when trying to install miniconf. @jordens took over this part, so I just write down his bash history more or less. All commands were executed in MING64 bash in the Stabilizer repo, while he created a virtual python environment vpy first:
$ python -m venv .
$ python -m venv --system-site-packages vpy
$ git clone https://github.com/quartiq/miniconf
$ ./vpy/Scripts/pip.exe install -e miniconf/py/miniconf-mqtt/

[jordens]

Closed by #451 #452 #401 #449