Add instruction for Thermostat EEM

src/SUMMARY.md

@@ -20,6 +20,7 @@
   - [Sinara 8452 DSP Stabilizer / Sinara 4459 Pounder](./hw/stabilizer_pounder.md)
   - [Sinara 9805 RF Power Amplifier Booster](./hw/booster.md)
   - [Sinara 8451 Thermostat](./hw/thermostat.md)
+  - [Sinara 8453 Thermostat EEM](./hw/thermostat_eem.md)
   - [Sinara 2245 LVDS DIO](./hw/lvds_dio.md)
 - [Software/Support](./sw_sup/software_support.md)
   - [Starting with ARTIQ](./sw_sup/artiq_start.md)

src/hw/stabilizer_pounder.md

@@ -146,9 +146,32 @@ SMA connectors should line up with the ones from Stabilizer; no pins should be v
 
 ## Testing the Pounder
 
+### With serial only
+
+You need to have the Stabilizer powered on and connected through USB. Ethernet is not necessary.
+
+Input the following sequence of commands into the shell, assuming Stabilizer serial interface is visible at /dev/ttyACM0:
+```
+stty 115200 -F /dev/ttyACM0
+echo 'set /dual_iir/pounder/out_channel/0/dds/frequency 20e6' > /dev/ttyACM0
+echo 'set /dual_iir/pounder/out_channel/0/dds/amplitude 1' > /dev/ttyACM0
+echo 'set /dual_iir/pounder/out_channel/0/attenuation 16' > /dev/ttyACM0
+echo 'set /dual_iir/pounder/out_channel/1/dds/frequency 30e6' > /dev/ttyACM0
+echo 'set /dual_iir/pounder/out_channel/1/dds/amplitude 1' > /dev/ttyACM0
+echo 'set /dual_iir/pounder/out_channel/1/attenuation 16' > /dev/ttyACM0
+```
+
+You can copy them all and input at once.
+
+Observe a sine wave with frequency of 20MHz on channel 0 output, and 30MHz on channel 1 output.
+
+### With MQTT (slower)
+
+For this method, you need to set up MQTT and have the Stabilizer connected with Ethernet.
+
 1. Set up the MQTT as described above.
 2. Using Mosquitto and MQTT Explorer, set the pounder ``out_channel`` parameters:
-* Frequency: 10e6 (10MHz)
+* Frequency: 20e6 (20MHz)
 * Amplitude: 1.0
    ![Pounder MQTT settings](../img/pounder_mqtt.png)
 3. Repeat the procedure for the other channel.

src/hw/thermostat_eem.md

