Update networking and add UART logs for windows

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

src/SUMMARY.md

@@ -16,3 +16,6 @@
   - [Sinara 8452 DSP Stabilizer](./hw/stabilizer.md)
   - [Sinara 9805 RF Power Amplifier Booster](./hw/booster.md)
   - [Sinara 8451 Thermostat](./hw/thermostat.md)
+- [Software/Support](./sw_sup/software_support.md)
+  - [Networking](./sw_sup/networking.md)
+  - [UART Logs](./sw_sup/uart_logs.md)

src/build_test_firmware.md

@@ -1,5 +1,16 @@
 # Build and test firmware
 
+## Operating hints and warnings
+
+* 😡 **Always** use grounding strap during dis/assembly or other cards' physical operation
+* 😡 **Always** power off devices before un/plugging
+* 🧐 If needed to power-cycle the crate, wait at least 30 seconds before turning them on
+* 🙅 Avoid the boards touching conductive materials - wires, metals. Use at 
+  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
+
 ## Kasli standalone
 
 ### Checklist
@@ -9,26 +20,20 @@
 3. Test hardware
 4. Create a flash-drive with `device_db.py` file for customers (FAT32)
 
-### CLI commands
+### CLI commands - build and flash
 
 ```shell
 mkdir <variant>
 cd <variant>/
-git clone git@github.com:m-labs/artiq.git
-cd artiq/
-git checkout origin/release-7
-nix develop
+nix develop github:m-labs/artiq\?ref=release-7
+# master/standalone only
 artiq_mkfs -s ip 192.168.1.75 kasli.config
 artiq_flash storage -f kasli.config
 artiq_ddb_template -o device_db.py <variant>.json 
 python -m artiq.gateware.targets.kasli_generic <variant>.json 
 artiq_flash --srcbuild -d artiq_kasli/<variant>/
-artiq_sinara_tester
 ```
 
-Follow `artiq_sinara_tester` instructions for testing the hardware. For more detailed information, 
-you can use this book's pages, or if there is no instruction for testing your hardware, please add them to this book.
-
 ## Kasli-SoC (zynq)
 
 ### Checklist
@@ -41,37 +46,42 @@ you can use this book's pages, or if there is no instruction for testing your ha
 6. Test hardware
 7. Create a flash-drive with `device_db.py` file for customers (FAT32)
 
-### CLI commands
+### CLI commands - build and flash
 
 ```shell
 mkdir <variant>
 cd <variant>/
-git clone gitea@git.m-labs.hk:M-Labs/artiq-zynq.git
-cd artiq-zynq/
-git checkout origin/release-7
-nix develop
+nix develop git+https://git.m-labs.hk/m-labs/artiq-zynq\?ref=release-7
 artiq_ddb_template -o device_db.py <variant>.json 
-nix build -L --impure --expr 'let fl = builtins.getFlake "git+file://<path to artiq_zynq repo>"; in (fl.makeArtiqZynqPackage {target="kasli_soc"; variant="[master, standalone, satellite]"; json=<path to the json description>;}).kasli_soc-[master, standalone, satellite]-sd' 
+nix build -L --impure --expr 'let fl = builtins.getFlake "git+https://git.m-labs.hk/m-labs/artiq-zynq?ref=release-7"; in (fl.makeArtiqZynqPackage {target="kasli_soc"; variant="[master, standalone, satellite]"; json=<full path to the json description>;}).kasli_soc-[master, standalone, satellite]-sd' 
 # copy `results/boot.bin` to the SD card
 # insert SD card to the Kasli-SoC and boot
 artiq_coremgmt -D 192.168.1.56 config write -s ip 192.168.1.75 # or just place extra/CONFIG.TXT near the boot.bin on SD card
-# update firmware
+# update firmware (alternative to copy to SD, if ARTIQ already running)
 artiq_coremgmt config write -f boot result/boot.bin
 # reboot via power supply
+```
+
+## Testing (common)
+
+```
 artiq_sinara_tester
 ```
 
+Follow `artiq_sinara_tester` instructions for testing the hardware. For more detailed information, 
+you can use this book's pages, or if there is no instruction for testing your hardware, please add them to this book.
+
 ### 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 reconnect the card to the other ports until it gets working.
+  do not work properly with some EEM ports. You might need to connect the card to the other ports until it gets working.
 
 ## Master-satellite setups
 
 1. Change `base` in JSON to the respective `master` or `satellite`, add `"enable_sata_drtio": true` if needed to the master,
    remove `core_addr` in satellites
 2. Build and flash firmware for each crate with JSONs (see instructions above)
