Overheating issues for DRTIO

Signed-off-by: Egor Savkin <es@m-labs.hk>

flake.lock

@@ -2,16 +2,16 @@
   "nodes": {
     "nixpkgs": {
       "locked": {
-        "lastModified": 1675237434,
-        "narHash": "sha256-YoFR0vyEa1HXufLNIFgOGhIFMRnY6aZ0IepZF5cYemo=",
+        "lastModified": 1710695816,
+        "narHash": "sha256-3Eh7fhEID17pv9ZxrPwCLfqXnYP006RKzSs0JptsN84=",
         "owner": "NixOS",
         "repo": "nixpkgs",
-        "rev": "285b3ff0660640575186a4086e1f8dc0df2874b5",
+        "rev": "614b4613980a522ba49f0d194531beddbb7220d3",
         "type": "github"
       },
       "original": {
         "owner": "NixOS",
-        "ref": "nixos-22.11",
+        "ref": "nixos-23.11",
         "repo": "nixpkgs",
         "type": "github"
       }

flake.nix

@@ -1,7 +1,7 @@
 {
     description = "Sinara assembly and test instructions";
 
-    inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-22.11;
+    inputs.nixpkgs.url = github:NixOS/nixpkgs/nixos-23.11;
 
     outputs = { self, nixpkgs }:
 

src/SUMMARY.md

@@ -2,6 +2,8 @@
 
 - [Build and test firmware](./build_test_firmware.md)
 - [Hardware](./hw/hardware.md)
+  - [Sinara Kasli](./hw/kasli.md)
+  - [Sinara Kasli-SOC](./hw/kasli_soc.md)
   - [Sinara 4624 AWG Phaser (Upconverter/Baseband)](./hw/phaser.md)
   - [Sinara 4456 synthesizer Mirny / Sinara 4457 Almazny Mezzanine card](./hw/mirny_almazny.md)
   - [SUServo (Sampler + Urukul)](./hw/suservo.md)
@@ -16,6 +18,14 @@
   - [Sinara 8452 DSP Stabilizer](./hw/stabilizer.md)
   - [Sinara 9805 RF Power Amplifier Booster](./hw/booster.md)
   - [Sinara 8451 Thermostat](./hw/thermostat.md)
+  - [Sinara 2245 LVDS DIO](./hw/lvds_dio.md)
 - [Software/Support](./sw_sup/software_support.md)
+  - [Starting with ARTIQ](./sw_sup/artiq_start.md)
+  - [Building legacy firmware](./sw_sup/artiq_legacy.md)
   - [Networking](./sw_sup/networking.md)
+  - [DRTIO](./sw_sup/drtio.md)
   - [UART Logs](./sw_sup/uart_logs.md)
+  - [Flashing the Firmware](./sw_sup/flashing_firmware.md)
+  - [Moninj](./sw_sup/moninj.md)
+  - [Clocking](sw_sup/clocking.md)
+  - [device_db.py](sw_sup/device_db.md)

src/build_test_firmware.md

@@ -9,7 +9,21 @@
   least plastic ESD bags if you need the cards to be put at the desk or any other surface.
 * 💁 Be gentle to the EEM ports and any other connectors. Support them when plugging, hold when unplugging
 * 🙆 If you need to take the cards out, take them out one-by-one from the end, unplug EEM and cables if you feel high tension
-* 🙆 Use dedicated power supplies for each crate
+* 🙆 Use dedicated power supplies for each crate, preferably given or equivalent to given by us
+* 🙅 Avoid unnecessary inserts and pullouts, especially of MMCX cables
+
+Failure to comply with this voids the warranty.
+
+## Shipping hints and warnings
+
+* 🙆 Leave the cards in the crate
+* 🙆 Ensure screws are tight
+* 🙆 Ensure cards are in card guides
+* ⚠️ Remove any cables from front panels
+* ⚠️ Remove SFP adapters and insert caps/stubs
+* 💁 Also advised to put caps on SMA connectors
+* ✅ Wrap each crate in the bubble wrap individually until you don't feel the edges of the crate (usually 10 layers of standard buble wrap)
+* 🈁 Fill in the space around the crate in the box with foamy stuff
 
 ## Kasli standalone
 
@@ -17,7 +31,7 @@
 
 1. Build firmware (see commands below)
 2. Flash firmware and settings
-3. Test hardware
+3. Test hardware with the PSU, which is going to be shipped
 4. Create a flash-drive with `device_db.py` file for customers (FAT32)
 
 ### CLI commands - build and flash
@@ -43,7 +57,7 @@ artiq_flash --srcbuild -d artiq_kasli/<variant>/
 3. Insert SD card to the Kasli-SoC and boot
 4. Change IP from the default one: `artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75`
 5. Reboot and check it works on new IP address
-6. Test hardware
+6. Test hardware with the PSU, which is going to be shipped
 7. Create a flash-drive with `device_db.py` file for customers (FAT32)
 
 ### CLI commands - build and flash
@@ -73,8 +87,9 @@ you can use this book's pages, or if there is no instruction for testing your ha
 
 ### Known issues
 
-* [artiq-zynq#197](https://git.m-labs.hk/M-Labs/artiq-zynq/issues/197) - some cards (Sampler, Mirny, Zotino and others)  
-  do not work properly with some EEM ports. You might need to connect the card to the other ports until it gets working.
+* ~~[artiq-zynq#197](https://git.m-labs.hk/M-Labs/artiq-zynq/issues/197) - some cards (Sampler, Mirny, Zotino and others)  
+  do not work properly with some EEM ports. You might need to connect the card to the other ports until it gets working.~~
+  resolved (hopefully)
 
 ## Master-satellite setups
 

src/extra/CONFIG.TXT

@@ -1 +1,2 @@
 ip=192.168.1.75
+rtio_clock=int_125

src/extra/prep_pkg.py

@@ -0,0 +1,35 @@
+import shutil
+import os
+import argparse
+import zipfile
+
+
+def main():
+    parser = argparse.ArgumentParser()
+    parser.add_argument("-v", default=None, help="Variant name")
+    parser.add_argument("-d", default="./artiq_kasli", help="path to built")
+    parser.add_argument("-o", default=None, help="output zip (default: kasli-<variant>.zip")
+    args = parser.parse_args()
+    if not args.v:
+        raise ValueError("need to specify variant!!")
+    basepath = os.path.abspath(args.d)
+    tempdir = os.path.join(basepath, "kasli-{}".format(args.v))
+    try:
+        os.mkdir(tempdir)
+    except FileExistsError:
+        pass
+    shutil.copyfile(os.path.join(basepath, args.v, "gateware/top.bit"), os.path.join(tempdir, "top.bit"))
+    shutil.copyfile(os.path.join(basepath, args.v, "software/bootloader/bootloader.bin"), os.path.join(tempdir, "bootloader.bin"))
+    try:
+        shutil.copyfile(os.path.join(basepath, args.v, "software/runtime/runtime.elf"), os.path.join(tempdir, "runtime.elf"))
+        shutil.copyfile(os.path.join(basepath, args.v, "software/runtime/runtime.fbi"), os.path.join(tempdir, "runtime.fbi"))
+    except FileNotFoundError:
+        shutil.copyfile(os.path.join(basepath, args.v, "software/satman/satman.elf"), os.path.join(tempdir, "satman.elf"))
+        shutil.copyfile(os.path.join(basepath, args.v, "software/satman/satman.fbi"), os.path.join(tempdir, "satman.fbi"))
+    output = args.o if args.o else "kasli-{}".format(args.v)
+
+    shutil.make_archive(output, "zip", tempdir)
+    shutil.rmtree(tempdir)
+    
+if __name__ == "__main__":
+    main()

src/hw/bnc_sma_ttl.md

@@ -13,8 +13,8 @@
   "hw_rev": "vX.Y", // optional
   "ports": [<port num>],
   "edge_counter": <bool>,
-  "bank_direction_low": "input",
-  "bank_direction_high": "output"
+  "bank_direction_low": "input", // or "output"
+  "bank_direction_high": "output" // or "input"
 }
 ```
 

src/hw/booster.md

@@ -8,14 +8,46 @@
 
 ### Flashing
 
+#### Easier way
+
+Download and unpack the [booster firmware](../extra/booster/booster0.5.0.tar.xz), and then:
 ```shell
-git clone git@github.com:quartiq/booster.git
-cd booster
-nix-shell -p rustup cargo rustc dfu-util
+nix-shell -p dfu-util
+dfu-util -a 0 -s 0x08000000:leave --download booster0.5.0.bin
+```
+
+#### Build from source on Fedora 38
+
+Creating proper Nix shell for updated Rust is quite troublesome, so the faster way is actually to use any
+classic Linux distribution:
+
+```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
 cargo build --release
-cargo objcopy -- -O binary booster.bin
+cargo objcopy --release -- -O binary booster.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
+
+```shell
+git clone git@github.com:quartiq/booster.git
+cd booster
+git checkout a1f83b63180511ecd68f88a04621624941d17a41 # or earlier
+nix-shell -p rustup cargo rustc dfu-util
+rustup target add thumbv7em-none-eabihf
+cargo install cargo-binutils
+rustup component add llvm-tools-preview
+cargo build --release
+cargo objcopy --release -- -O binary booster.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
@@ -31,7 +63,7 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
     ```
 3. `mosquitto -c mosquitto.conf -d`
 4. Run `cutecom`
-5. Connect to the Booster via `/dev/ttyACMX` port, baud 9600
+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
@@ -43,6 +75,13 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
     # apply changes and wait until it fully rebooted
     reset
     ```
+   Newer version:
+   ```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`
@@ -51,19 +90,23 @@ dfu-util -a 0 -s 0x08000000:leave --download booster.bin
 
 ## Calibration
 
-1. Assemble Kasli with one Urukul, build and flash firmware for it with [booster.json](../extra/booster.json)
-2. Run [dds_for_booster.py](../extra/dds_for_booster.py) experiment once
+1. Assemble Kasli with one Urukul, build and flash firmware for it with [booster.json](../extra/booster/booster.json)
+2. Run [dds_for_booster.py](../extra/booster/dds_for_booster.py) experiment once
 3. Attach parallel 50 Ohm load to the oscilloscope, as shown on the picture: ![](../img/50ohm_parallel_load.jpg),
 4. Configure oscilloscope for 1M Ohm impedance
 5. Attach attenuator to the Urukul's RF2
 6. `cd py/`
-7. You may also need to download or install python's `gmqtt` and `miniconf`
+7. You may also need to download or install python's `gmqtt` and `miniconf`:
+   ```shell
+   python -m venv env
+   source env/bin/activate.fish
+   pip install git+https://github.com/quartiq/miniconf.git@84cc9046bf504cc2d0d33b84d2f3133f2faf2248#subdirectory=py/miniconf-mqtt
+   ```
 8. Enable channels: `python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N tune=0.1`
-9. Use [online calculator](https://www.analog.com/en/design-center/interactive-design-tools/dbconvert.html) for Volts to dBm conversion
-10. Using [booster_template](../extra/booster_template.ods) fill in `y0`, `y1`, `m`, `c`, values using instructions below
-11. Update settings with the adjusted values
-12. Save settings with `python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N save`
-13. Reboot and check settings are applied
+9. Using [booster_template](../extra/booster/booster_template.ods) fill in `y0`, `y1`, `m`, `c`, values using instructions below
+10. Update settings with the adjusted values
+11. Save settings with `python -m booster --broker 192.168.1.123 --prefix dt/sinara/booster/xx-xx-xx-xx-xx-xx --channel N save`
+12. Reboot and check settings are applied
 
 ### Input power
 

src/hw/clocker.md

@@ -4,20 +4,11 @@
 
 ## JSON
 
-Put the `ext_ref_frequency` field into the JSON description if the Kasli is going to use an external frequency:
+Not present in the JSON.
 
-```json
-{
-  "hw_rev": "<hw rev>",
-  "base": "<base>",
-  ...
-  "ext_ref_frequency": <freq in Hz>,
-  ...
-  "peripherals": [...]
-}
-```
-
-On peripherals you should choose `"clk_sel": 2` on connected devices.
+Peripherals typically should choose `"clk_sel": 2` for MMCX connection and `"clk_sel": 1` for external SMA connection.
+Refer to the [official docs](https://m-labs.hk/artiq/manual/core_drivers_reference.html) by searching for `clk_sel`.
+You may also need to add `"refclk": <number>` field to the target card.
 
 ## Setup external clocker
 
@@ -41,12 +32,12 @@ Here is example setup for SynthNV RF signal generator:
 1. Switch `CLK SEL` pin to `EXT`/`INT` according to customer needs
 2. Connect MMCx cables according to the customer needs and boards specifications (see image below for reference): 
    if the `INT` source is chosen, connect MMCx cable to `INT CLK`, otherwise connect external clocker to SMA `EXT CLK` 
-3. Connect the Clocker to the Kasli via 30-pin ports
+3. Connect the Clocker to the Kasli via 30-pin ports, or via external power supply
    ![](../img/clocker_ref.jpg)
 4. Connect the Clocker's SMA output to the Kasli's `CLK`/`CLK IN` SMA pin
-5. After assembling the crates and flashing the firmware, start Kasli and write config as follows:
+5. After assembling the crates and flashing the firmware, start Kasli and set config if needed:
    `artiq_coremgmt config write -s rtio_clock ext0_bypass`. Please refer to the [official manual](https://m-labs.hk/artiq/manual/installing.html#miscellaneous-configuration-of-the-core-device)
-   for the details and available options
+   for the details and available options. In most cases you may skip this step.
 6. Reboot either via `artiq_coremgmt reboot` or via power supply if the board's firmware doesn't have such command
 
 ## Testing

src/hw/kasli.md

@@ -0,0 +1,9 @@
+# Kasli
+
+## Mounting fan onto heatsink
+![](../img/kasli_fan.jpg)
+1. ⚠️ Verify the fan has the **correct polarity (powering on with wrong polarity will burn the MOSFET in series💥)**
+2. Place the fan on a heatsink
+3. Tap 3 threads on the heatsink using M2.5 pointy tapping screws (e.g. front panel screws)
+4. Replace the tapping screws with M2.5x14mm screws
+5. Verify the fan is secure

src/hw/kasli_soc.md

@@ -0,0 +1,16 @@
+# Kasli_SOC
+
+## HW Setup
+
+Check the BOOT mode switches - they both should be at SD if the Kasli-SoC going to be shipped to customer.
+POR jumper needs only for JTAG mode.
+
+![](../img/kasli_soc.jpg)
+
+## Mounting fan onto heatsink
+![](../img/kasli_soc_fan.jpg)
+1. ⚠️ Verify the fan has the **correct polarity (powering on with wrong polarity will burn the MOSFET in series💥)**
+2. Place the fan on a heatsink
+3. Tap 3 threads on the heatsink using M2.5 pointy tapping screws (e.g. front panel screws)
+4. Replace the tapping screws with M2.5x14mm screws
+5. Verify the fan is secure

src/hw/lvds_dio.md

@@ -0,0 +1,79 @@
+# Sinara 2245 LVDS DIO card
+
+* [Wiki](https://github.com/sinara-hw/DIO_LVDS_RJ45/wiki)
+* [Datasheet](https://m-labs.hk/docs/sinara-datasheets/2245.pdf)
+
+## JSON
+
+Be aware of the reversed EEM order on the card:
+
+```json
+[
+  {
+    "type": "dio",
+    "board": "DIO_LVDS",
+    "ports": [1],
+    "bank_direction_low": "input",
+    "bank_direction_high": "input",
+    "edge_counter": false // or true
+  }, 
+  {
+    "type": "dio",
+    "board": "DIO_LVDS",
+    "ports": [0],
+    "bank_direction_low": "output",
+    "bank_direction_high": "output"
+  }
+]
+```
+
+## Setup
+
+Switch DIPs in required position per each channel individually. Each RJ45 have 4 channels.
+
+![](../img/lvds_ttl_switches.jpg)
+
+## Testing
+
+```bash
+*** Testing TTL inputs.
+TTL device to use as stimulus (default: ttl0): ttl0
+
+Connect ttl0 to ttl4. Press ENTER when done.
+
+PASSED  # <--------
+Connect ttl0 to ttl5. Press ENTER when done.
+
+FAILED
+Connect ttl0 to ttl6. Press ENTER when done.
+
+FAILED
+Connect ttl0 to ttl7. Press ENTER when done.
+
+FAILED
+...
+
+*** Testing TTL inputs.
+TTL device to use as stimulus (default: ttl0): ttl1
+
+Connect ttl1 to ttl4. Press ENTER when done.
+
+FAILED
+Connect ttl1 to ttl5. Press ENTER when done.
+
+PASSED  # <--------
+Connect ttl1 to ttl6. Press ENTER when done.
+
+FAILED
+Connect ttl1 to ttl7. Press ENTER when done.
+
+FAILED
+...
+```
+1. Connect a RJ45 output port to a input port
+2. Run `artiq_sinara_tester`  
+3. One TTL will pass while other will fail
+4. Run `artiq_sinara_tester` again and increment the stimulus (e.g. `ttl0->ttl1->ttl2->ttl3`) until all channels on the input port passed at least once
+5. Plug into to another input port and repeat 2-4 until all input ports are tested
+
+It is incompatible with other TTL cards, so you will need to use same or other LVDS card for proper testing.

src/hw/mirny_almazny.md

@@ -9,7 +9,9 @@
 {
   "type": "mirny",
   "almazny": true, // for mirny with almazny only 
-  "ports": [<port num>]
+  "ports": [<port num>],
+  "clk_sel": 2, // optional
+  "refclk": 125e6 // optional
 }
 ```
 
@@ -37,8 +39,8 @@ mirny0_ch3 info: {'f_outA': 1300000000.0, 'f_outB': 10400000000, 'output_divider
 After running `artiq_sinara_test`:
 
 1. Install gqrx `nix-shell -p gqrx`
-2. Connect bladeRF via USB cable only
-3. Run gqrx and choose `BladeRF #<number>...`
+2. Connect HackRF One via USB cable only
+3. Run gqrx and choose `HackRF HackRF One...`
 4. Default settings
 5. When gqrx loaded, start DSP processing with frequency at mirnyN_chM freq
 6. Connect the probe through attenuator to the Mirny's port

src/hw/phaser.md

@@ -25,24 +25,21 @@ phaser0 10+0 10+1 10+2 10+3 10+4 MHz
 ### Upconverter
 
 1. Install gqrx `nix-shell -p gqrx`
-2. Connect bladeRF via USB cable only
-3. Run gqrx and choose `BladeRF #<number>...`
-4. Input rate 30000000, other settings are default
-5. When gqrx loaded, start DSP processing with frequency near 2.875 GHz + frequencies from `artiq_sinara_test`
+2. Connect HackRF One via USB cable only
+3. Run gqrx and choose `HackRF HackRF One...`
+4. Default settings
+5. Lower the gain in `Input options`
+6. When gqrx loaded, start DSP processing with frequency near 2.875 GHz +- DUC frequencies from `artiq_sinara_test`
    in `Receiver Options`
-6. Connect the probe through attenuator to the Phaser's ports
-7. You should see 5 tones on `artiq_sinara_test`'s frequencies, like on the picture below
-
-![](../img/phaser_upconverter_gqrx.png)
+7. Connect the probe through attenuator to the Phaser's RF ports
+8. You should see 5 tones on `artiq_sinara_test`'s frequencies, like on the pictures below for RF0 and RF1 respectively:
+   ![](../img/phaser_upconverter_gqrx_rf0.png)
+   ![](../img/phaser_upconverter_gqrx_rf1.png)
 
 
 ### Baseband
 
-1. Install gqrx `nix-shell -p gqrx`
-2. Connect bladeRF via USB cable only
-3. Run gqrx and choose `Nuand bladeRF SN <number>...`
-4. Input rate 15000000, other settings are default
-5. When gqrx loaded, start DSP processing with frequency near 2.875 GHz + frequencies from `artiq_sinara_test`
-   in `Receiver Options`
-6. Connect the probe through attenuator to the Phaser's ports RF0 or RF1 (not the ADC)
-7. You should see 5 tones on `artiq_sinara_test`'s frequencies
+1. Connect the probe through attenuator to the Phaser's ports RF0 or RF1 (not the ADC)
+2. Find FTT (Fourier Transform) function in the oscilloscope
+3. Start processing with frequency near DUC frequencies from `artiq_sinara_test`
+4. You should see 5 tones on `artiq_sinara_test`'s frequencies

src/hw/sampler.md

@@ -32,4 +32,5 @@ PASSED
 
 1. Apply 1.5V (connect the AA-battery) to the `samplerX`'s requested channel
 2. Press `Enter`, the `artiq_sinara_test` should output `PASSED`
-3. Repeat steps 1-2 for every available channel.
+3. Repeat steps 1-2 for every available channel.
+4. Disassemble AA-battery tool as it risks getting corrosion

src/hw/stabilizer.md

@@ -4,9 +4,76 @@
 * [QUARTIQ Manual](https://quartiq.de/stabilizer/)
 * [Firmware](https://github.com/quartiq/stabilizer)
 
+EEM is used for power only, and it can be alternatively powered by 12V barrel jack or PoE.
+
 ## JSON
 
-No JSON modifications required.
+Not present in the JSON.
+
+## Building
+
+Pick your poison - firmware version: older with Pounder support or newer with USB serial console - the first works with a hardcoded MQTT broker and (static or dynamic) IP address, the latter is configured like the booster - through a serial console.
+
+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).
+
+```
+nix-shell -p dfu-util rustup
+```
+
+Set up the toolchain, this should be done only once:
+
+```
+rustup target add thumbv7em-none-eabihf
+cargo install cargo-binutils
+rustup component add llvm-tools-preview
+rustup update
+rustup default stable
+```
+
+Building the older version:
+
+```
+BROKER="MQTT BROKER IP" cargo build --release
+BROKER="MQTT BROKER IP" cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
+```
+
+Building the newer version:
+
+```
+cargo build --release
+cargo objcopy --release --bin dual-iir -- -O binary dual-iir.bin
+```
+
+The newer version must be configured with USB console later (try ``help`` command first).
+
+## Flashing
+
+Once you have the binary (either built, or received from someone), you can now flash it.
+
+Without firmware on the device or with older firmware, you need to use the jumper method:
+
+1. Have the Stabilizer 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.
+
+With newer firmware with USB serial console:
+
+1. Connect the Stabilizer to power.
+2. Connect USB cable to the Stabilizer.
+3. Connect with a serial console emulator, usually at ``/dev/ttyACM0``.
+4. Input ``platform dfu`` in the console.
+
+And for both:
+
+5. The device is now in DFU mode.
+6. Flash the device with the following command:
+
+```
+dfu-util -a 0 -s 0x08000000:leave -R -D dual-iir.bin
+```
+
+7. Look for "File downloaded successfully".
 
 ## Testing
 

src/hw/suservo.md

@@ -16,9 +16,21 @@ With enabled SUServo mode, you only need to add `suservo` to JSON file, with its
 
 ## Setup
 
-On bottoms of each Urukul, switch first pins 1 and 2 to `ON`, as on the picture:
+To enable, on bottoms of each Urukul, switch first switches 1 and 2 to `ON`, as on the picture:
 ![](../img/urukul_pins_suservo.jpeg)
 
+### Easier access to the switches (for big racks)
+
+When the crate is assembled, it may be difficult to pull out the cards to access the switches.
+Hence for big racks it may be easier to remove the upper perforated panel. For this:
+1. Unscrew from both sides:
+   ![rack_urukul_switch_access.jpg](../img/rack_urukul_switch_access.jpg)
+2. Remove empty front panels
+3. Gently push out the perforated panel, applying the force from rack's back and front
+4. With tweezers and following the [basic operating hints](../build_test_firmware.md#operating-hints-and-warnings) 
+   switch the switches in desired direction
+5. Install the perforated and front panels back, screw the screws
+
 ## Testing
 
 After running `artiq_sinara_test`:

src/hw/thermostat.md

@@ -23,6 +23,28 @@ dfu-util -a 0 -s 0x08000000:leave -D thermostat.bin
 Then check that fans are working properly.
 You may also check fan controls via `fan` commands (see the firmware documentation).
 
+## Test PID
+
+1. For Zotino: connect 10-pins IDC 2.54mm FC cable from internal Thermostat connector to the Zotino TEC
+2. General TEC: connect external connector to the TEC
+3. Connect Ethernet and PSU
+4. Run:
+   ```shell
+   git clone gitea@git.m-labs.hk:esavkin/thermostat.git
+   cd thermostat
+   git checkout zotino-tec
+   nix develop
+   python pytec/tec_qt.py
+   ```
+5. In `Output Config`, set limits: 
+   * `Max Cooling Current` - 400 mA
+   * `Max Heating Current` - 400 mA
+   * `Max Voltage Difference` - 1 V
+6. `PID Config` -> `PID Auto Tune` set desired target temperature, which should be slightly above your room temperature (+10C)
+7. Set `Thermistor Config` -> `B` and other values, according to the datasheet of the TEC module, for example for Zotino `B` is `3455 K`
+8. Run `PID Config` -> `PID Auto Tune` -> `Run` and check graphs that the measured temperature goes to the target temperature, 
+   and eventually stabilizes at +- 0.01 of the target
+
 ## Common problems
 
 ### Thermostat doesn't connect or doesn't enter DFU mode

src/hw/urukul.md

@@ -12,6 +12,7 @@
     "dds": "<variant>", // ad9910/ad9912
     "ports": [<port num>, <port num>], // second port is optional
     "clk_sel": <clock num>,
+    "synchronization": true/false, // for AD9910 only
     "refclk": <freq>, // for external clock signal
     "pll_en": <0 or 1, default 1> // PLL bypass, to allow higher external clocker frequencies (1e9 for example)
 }
@@ -19,7 +20,32 @@
 
 ## Setup
 
-Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs. Connect to the clocker source.
+Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs. Connect to the clock source - either Clocker, 
+Kasli or external via SMA.
+
+### Synchronization
+
+Phase synchronization enables phase control from Kasli/Kasli-SoC with an absolute phase reference, i.e. you can use the phase control API in the coredevice driver.
+Without synchronization the phase between Urukuls will not drift, but it can change across reboots, and the phase control API cannot be used.
+Synchronization requires Kasli and Urukul to be clocked from the same oscillator with <<1ns noise, otherwise the synchronization may fail, and that's
+why this feature is disabled by default.
+There is no intrinsic impact on Urukul output phase noise and the synchronization process is quick and reliable when done correctly.
+
+### One-EEM mode
+
+Users may choose to use only one EEM port, if they want more cards to be in their crate. However following features
+will become unavailable:
+ * SU-Servo
+ * Low-latency RF switch control
+ * Synchronization
+
+RF switches are still available but the commands need to go over the SPI bus so it's higher-latency and lower-resolution.
+
+### Urukul 4412
+
+Urukul 4412 has higher frequency resolution (47 bit against 32 at Urukul 4410), however lacks such features:
+ * SU-Servo
+ * Synchronization
 
 ## Testing
 
@@ -57,19 +83,21 @@ Press ENTER when done.
 
 ## Common problems
 
-### Urukul AD9912 product id mismatch
+### Urukul AD9912 product id mismatch or missing LEDs
 
 ```pycon
 ValueError: Urukul AD9912 product id mismatch
 ```
 
 Some Urukuls may fail with this error during testing, usually meaning that the Urukul has not been flashed with the 
-firmware, especially if the ID is `65535` (you will need to edit the code to check this).
+firmware, especially if the ID is `65535` (you will need to edit the code to check this). 
+
+Another common symptom of no firmware is that no LEDs are lit up, besides Power Good - whereas if the firmware has been flashed, the RF channels will be lit red.
 
 You can flash the firmware yourself with a JTAG adapter:
 
 1. Download the latest binary release from [quartiq/urukul](https://github.com/quartiq/urukul) and extract the `urukul.jed` file.
-2. Connect the Urukul with the JTAG adapter to the PC and connect its EEM0 to any available Kasli/Kasli-SoC (do not hot-plug), then turn on the Kasli/Kasli-SoC.
+2. Connect the Urukul with the JTAG adapter to the PC and connect its EEM0 to any available Kasli/Kasli-SoC (**do not hot-plug**), then power on the Kasli/Kasli-SoC.
 3. Run `nix-shell -p xc3sprog`.
 4. Run `xc3sprog -c jtaghs2 urukul.jed -m /opt/Xilinx/Vivado/<available version>/data/xicom/cable_data/digilent/lnx64/xbr/`.
 5. If the last command outputs Verify: Success, then your Urukul is ready. It can also output the message 
@@ -121,4 +149,25 @@ matches real clocker source.
 ValueError: Urukul AD9910 AUX_DAC mismatch
 ```
 
-Ensure it is the AD9910 and not the AD9912. Also check SUServo pins are set up respective to the JSON description.
+Ensure it is the AD9910 and not the AD9912. Also check SUServo pins are set up respective to the JSON description.
+
+### Jagged signal with 1GHz external clock on AD9910
+
+By default, on AD9910 external clock signal is divided by 4, while it should be not divided at all with PLL disabled.
+Change the ``clk_div`` parameter to the CPLD in the device_db file:
+
+```python
+device_db["urukulX_cpld"] = {
+    "type": "local",
+    "module": "artiq.coredevice.urukul",
+    "class": "CPLD",
+    "arguments": {
+        "spi_device": "spi_urukul0",
+        "sync_device": None,
+        "io_update_device": "ttl_urukul0_io_update",
+        "refclk": 1000000000.0,
+        "clk_sel": 1,
+        "clk_div" : 1 # <--- add this line
+    }
+}
+```

src/hw/zotino_fastino.md

@@ -20,8 +20,7 @@
 }
 ```
 
-Fastino uses two physical EEM channels, but in the JSON file there should be only one channel specified, 
-and it should be the one connected to Fastino's EEM0.
+Fastino uses one physical EEM channel, despite having two EEM ports.
 
 ## Setup
 
@@ -55,4 +54,25 @@ Press ENTER when done.
 ### High-freq audible noise and output values all near -0.1 on Zotino v1.4.2
 
 This may happen when power-cycle is too short. Power down the crate, wait at least 30 seconds, and power up again.
-[Issue](https://github.com/sinara-hw/Zotino/issues/37).
+[Issue](https://github.com/sinara-hw/Zotino/issues/37).
+
+### Zero/meaningless voltage output on Fastino
+
+Some Fastino may not output any meaningful voltage during testing, usually that means it has no gateware flashed.
+
+Another common symptom of no gateware is that no LEDs are lit up. Whereas if the gateware has been flashed, the PG and FD LEDs will be lit green.
+
+You can flash the gateware with a Kasli/Kasli-SoC, be it in the crate or standalone (no specific gateware needed for Kasli/SoC):
+
+1. Download the latest `fastino.bin` release from [quartiq/fastino](https://github.com/quartiq/fastino/releases).
+2. Run `git clone https://github.com/quartiq/kasli-i2c.git` and place `fastino.bin` in the kasli-i2c directory.
+3. Connect the Fastino's EEM0 to any available Kasli/Kasli-SoC EEM port ([**do not hot-plug**](../build_test_firmware.md#operating-hints-and-warnings)). 
+   You may skip this step if Fastino is connected within a crate.
+4. Power on the standalone Kasli/Kasli-SoC and connect it to the PC via data micro-USB.
+5. Run `nix-shell -p python311Packages.pyftdi`.
+6. Run `cd kasli-i2c; python flash_fastino.py 0 EEM<number> write fastino.bin` where `<number>` is the EEM port number on the Kasli/Kasli-SoC side.
+7. If PG and FD LEDs are lit green, the Fastino is ready.
+
+### Fastino output is 10V
+
+Fastinos by default after power up output 10V on all channels if not driven by the test otherwise. Make sure the EEM ports are specified correctly in the JSON and the EEM cable is connected to EEM0 on the Fastino.

src/sw_sup/artiq_legacy.md

@@ -0,0 +1,64 @@
+# Building ARTIQ-6 and earlier
+
+Pre-flake ARTIQ (that is 6 and earlier) requires slightly different steps for building.
+
+## Initial setup
+
+The following steps need to be done only once.
+
+First we will need to specify older nixpkg version - 21.05. Open ``~/.nix-channels`` with your favorite text editor.
+
+If there are any ``nixpkgs`` present already, comment them out with ``#``.
+
+Then add the following line:
+
+```
+https://nixos.org/channels/nixos-21.05 nixpkgs
+```
+
+Save and exit.
+
+Now, we need special ``nix-scripts`` to configure building environment, and a local copy of the artiq repository, in legacy release.
+
+```shell
+mkdir artiq-legacy
+cd artiq-legacy
+git clone https://git.m-labs.hk/M-Labs/nix-scripts
+git clone https://github.com/m-labs/artiq/
+cd artiq
+git checkout release-6  # or release-5...
+cd ..
+```
+
+## Setting up the environment and building firmware
+
+Within ``fish`` shell (others may not work correctly), set up the ARTIQ build environment:
+
+```shell
+nix-shell -I artiqSrc=<full path to artiq repo in legacy branch> nix-scripts/artiq-fast/shell-dev.nix
+```
+
+Then build the required firmware as usual:
+
+```shell
+python -m artiq.gateware.targets.kasli_generic <variant>.json
+```
+
+If you are building legacy ARTIQ for local use and you want to flash it, use:
+```shell
+artiq_flash -V <variant> -d artiq_kasli --srcbuild
+```
+
+There's a slight discrepancy from usual command - ``-V <variant>`` option is not present in ARTIQ-7+, but it is necessary here.
+
+If you want to send the binaries to a customer, there's no need packing up the whole build directory - only ``top.bit``, ``bootloader.bin`` and ``runtime.elf/fbi`` or ``satman.elf/fbi`` are necessary. You can use the ``prep_pkg.py`` script from extras to package them up neatly into a zip file for distributions:
+
+```shell
+python prep_pkg.py -v <variant> -d artiq_kasli/
+```
+
+Then the customer can use ``artiq_flash`` easily, after extracting the contents:
+
+```shell
+artiq_flash -V <variant> -d .
+```

src/sw_sup/artiq_start.md

@@ -0,0 +1,38 @@
+# Starting with ARTIQ
+
+This page describes how to start with ARTIQ system for novice users.
+
+## Connecting wires
+
+In most cases the system is shipped with power bricks (PSU), DC splitters and SFPs enough to power and control the whole system.
+Connect them in following order:
+1. Insert Ethernet SFP into the SFP0 of the master or standalone Kasli/Kasli-SoC (Carrier)
+2. Connect these SFPs to the router or PC via Ethernet cable (in some cases, optical cable)
+3. Insert optic/direct attach SFPs into the master and satellite Carriers, respective to the numeration, [more info in DRTIO page](drtio.md)
+4. Power on PSU or EEM power module, by inserting C14 cable, attach DC splitters if available
+5. Some cards may have "External power" setting (check the quotation), in this case, insert DC connector into the port
+6. Insert remaining cables into the Carriers (not applicable in case of EEM Power Module).
+
+## Set the network
+
+By default standalone/master Carriers arrive with 192.168.1.75/24 set as their static address. Carrier will try to acquire this address
+from your router, and in case of failure, they will be just unavailable from the network. Check the following articles for troubleshooting network issues:
+* [Networking](networking.md)
+* [Official docs](https://m-labs.hk/artiq/manual/installing.html#setting-up-the-core-device-ip-networking)
+
+## Run first experiment via artiq_run
+
+Before diving in to the repository experiments management and scheduling, it is essential to try run your first experiment
+via most basic way - `artiq_run`. For this you need to enter your ARTIQ environment (console) and run:
+```shell
+artiq_run --device-db path/to/device_db.py path/to/experiment.py
+```
+
+In case your directory contains relevant `device_db` file, you may omit the `--device-db path/to/device_db.py` part.
+To check this, you may run `ls .` and check if it is in the list.
+
+On pre-installed NUCs, the ARTIQ commands are available everywhere, and you just need to run them.
+If you have Nix package manager or NixOS, you will just need to enter the shell with `nix develop github:m-labs/artiq\?ref=release-7`.
+If you have installed ARTIQ with Conda, you will need to activate the environment with `conda activate <name of the environment with ARTIQ>`.
+
+You may check for experiments in the [official docs](https://m-labs.hk/artiq/manual/getting_started_core.html).

src/sw_sup/clocking.md

@@ -0,0 +1,84 @@
+# Clocking
+
+This page describes ways to set up clocking. Official documentation references:
+
+* [Carrier configuration](https://m-labs.hk/artiq/manual/installing.html#miscellaneous-configuration-of-the-core-device)
+* Devices' [available options](https://m-labs.hk/artiq/manual/core_drivers_reference.html), [Urukul example](https://m-labs.hk/artiq/manual/core_drivers_reference.html#artiq.coredevice.urukul.CPLD)
+
+In general, any RF card and Carriers require some clock source. Most of them have both internal clock signal generator
+and external MMCX and/or SMA connectors to accept the signal. By default the internal clock is used for Carriers,
+and external MMCX is used for RF cards. However, internal clock may be not good enough for the end-user application,
+so the end-user may want to change the clock source at any time.
+
+## Kasli/Kasli-SoC
+
+For setting clocking on the Carriers you will just need to set `rtio_clock` in the core device config. Be aware, that
+setting any external clocking will require appropriate external clock signal to be supplied into `CLK IN` SMA connector
+on the front panel to boot. Therefore, firmware will be halted, the `ERR` LED will be red and **no Ethernet connection
+will be established**. Since the clock signal is distributed by DRTIO, there is generally no need in setting it up on
+satellites.
+
+If you have connection with the Carrier, you can use coremgmt command:
+
+```shell
+artiq_coremgmt config write -s rtio_clock <OPTION>
+```
+
+For available options refer to the official documentation (at the top of the page).
+
+### Setting clocking for Kasli without connection
+
+For RISC-V/legacy Kasli you will just need to connect your PC to the Kasli via _data_ micro-USB cable and run the
+following:
+
+```shell
+# you may also change IP setting here, the default is 192.168.1.75
+artiq_mkfs kasli.config -s ip xx.xx.xx.xx -s rtio_clock <OPTION> 
+# but don't forget to update `core_addr` variable in the device_db.py file if changed
+artiq_flash storage -f kasli.config
+```
+
+Be aware that all other settings will be **erased**, so you may need to restore them in the `artiq_mkfs` command.
+
+### Setting clocking for Kasli-SoC without connection
+
+For this you will need to eject micro-SD card from the Kasli-SoC, either
+by [removing the top panel](../img/rack_urukul_switch_access.jpg) or by gently pulling the Kasli-SoC from the crate,
+possibly with other cards. In any case, be cautious and follow
+the [warnings](../build_test_firmware.md#operating-hints-and-warnings). Once accessed the micro-SD card, simply
+add `rtio_clock=<OPTION>` on a new line to the existing `CONFIG.TXT` file and save it, or if it is absent, just download
+default-ish [CONFIG.TXT](../extra/CONFIG.TXT) to the SD card near (same level) `boot.bin` file.
+
+## RF Devices (Except Clocker)
+
+If you want to set the clock source specifically for RF devices, you will just need to update the JSON file
+and [regenerate device_db.py file](device_db.md).
+
+For example for Urukul, you will just need to check the manual for available variants and apply them in the JSON file,
+so Urukul entry may look like this:
+
+```json
+{
+  "type": "urukul", 
+  "dds": "ad9910", 
+  "ports": [1, 2], 
+  "refclk": 10e6, 
+  "clk_sel": 1
+}
+```
+
+So basically, `clk_sel` and `refclk` fields need to be set:
+
+* `clk_sel` selects the source clock, where 0 - internal 100MHz XO; 1 - front-panel SMA; 2 internal MMCX
+* `refclk` - reference clock frequency in Hz
+
+These settings may need to be checked with official manual and may differ from device to device.
+
+## Clocker card
+
+Main page: [clocker.md](../hw/clocker.md)
+
+Clocker card allows to distribute clock signal up to 1 GHz without additional software setup. Therefore, there is no way
+to set it to generate signal, which would be different from input. The only setup allowed is to set to accept signal
+from `EXT`/`INT` ports, front-panel SMA or card's MMCX ports respectively, by switching the `CLK SEL` switch on the
+card ![](../img/clocker_ref.jpg).

src/sw_sup/device_db.md

@@ -0,0 +1,21 @@
+# device_db.py File
+
+`device_db.py` file contains the database of the devices and their respective interfaces within the firmware/gateware.
+It is generated from JSON description file and tied with the configuration and the gateware.
+
+## Generating the device_db.py File
+
+In some cases you may need to regenerate `device_db.py`, like switching clock source or changing the configuration.
+Also it is must-do in most cases once firmware/gateware is being updated (for example, when you add, move or remove EEM
+cards).
+Luckily, it is fairly easy to do. For standalone systems:
+
+```shell
+artiq_ddb_template -o device_db.py <standalone variant>.json
+```
+
+For DRTIO systems:
+
+```shell
+artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <...> -s N <satelliteN>.json <master>.json
+```

src/sw_sup/drtio.md

@@ -0,0 +1,53 @@
+# DRTIO
+
+This page intends to help users solve problems with their DRTIO systems.
+
+## Description (from user experience)
+
+[Distributed Real Time Input/Output](https://m-labs.hk/artiq/manual/drtio.html) - allows almost seamlessly connecting several satellites to one master crate,
+so that all the crates can be controlled as one whole crate. The connection between the crates is done either by passive copper
+direct attach cables (suitable for one-crate setups) or optical fibers SFP+ adapters (suitable for multiple crates that 
+can be distributed up to [several kilometers](https://github.com/m-labs/artiq/issues/2022)). The DRTIO protocol is not
+compatible with Ethernet, and moreover, satellites do not have any network access and can be controlled only by master.
+However, both star (2 levels) and tree topologies are supported as well, 
+with default one being the star (one master and up to 3-4 directly connected satellites), and if any chaining is needed, the
+routing table setup is needed.
+To switch between satellite/master/standalone variants you just need to flash appropriate firmware, and set the respective `base`
+field in the JSON description.
+
+The master will attempt to connect the satellite whenever it sees that there are SFPs plugged in. For this purpose,
+it will _ping_ the satellite until it establishes the connection. This connection process can be observed from the logs:
+```rust
+// successful connection
+[ 5385.011286s] INFO(runtime::rtio_mgt::drtio): [LINK#1] link RX became up, pinging
+[ 5390.219274s] INFO(runtime::rtio_mgt::drtio): [LINK#1] remote replied after 27 packets
+[ 5390.257152s] INFO(runtime::rtio_mgt::drtio): [LINK#1] link initialization completed
+[ 5390.264854s] INFO(runtime::rtio_mgt::drtio): [DEST#2] destination is up
+[ 5390.271567s] INFO(runtime::rtio_mgt::drtio): [DEST#2] buffer space is 128
+
+// not successful connection:
+[    95.269811s]  INFO(runtime::rtio_mgt::drtio): [LINK#1] link RX became up, pinging
+[   115.076772s] ERROR(runtime::rtio_mgt::drtio): [LINK#1] ping failed
+```
+
+During the connection, the clock signal is being distributed, effectively making the clocks across crates to be synchronized.
+
+
+## Common problems
+
+### Master and satellite do not connect with each other
+
+* Shady cables and SFP adapters are often the cause, use the adapters from reputable sources, or better, use the one we ship. 
+  You may also contact our helpdesk to get help in choosing the right adapters if needed.
+* The adapter is not pushed until the end. You shouldn't be able to pull out the adapters without pulling the petals/handles.
+* The fiber is not properly connected - you shouldn't be able to pull it out without squeezing the handle. Also the optics
+  may be dirty or damaged.
+* Wrong setups - master to master, standalone to standalone. Messing up with SFP ports generally makes it unusable,
+  but the connection should be established in most cases.
+* The fiber adapters are not symmetrical - if one end has 1270/1330 label, another one should be 1330/1270.
+
+
+### Master-satellite interrupted/unstable connection
+
+This often happens due to overheating issues. Check if the Kasli/SoC fans are working properly and
+try installing rack fans to increase the air flow.

src/sw_sup/flashing_firmware.md

@@ -0,0 +1,20 @@
+# Flashing the Firmware
+
+Here are some extra steps needed for flashing the firmware.
+
+## Kasli
+
+### Windows
+
+From the [official manual](https://m-labs.hk/artiq/manual/installing.html#configuring-openocd):
+
+On Windows, a third-party tool, Zadig, is necessary. Use it as follows:
+1. Make sure the FPGA board’s JTAG USB port is connected to your computer.
+2. Activate Options → List All Devices.
+3. Select the “Digilent Adept USB Device (Interface 0)” or “FTDI Quad-RS232 HS” (or similar) device from the drop-down list.
+4. Select WinUSB from the spinner list.
+5. Click “Install Driver” or “Replace Driver”.
+6. After above steps done, you may see the devices in the Device Manager:
+   ![after_zadig_devices.png](../img/win32/after_zadig_devices.png)
+
+You may need to repeat these steps every time you plug the FPGA board into a port where it has not been plugged into previously on the same system.

src/sw_sup/moninj.md

@@ -0,0 +1,11 @@
+# Moninj
+
+The official documentation lacks the description of MONitor/INJector, but it is a common mistake when running the ARTIQ-7.
+Basically it is a service that consists of two parts - one runs on the host PC, another on the Kasli.
+It allows to watch and control the state of the devices, so you can see it on the dashboard.
+That's why the dashboard may emit errors about not working moninj. To fix this, you just need [to run it with Kasli's IP](https://m-labs.hk/artiq/manual/utilities.html#moninj-proxy):
+
+```shell
+aqctl_moninj_proxy CORE_ADDRESS
+```
+

src/sw_sup/networking.md

@@ -23,6 +23,23 @@ a-la `I can't connect, please help`.
     or connected to different address. If the packets just do not respond then it is not as clear, we cannot know all the truth.
 2. See the SFP0 LED
 3. See the ERR LED
-4. UART logs. TODO here is a link to ways to obtain them
+4. [UART logs](uart_logs.md)
 5. `nmap` and `arp` to scan your network to help your Kasli get discovered. May be restricted in your network.
-6. Become a router and capture all the packets when your Kasli tries to connect to the network.
+6. Directly connect your Kasli to the PC via Ethernet and set up networking on the PC: `ip addr change 192.168.1.0/24 dev eth0`
+7. Become a router and capture all the packets when your Kasli tries to connect to the network.
+
+
+## Direct connection
+
+Sometimes it is neccessary to connect your Kasli/Kasli-SoC (Carrier) directly to the PC/NUC. For example, your Kasli-SoC
+may be configured for the wrong network. In order to do this, you will just need to:
+1. Connect Carrier via Ethernet directly to the NUC/PC
+2. Set the network settings (example for default 192.168.1.75 Carrier setting):
+    ```
+    IPv4 method: Manual
+    Address: 192.168.1.0
+    Netmask: 255.255.255.0
+    Gateway: 192.168.1.0
+    DNS, Routes - Auto
+    ```
+   ![gnome_direct_conn_settings.png](../img/gnome_direct_conn_settings.png)

src/sw_sup/uart_logs.md

@@ -4,7 +4,7 @@ Used for network, booting, and most other issues debugging.
 
 ## How to get them
 
-First, connect your Kasli/SoC to the PC with a micro-USB cable. Once you turn on the device, wait at least 15 seconds
+First, connect your Kasli/SoC to the PC with a data micro-USB cable. Once you turn on the device, wait at least 15 seconds
 until its fully loaded.
 
 ### Development shell
@@ -22,11 +22,16 @@ until its fully loaded.
 
 ### Windows
 
+While Windows 11 tested to be working out-of-the box with both UART and flashing, Windows 10 may need additional drivers
+manipulations, as shown below.
+
 #### Drivers
 
 Use following instructions to set correct drivers for the COM ports.
 At choosing FTDI drivers stage you may have longer list of drivers. 
-In that case, choose respective `USB Serial Converter X` (A for 0, B for 1, C for 2, D for 3) driver. 
+In that case, choose respective `USB Serial Converter X` (A for 0, B for 1, C for 2, D for 3) driver. In case you cannot
+locate the devices, they may appear in the _Other devices_ section:
+![other_devices_section.png](../img/win32/other_devices_section.png)
 You may also need to reboot your PC after doing this.
 
 1. ![com_driver_set0.png](../img/win32/com_driver_set0.png)
@@ -37,6 +42,9 @@ You may also need to reboot your PC after doing this.
 6. ![com_driver_set5.png](../img/win32/com_driver_set5.png)
 7. ![com_driver_set6.png](../img/win32/com_driver_set6.png)
 
+If you are here after [flashing firmware](flashing_firmware.md) stage, you may fail to see the devices in the described locations.
+If you see them in the `Universal Serial Bus devices` section, you may need just to uninstall the third _Quad_ device and reconnect the
+Kasli/Kasli-SoC to the PC.
 
 #### Connecting with PuTTY