booster: update instructions, add troubleshooting instructions

src/hw/booster.md

@@ -8,33 +8,45 @@
 
 ### Flashing
 
-#### Easier way
+Download the latest [booster firmware](https://github.com/quartiq/booster/releases/latest/download/booster-release.bin).
 
-Download and unpack the [booster firmware](../extra/booster/booster0.5.0.tar.xz), and then:
+Switch the booster into DFU mode by either inputting ``platform dfu`` in the serial console, or by turning it on while pressing the DFU button with a thin rod of some sort.
+
+Then you can use ``dfu-util``:
 
 ```shell
 nix-shell -p dfu-util
-dfu-util -a 0 -s 0x08000000:leave --download booster0.5.0.bin
+dfu-util -a 0 -s 0x08000000:leave --download booster-release.bin
 ```
 
-#### Build from source on Fedora 38
+#### Building from source (optional)
 
-Creating proper Nix shell for updated Rust is quite troublesome, so the faster way is actually to use any
+Please keep in mind that the firmware from the official Quartiq repository does not include support for Pounder in MQTT,
-classic Linux distribution:
+you may need to use a fork for that. But if the stabilizer is without a Pounder, it's also a valid option.
+
+There is no Nix Flake support to make things easier, so you need to set up rust and cargo manually.
+Start with cloning the stabilizer repository and opening a new shell with dfu-util (for flashing) and rustup
+(for building).
+
+```shell
+nix-shell -p dfu-util rustup
+```
+
+Set up the toolchain, this should be done only once:
 
 ```shell
-git clone https://github.com/quartiq/booster.git # download sources
-sudo dnf install clang dfu-util
-cd booster/
-curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh # install Rust, we need rustup
 rustup target add thumbv7em-none-eabihf
 cargo install cargo-binutils
 rustup component add llvm-tools-preview
+rustup update
+rustup default stable
+```
+
+Building:
+
+```shell
 cargo build --release
-cargo objcopy --release -- -O binary booster.bin
+cargo objcopy --release -- -O binary booster-release.bin
-# enter dfu mode by either serial terminal or
-# press `DFU Bootloader` button while rebooting
-dfu-util -a 0 -s 0x08000000:leave --download booster.bin
 ```
 
 #### For version before September 2023 on NixOS
@@ -54,14 +66,27 @@ cargo objcopy --release -- -O binary booster.bin
 dfu-util -a 0 -s 0x08000000:leave --download booster.bin
 ```
 
+### Clearing settings
+
+In case someone sets some setting wrongly, or updates the firmware and suddenly there's an incompatibility, you may find (firmware, not yourself) in a state of panic, where it will not allow you to change the settings back.
+
+1. Get into DFU mode (described above), probably with jumper method.
+2. Use dfu-util to clear the flash completely:
+
+   ```shell
+   dfu-util -a 0 -s 0x08000000:mass-erase:force:leave
+   ```
+
+3. Reflash the target firmware.
+
 ### Basic setup via USB
 
 1. `nix-shell -p cutecom mosquitto appimage-run`
-2. Create mosquitto config `mosquitto.conf` with your bound address:
+2. Create mosquitto config `mosquitto.conf`, or use the one from Stabilizer:
 
     ```text
-    bind_address 192.168.1.123
+    %allow_anonymous true
-    allow_anonymous true
+    listener 1883
     ```
 
 3. `mosquitto -c mosquitto.conf -d`
@@ -69,7 +94,24 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
 5. Connect to the Booster via `/dev/ttyACMX` port, baud 9600, switch from LF to CR on newer version
 6. Send `help` command to check if it works
 7. Enter commands (change details if necessary):
+    ```shell
+    set /broker "192.168.1.123"
+    set /ip "192.168.1.79/24"
+    store /broker
+    store /ip
+    # apply changes and wait until it fully rebooted
+    platform reboot
+    ```
 
+   Older version:
+    ```shell
+    write broker "192.168.1.123"
+    write ip "192.168.1.75"
+    # apply changes and wait until it fully rebooted
+    reset
+    ```
+
+   Oldest version:
     ```shell
     write broker-address 192.168.1.123
     # only if you need static IP address
@@ -80,17 +122,8 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
     reset
     ```
 
-   Newer version:
+8. Check if the Booster connects to your broker.
-
+9. If you don't have it yet, download [MQTT Explorer](https://github.com/thomasnordquist/MQTT-Explorer/releases)
-   ```shell
-    write broker "192.168.1.123"
-    write ip "192.168.1.75"
-    # apply changes and wait until it fully rebooted
-    reset
-    ```
-
-8. Check the Booster connects to your broker.
-9. Download AppImage from [MQTT Explorer](https://mqtt-explorer.com/)
 10. Run it with `appimage-run /path/to/MQTT-Explorer-XXX.AppImage`
 11. Connect to your MQTT broker
 12. Restart booster to receive settings
@@ -151,3 +184,25 @@ extrapolate them for all channels._
 13. Do steps 1-10 for every channel
 
 _Note: default setting values are usually the same across channels, so you can extrapolate them for all channels._
+
+## Troubleshooting
+
+### Fans running constantly
+
+If firmware is not running, the fans will be running at all times. There will also be no LED lights. It may be also the firmware doesn't have the chance to switch the fans off before a panic, so clearing settings may also help.
+
+### Fans running high, slowing and high again in a loop
+
+Possibly the firmware is panicking and rebooting. Try clearing the settings.
+
+### No USB console available
+
+There was a bug that causes [USB not to work on Windows](https://github.com/quartiq/booster/pull/166) in older firmware. Updating the firmware should be fine.
+
+### Booster will not connect to MQTT
+
+You may need to supply the IP address, if the device cannot get one from DHCP.
+
+### Overload light is on even after interlock reset
+
+Make sure you set the output interlock threshold high enough for your intended load, but also keep in mind that it cannot be not more than 47dBm. Similarly, reflected power threshold is at 30dBm, so if the input is high enough and output is not connected, it will also trip the lock.