-3. Create composed `device_db.py`: `artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <master>.json`
+3. Create composed `device_db.py`: e.g. `artiq_ddb_template -o device_db.py -s 1 <satellite1>.json -s 2 <satellite2>.json <master>.json`
 4. Connect satellite crates to the master respective to their numbers via the fiber (see example picture)
    ![](img/master_sat_connection.jpg)
 5. Ethernet is needed only for master

src/hw/zotino_fastino.md

@@ -48,3 +48,11 @@ Press ENTER when done.
 2. Check that respective pins have voltages as described by `artiq_sinara_test`
 3. If there are [BNC/SMA-IDC adapters](./bnc_sma_idc_adapter.md), also check their voltages - they should be the same
 4. Check LEDs are on
+
+
+## Common problems
+
+### 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).

src/sw_sup/networking.md

@@ -0,0 +1,28 @@
+# Networking
+
+This page should help solving common network/related problems,
+a-la `I can't connect, please help`.
+
+## Common problems
+
+1. `device_db.py` has misleading `core_addr` address.
+2. PC and the crate are in different subnets. They should be in the same network. Also you may want to directly attach the Kasli to the PC.
+3. Network restrictions/problems on your router, either by IP, MAC, protocols or anything else.
+4. Wrong configuration of the Kasli. Change IP or MAC address to correspond your network. For ARTIQ-8, add 
+   network mask to the `ip` setting on Kasli, like `192.168.1.75/24`.
+5. Incompatible Ethernet cables/SFP RJ45. Try different cables and SFP adapters. 
+   We usually test them with CAT6 cables, but lower categories should be supported too.
+6. SFP or Ethernet are not pushed til the end.
+7. Some weird bugs in Vivado, leading to not working SFP on certain combinations of builds and Kaslis (very rare)
+8. Running configured for external reference Kasli without external reference clock signal 
+9. Using legacy firmware with newer hardware. ARTIQ-6 doesn't support Kasli v2.0.2
+
+## Ways to diagnose
+
+1. `ping` the device. If destination is unreachable, than it is either didn't connect to the network
+    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
+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.

src/sw_sup/software_support.md

@@ -0,0 +1,10 @@
+# Software/Support
+
+In this section you'll find instructions, tips and hints mostly
+regarding software. The main intend of this section is to ease the support
+process, which often includes answering similar questions and solving similar problems.
+In the future, it may be revised and added to the official ARTIQ manual.
+
+I hope that helps!
+
+![curious_doge.jpg](../img/curious_doge.jpg)

src/sw_sup/uart_logs.md

@@ -0,0 +1,49 @@
+# UART Logs
+
+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
+until its fully loaded.
+
+### Development shell
+
+1. `flterm /dev/ttyUSBX`, where `X` is usually third (index 2) from suggested variants.
+2. Restart the device with `artiq_flash start`
+3. If it didn't work, try all of `/dev/ttyUSBX`, and restart the device
+
+### Older Nix and other Linuxes
+
+1. Install `cutecom` via `nix-shell -p cutecom` or your package manager
+2. Run `cutecom` and follow settings from the picture: ![uart_cutecom.png](../img/uart_cutecom.png)
+3. Restart the device with `artiq_flash start`, or by power-cycling it (wait 30 seconds before turning on)
+4. If it didn't work, try all of `/dev/ttyUSBX`, and restart the device
+
+### Windows
+
+#### 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. 
+You may also need to reboot your PC after doing this.
+
+1. ![com_driver_set0.png](../img/win32/com_driver_set0.png)
+2. ![com_driver_set1.png](../img/win32/com_driver_set1.png)
+3. ![com_driver_set2.png](../img/win32/com_driver_set2.png)
+4. ![com_driver_set3.png](../img/win32/com_driver_set3.png)
+5. ![com_driver_set4.png](../img/win32/com_driver_set4.png)
+6. ![com_driver_set5.png](../img/win32/com_driver_set5.png)
+7. ![com_driver_set6.png](../img/win32/com_driver_set6.png)
+
+
+#### Connecting with PuTTY
+
+1. Enable options shown on picture:
+   ![putty_lfcr.png](../img/win32/putty_lfcr.png)
+2. Be aware of these options:
+   ![putty_com_settings.png](../img/win32/putty_com_settings.png)
+3. Connect to every COM port you find on connecting the device (usually connecting the the third port is enough)
+4. Restart the device with `artiq_flash start`, or by power-cycling it (wait 30 seconds before turning on)
+5. See which COM port produces meaningful output and close others :)