Update Shuttler Assembly Instructions

src/SUMMARY.md

@@ -10,6 +10,7 @@
   - [Sinara 2118 BNC-TTL / 2128 SMA-TTL](./hw/bnc_sma_ttl.md)
   - [Sinara 2138 MCX-TTL](./hw/mcx_ttl.md)
   - [Sinara 5432 DAC Zotino / Sinara 5632 DAC Fastino](./hw/zotino_fastino.md)
+  - [Sinara 5716 DAC Shuttler](./hw/shuttler.md)
   - [Sinara 5518 BNC-IDC / 5528 SMA-IDC adapter](./hw/bnc_sma_idc_adapter.md)
   - [Sinara 4410/4412 DDS Urukul (AD9910/AD9912)](./hw/urukul.md)
   - [Sinara 5108 Sampler](./hw/sampler.md)

src/hw/shuttler.md

@@ -1,5 +1,8 @@
 # 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 [EEM FMC Carrier](https://github.com/sinara-hw/EEM_FMC_Carrier) (EFC) Board. The EFC Board has an FPGA on board that requires special attention when flashing.
+
+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 [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. At first power up, EFC Board and connected Kasli/Kasli-soc calibrate the EEM signal delay and store the value into the flash memory/SD Card.
 
 ## JSON
 
@@ -12,15 +15,17 @@ The Sinara 5716 DAC Shuttler consists of the [Shuttler](https://github.com/sinar
 
 ## Hardware Configurations and Connections
 ### EEM Cable Connection 
-Only the EEM0 port on the EFC board is used. The EEM Cable will provide power. You can ignore the barrel jack at the back of the board.
+
+Only the EEM0 port on the EFC board is used. The EEM Cable provides power. You can ignore the barrel jack at the back of the board(if fitted).
 
 ### CLK Input
-The EFC requires a common clock source with the Kasli/Kasli-Soc Master.
+
+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.
-![issue](../img/efc_clk_sel.png).
+![efc_clk_sel](../img/efc_clk_sel.png)
 
 | Clock Source | CLK_SEL0 | CLK_SEL1 |
 |---|---|---|
@@ -30,33 +35,68 @@ For the EFC Board v1.1 (or later), there is a DIP switch to select the clock sou
 | PE CLK | 1 | 1 |
 
 ### VADJ Power
-You should fit the W1 with a jumper to set VADJ to 1.8V.
+
+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, please connect the **Impedance Matched Pair** of Mini SAS Cables in this orientation.
+
+The Remote AFE Board is not installed in the crate and should be shipped separately. When you test the EFC, 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 Board to a lab PSU supplying +15V, -15V, and +5V. Please ensure all voltages share a common GND and check the pinout carefully. Incorrect power connections can damage the AFE Board.                                                  
+There is no PSU for the Remote AFE Board at this moment. For testing purposes, you should connect the Remote AFE Board to a lab PSU supplying +15V, -15V, and +5V. Please make sure all voltages share a common GND and check the pinout carefully. Incorrect power connections can damage the Remote AFE Board.                                                  
+
+## Building EFC Board Gateware and Firmware
 
-## Building
 The EFC Board gateware and firmware are on the Artiq repo.
 
 To build the gateware and firmware,
 ```
-python -m artiq.gateware.targets.efc
+python -m artiq.gateware.targets.efc --hw-rev [v1.0, v1.1]
+```
+
+## 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, you will need to specify the routing table on the Kasli/Kasli-soc master in order to access the Shuttler hardware. Shuttler locates at DEST 4 connecting to Repeater ID #3. The ID number goes up accordingly if more than one Shuttler is connected.
+
+Here provides an example to configure the routing table.
+You have 1 Kasli Master and 1 Kasli Satellite. Kasli Master (SFP1)(DEST1) port is connected to Kasli Satellite(SFP0)(DEST0). Shuttler is connected to Kasli Satellite with DRTIO over EEM Cable(DEST4).
+
+Initialize the Routing Table
+```
+artiq_route rt.bin init
+```
+
+Add the routing table entry for Kasli Master's Peripherals
+```
+artiq_route rt.bin set 0 0
+```
+
+Add the routing table entry for Kasli Satellite's Peripherals
+```
+artiq_route rt.bin set 1 1 0
+```
+Add the routing table entry for Shuttler
+```
+artiq_route rt.bin set 4 1 4 0
+```
+
+Flash the routing table on Kasli Master
+```
+artiq_coremgmt config write -f routing_table rt.bin
 ```
 
 ## Flashing
-The EFC and Kasli/Kasli-Soc Master will calibrate each other's IO signal delay at the first startup and then store the calibrated value in the flash memory.
 
-When a crate is built, you should erase the flash on both the EFC and Kasli/Kasli-Soc. Flash the EFC Board first before flashing the Kasli/Kasli-Soc.
+When a crate is built, you should erase the flash/sd card config on both the EFC and Kasli/Kasli-soc. Always flash the EFC Board first before flashing the Kasli/Kasli-soc.
 
-If either of these elements is changed, you will need to **ERASE** the stored calibrated values on both the EFC and Kasli/Kasli-Soc Master, or the communication between the boards cannot be established:
+If either of the following elements is changed, you will need to **ERASE** the stored calibrated values on both the EFC and Kasli Master, or the communication between the boards cannot be established:
 1. EEM Cable
 2. Clock-Related Cable
 3. EFC Board Gateware
-4. Kasli/Kasli-Soc Master Gateware
-5. EFC Board/Kasli/Kasli-Soc Master replacement
+4. Kasli Master Gateware
+5. EFC Board/Kasli Master replacement
 
 To erase the flash on the EFC board,
 ```
@@ -65,12 +105,36 @@ artiq_flash -t efc erase
 
 To flash the gateware and firmware onto the EFC board,
 ```
-artiq_flash --srcbuild -t efc -d artiq_efc/shuttler
+artiq_flash --srcbuild -t [efc1v0, efc1v1] -d artiq_efc/shuttler
 ```
 
 ## Testing
-1. Power up both boards. 
-2. After calibration is completed, power cycle the boards.
-3. Run the test
 
-`artiq_sinara_test` is not developed yet. Please run Shuttler's core device example code on the Artiq repo for a basic test and look at the waveform output at OUT0 and OUT1 on the D-Sub connector.
+It is required for the Remote AFE Card to be connected to the Shuttler for the whole system to be functional.
+
+1. Power up the Remote AFE Board and the Kasli/Kasli-Soc with the connected Shuttler.
+2. Remote AFE Board had all Power Indicator LEDs being lit up.
+3. Run the `artiq_sinara_test`. 
+
+
+```
+*** Testing LEDs.
+Check for blinking. Press ENTER when done.
+...
+Testing LED: shuttler0_led0
+Testing LED: shuttler0_led1
+
+*** Testing Shuttler.
+Testing: shuttler0
+Check if Shuttler Output Channel 0 has 5V
+Check if Relay LED Indicator 0 is lit up
+Channel 0 ADC Reading is 4.998898506164551
+Press Enter to Continue
+
+Check if Shuttler Output Channel 1 has 5V
+Check if Relay LED Indicator 1 is lit up
+Channel 1 ADC Reading is 5.000171065330505
+Press Enter to Continue
+
+...
+```