shuttler: mention drtio destination config in JSON

Yeah, this is a forgotten feature.

src/hw/shuttler.md

@@ -1,7 +1,7 @@
 # Sinara 5716 DAC Shuttler
 
 The Sinara 5716 DAC Shuttler consists of the [Shuttler](https://github.com/sinara-hw/Shuttler),
-[Remote AFE-Board](https://github.com/sinara-hw/Shuttler), and
+[Remote AFE-Board](https://github.com/sinara-hw/AFE_DAC_External), and
 [EEM FMC Carrier](https://github.com/sinara-hw/EEM_FMC_Carrier) (EFC) Board.
 
 The EFC Board has an FPGA running Kasli Satellite. DRTIO communication is established through the EEM Cable.
@@ -13,12 +13,22 @@ and then store the value into the flash memory/SD Card.
 ```json
 {
     "type": "shuttler",
-    "ports": [<port num>]
+    "ports": [<port num>],
+    "drtio_destination": [<drtio_dest>]
 }
 ```
 
+See how the default DRTIO destination is [generated if unspecified](https://github.com/m-labs/artiq/blob/ff1a9badfcb595d432644aea5a0b30b7478c9966/artiq/frontend/artiq_ddb_template.py#L820-L836).
+
+
 ## Hardware Configurations and Connections
 
+### EFC to FMC CLK Configurations
+
+C217, C218, C213, C214 should be fitted to pass the EFC analog clock source to the Shutter FMC board. If they are incorrectly configured, the EFC board will panic at "DAC AD9117 retiming failure".
+
+![efc_to_fmc_clk_cfg](../img/efc_to_fmc_clk_config.png)
+
 ### EEM Cable Connection
 
 Only the EEM0 port on the EFC board is used. The EEM Cable provides power. You can ignore the barrel jack at
@@ -31,6 +41,7 @@ The EFC requires a **common** clock source with the connected device.
 For the EFC Board v1.0, please refer to this [issue](https://github.com/sinara-hw/EEM_FMC_Carrier/issues/44).
 
 For the EFC Board v1.1 (or later), there is a DIP switch to select the clock source.
+
 ![efc_clk_sel](../img/efc_clk_sel.png)
 
 | Clock Source | CLK_SEL0 | CLK_SEL1 |
@@ -44,12 +55,14 @@ For the EFC Board v1.1 (or later), there is a DIP switch to select the clock sou
 
 The EFC Board has configurable Digital IO Voltage Level/PSU called VADJ. You should configure VADJ to 1.8V by
 fitting W1/W2 jumper accordingly.
+
 ![efc_vadj_settings](../img/efc_vadj_settings.jpg)
 
 ### Remote AFE Board Connections
 
 The Remote AFE Board is not installed in the crate and should be shipped separately. When you test the EFC Board,
 please connect the Mini SAS Cables in this orientation.
+
 ![Mini-Sas Connections](../img/shuttler_afe_connections.jpg)
 
 There is no PSU for the Remote AFE Board at this moment. For testing purposes, you should connect the Remote AFE
@@ -60,12 +73,18 @@ pinouts carefully. Incorrect power connections can damage the Remote AFE Board.
 
 The EFC Board gateware and firmware are on the [Artiq](https://github.com/m-labs/artiq) repo.
 
-To build the gateware and firmware,
+To build the gateware and firmware on the release-8 branch (only supports AFE revision <= v1.2),
 
 ```shell
 python -m artiq.gateware.targets.efc --hw-rev [v1.0, v1.1]
 ```
 
+To build the gateware and firmware on later ARTIQ versions / the master branch,
+
+```shell
+python -m artiq.gateware.targets.efc --efc-hw-rev [v1.0, v1.1] --afe-hw-rev [v1.0, v1.1, v1.2, v1.3]
+```
+
 ## Routing Table Configuration if Shuttler is Connected to Kasli Satellite
 
 When Kasli Satellite is compiled with Shuttler, Shuttler is connected to the Satellite Repeater instance. Therefore,
@@ -136,3 +155,32 @@ PASSED
 
 ...
 ```
+
+## Troubleshooting
+
+### UART spam error
+Generally the error messages implies the data is malformed. For example, `received packet of an unknown type`.
+
+It is likely caused by Kasli(-SoC) having an improper calibration for DRTIO-over-EEM. Consider re-do the [flashing](#flashing) step.
+
+### ADC error
+Please check the AFE card revision and the [corresponding supported ARTIQ version](#building-efc-board-gateware-and-firmware).
+
+### No DRTIO link to Shuttler
+First, check [this](#uart-spam-error).
+
+If the symptom doesn't fit, please check the routing table. You should go by these few points
+- Identify the DRTIO destination of the shuttler by checking the channel number in `device_db.py`. The destination is the 2 most significant hexadecimal digits of the channel. For example,
+```
+device_db["shuttler0_led0"] = {
+    "type": "local",
+    "module": "artiq.coredevice.ttl",
+    "class": "TTLOut",
+    "arguments": {"channel": 0x050000}
+}
+```
+The destination is 0x5 in hexadecimal, which is 5 in decimal.
+
+- Find the route correct DRTIO route for the shuttler [(See this)](https://m-labs.hk/artiq/manual/using_drtio_subkernels.html#configuring-the-routing-table).
+
+```

src/hw/stabilizer_pounder.md

@@ -63,7 +63,7 @@ Once you have the binary, you can now flash it.
 2. With newer firmware with USB serial console:
    1. Connect the Stabilizer to power.
    2. Connect USB cable to the Stabilizer.
-   3. Ensure you have `pyserial` module either with `nix-shell -p python312Packages.pyserial` for NixOS users
+   3. Ensure you have `pyserial` module either with `nix-shell -p python3Packages.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.
@@ -151,17 +151,31 @@ SMA connectors should line up with the ones from Stabilizer; no pins should be v
 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
+```shell
+nix-shell -p python3Packages.pyserial
+python -m serial /dev/ttyACM0
+--- Miniterm on /dev/ttyACM0  9600,8,N,1 ---
+--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
+> set /dual_iir/pounder/out_channel/0/dds/frequency 20e6
+Set but not stored. May require store and reboot to activate.
+
+> set /dual_iir/pounder/out_channel/0/dds/amplitude 1
+Set but not stored. May require store and reboot to activate.
+
+> set /dual_iir/pounder/out_channel/0/attenuation 16
+Set but not stored. May require store and reboot to activate.
+
+> set /dual_iir/pounder/out_channel/1/dds/frequency 30e6
+Set but not stored. May require store and reboot to activate.
+
+> set /dual_iir/pounder/out_channel/1/dds/amplitude 1
+Set but not stored. May require store and reboot to activate.
+
+> set /dual_iir/pounder/out_channel/1/attenuation 16
+Set but not stored. May require store and reboot to activate.
 ```
 
-You can copy them all and input at once.
+`Set but not stored. May require store and reboot to activate.` means the setting is applied but not persistent after reboot.
 
 Observe a sine wave with frequency of 20MHz on channel 0 output, and 30MHz on channel 1 output.
 

src/hw/thermostat.md

@@ -3,6 +3,14 @@
 * [Wiki](https://github.com/sinara-hw/Thermostat/wiki)
 * [Firmware](https://git.m-labs.hk/M-Labs/thermostat)
 
+## Hardware Configuration
+
+For version v2.2.4 or above, you can install a 0R resistor to receive 12V Power from IDC output header(s).
+
+For version below v2.2.4, IDC output headers 12V Power are always connected.
+
+![](../img/thermostat_idc_hdrs_0R_resistors.png)
+
 ## Setup
 
 Attach Ethernet and Micro-USB cables and run:

src/hw/urukul.md

@@ -180,3 +180,25 @@ device_db["urukulX_cpld"] = {
     }
 }
 ```
+
+### 10MHz reference clock
+
+```pycon
+assert vco_min <= sysclk / 1e6 <= vco_max
+...
+artiq.master.worker_db.DeviceError: Failed to create device 'urukul0_ch0'
+```
+
+This can be avoided by adjusting `pll_n` and `clk_div` argument in the device_db.py file as in:
+
+```py
+{
+    "type": "urukul",
+    "dds": "ad9910",
+    "ports": [6, 7],
+    "clk_sel": 2,
+    "refclk": 10e6,
+    "clk_div": 1, # <--- change here
+    "pll_n": 100 # <--- and here
+}
+```