Add assembly instructions for Shuttler (#13)

Add assembly instructions for Shuttler

Reviewed-on: #13
Co-authored-by: linuswck <linuswck@m-labs.hk>
Co-committed-by: linuswck <linuswck@m-labs.hk>

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

@@ -0,0 +1,120 @@
+# 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 running Kasli Satellite. DRTIO communication is established through the EEM Cable. At first power up, EFC Board and connected Kasli/Kasli-soc calibrate the clock skews on their own EEM transceiver and then store the value into the flash memory/SD Card.
+
+## JSON
+
+```json
+{
+    "type": "shuttler",
+    "ports": [<port num>]
+}
+```
+
+## Hardware Configurations and Connections
+### 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 the back of the board if it is placed.
+
+### CLK Input
+
+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 |
+|---|---|---|
+| Front Panel SMA | 0 | 0 |
+| Internal Oscillator(default) | 1 | 0 |
+| MMCX | 0 | 1 |
+| PE CLK | 1 | 1 |
+
+### VADJ Power
+
+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 Board to a lab PSU supplying +15V, -15V, and +5V. Please make sure all voltages share a common GND and check the pinouts carefully. Incorrect power connections can damage the Remote AFE Board.                                                  
+
+## Building EFC Board Gateware and Firmware
+
+The EFC Board gateware and firmware are on the [Artiq](https://github.com/m-labs/artiq) repo.
+
+To build the gateware and firmware,
+```
+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).
+
+1. Initialize the Routing Table: ``` artiq_route rt.bin init```
+2. Add the routing table entry for Kasli Master's Peripherals: ```artiq_route rt.bin set 0 0```
+3. Add the routing table entry for Kasli Satellite's Peripherals: ```artiq_route rt.bin set 1 1 0```
+4. Add the routing table entry for Shuttler: ```artiq_route rt.bin set 4 1 4 0```
+5. Flash the routing table on Kasli Master: ```artiq_coremgmt config write -f routing_table rt.bin```
+
+## Flashing
+
+When you are building a crate with shuttler(s), 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 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 PCB
+
+To erase the flash on the EFC board,
+```
+artiq_flash -t efc erase
+```
+
+To flash the gateware and firmware onto the EFC board,
+```
+artiq_flash --srcbuild -t [efc1v0, efc1v1] -d artiq_efc/shuttler
+```
+
+## Testing
+
+1. Connect the Remote AFE Card to the Shuttler
+2. Power up the Remote AFE Board and the Kasli/Kasli-Soc with the connected Shuttler.
+3. Check all Remote AFE Board Power Indicator LEDs.
+4. 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 Remote AFE Board Relay LED Indicators.
+Press Enter to Continue.
+
+Testing Shuttler DAC
+Voltages: 0.1 -0.1 0.2 -0.2 0.3 -0.3 0.4 -0.4 0.5 -0.5 0.6 -0.6 0.7 -0.7 0.8 -0.8
+Press Enter to Continue.
+
+PASSED
+
+...
+```