@@ -0,0 +1,181 @@
+# Sinara 8453 Thermostat EEM
+
+* [Wiki](https://github.com/sinara-hw/Thermostat_EEM/wiki)
+* [Firmware](https://github.com/quartiq/thermostat-eem/tree/main)
+
+EEM is used for power only, and it can be alternatively powered by 12V barrel jack or PoE.
+
+## JSON
+
+Not present in the JSON.
+
+### Building 
+There is no Nix Flake support to make things easier, so you need to set up rust and cargo manually.
+Start with cloning the thermostat-eem 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
+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 --bin thermostat-eem -- -O thermostat-eem.bin
+```
+
+## Flashing
+
+Once you have the binary, you can now flash it.
+
+1. Without firmware on the device or with older firmware (without USB serial console),
+   you need to use the jumper method:
+   1. Have the Thermostat EEM disconnected from power.
+   2. Use a jumper of some sort to short BOOT pins on the board.
+   3. Turn on the power.
+   4. You can remove the jumper after few seconds.
+2. With newer firmware with USB serial console:
+   1. Connect the Thermostat EEM to power.
+   2. Connect USB cable to the Thermostat EEM.
+   3. Ensure you have `pyserial` module either with `nix-shell -p python312Packages.pyserial` for NixOS users
+      or using `pip install pyserial` if you are using venv.
+   4. Run `python -m serial /dev/ttyACM0` to connect the serial port using `pyserial`.
+   5. Input `platform dfu` in the console.
+3. Once the device is now in DFU mode, flash the device with the following command (needs `nix-shell -p dfu-util`):
+
+   ```shell
+   dfu-util -a 0 -s 0x08000000:leave -R -D thermostat-eem.bin
+   ```
+
+4. Look for "File downloaded successfully".
+
+
+### 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.
+
+## Testing
+
+### Setting up MQTT
+
+MQTT is the only way to access the SENS and TEC pins telemetry for testing . 
+
+On PC side:
+
+1. Get IP address of your machine, e.g. with ``ip a``. Make note of it, that's the broker address.
+2. Get mosquitto, e.g. with ``nix-shell -p mosquitto``.
+3. Create a mosquitto config files by running ``echo -e "allow_anonymous true\nlistener 1883" > mosquitto.conf``
+3. Run mosquitto with the config ``mosquitto -c mosquitto.conf``
+4. If you don't have it yet, download [MQTT Explorer](https://github.com/thomasnordquist/MQTT-Explorer/releases).
+5. Call ``nix-shell -p appimage-run``, then ``appimage-run MQTT-Explorer-0.4.0-beta6.AppImage``.
+6. Connect to the MQTT broker under your own IP address.
+
+Configure Thermostat EEM:
+
+1. Ensure that the [firmware](#Building) has been flashed onto the Thermostat EEM
+2. Connect the Thermostat EEM to power.
+3. Connect USB cable to the Thermostat EEM.
+4. Run ``cutecom`` or your favorite terminal emulator, connect to ``/dev/ttyACM0``.
+5. Change the broker setting with: ``set /net/broker "<ip of your machine>"``.
+6. Store the setting with ``store /net/broker``.
+7. (Optional) Set the IP address of the Thermostat EEM by following steps 4 and 5, but with ``/net/ip`` setting instead.
+8. Reboot with ``platform reboot``.
+
+Now, disconnect the USB and connect the Ethernet cable to the Thermostat EEM, as both won't fit at the same time.
+Thermostat EEM should connect to moquitto automatically, and you should see the MQTT settings pop up in the MQTT Explorer.
+If the IP address is not set, Thermostat EEM will try to use DHCP to get an address.
+
+### SENS pins testing
+
+1. Power off the Thermostat EEM
+2. Connect the breakout board to Thermostat EEM
+3. Connect two 10k Ohm resistor to SENS0 & SENS1
+  ![resistor for sens pin](../img/thermostat_eem_resistor.jpg)
+4. Power the Thermostat EEM and access the `telemetry/statistics` on MQTT Explorer
+5. Check the mean temperature is around 25C for SENS0 & SENS1
+  ```json
+  {
+    ...
+    "statistics": [
+      // SENS0 & SENS1
+      [
+        {
+          "mean": 25.180674,
+          "ptp": 0.00029182434,
+          "std": 0.000053144646
+        },
+        {
+          "mean": 25.042572,
+          "ptp": 0.00029182434,
+          "std": 0.00005036032
+        },
+        null,
+        null
+      ],
+      // SENS2 & SENS3
+      [
+        {
+          "mean": -273.15,
+          "ptp": 0,
+          "std": 0
+        },
+        {
+          "mean": -273.15,
+          "ptp": 0,
+          "std": 0
+        },
+        null,
+        null
+      ],
+      ...
+    ],
+    ...
+  }   
+  ```
+6. Repeat 3-5 for other SENS pins
+
+### TEC pins testing
+
+1. Power off the Thermostat EEM
+2. Connect the breakout board to Thermostat EEM
+3. Power the Thermostat EEM and set `output/0/state` parameter to `On` using MQTT explorer
+  ![mqtt setup](../img/thermostat_eem_mqtt.png)
+
+4. Check that TEC0 pins have voltages as described in `telemetry/monitor/output_voltage`
+  ```json
+  {
+    "monitor": {
+      ...
+      "output_voltage": [
+        -1.1107178, // TEC0
+        -1.638794,  // TEC1
+        -1.762146,  // TEC2
+        -1.1976318  // TEC3
+      ],
+      ...
+    },
+  ...
+  }
+  ```
+5. Repeat 3-4 for other TEC pins