assembly/src/hw/urukul.md

# Sinara 4410/4412 DDS Urukul (AD9910/AD9912)

* [Datasheet](https://m-labs.hk/docs/sinara-datasheets/4410-4412.pdf)
* [Wiki](https://github.com/sinara-hw/Urukul/wiki)
* [Firmware](https://github.com/quartiq/urukul)

## JSON

```json
{
    "type": "urukul",
    "dds": "<variant>", // ad9910/ad9912
    "ports": [<port num>, <port num>], // second port is optional
    "clk_sel": <clock num>,
    "refclk": <freq>, // for external clock signal
    "pll_en": <0 or 1, default 1> // PLL bypass, to allow higher external clocker frequencies (1e9 for example)
}
```

## Setup

Check if [SUServo](./suservo.md) is enabled/disabled respective to customer needs. Connect to the clocker source.

## Testing

After running `artiq_sinara_test`:

```text
*** Testing Urukul DDSes.
urukul0_cpld: initializing CPLD...
urukul0_cpld: testing attenuator digital control...
urukul0_cpld: done
Calibrating inter-device synchronization...
urukul0_ch0	no EEPROM synchronization
urukul0_ch1	no EEPROM synchronization
urukul0_ch2	no EEPROM synchronization
urukul0_ch3	no EEPROM synchronization
...done
All urukul channels active.
Check each channel amplitude (~1.6Vpp/8dbm at 50ohm) and frequency.
Frequencies:
urukul0_ch0	10MHz
urukul0_ch1	11MHz
urukul0_ch2	12MHz
urukul0_ch3	13MHz
Press ENTER when done.

Testing RF switch control. Check LEDs at urukul RF ports.
Press ENTER when done.
```

1. Setup oscilloscope's impedance at 50 ohm
2. Touch each connector with oscilloscope, setup time- and voltage- scale and trigger, so that you can see sine waves
3. Measure frequencies and amplitudes on each connector, check with `artiq_sinara_test`'s respective values
4. When done, proceed with `artiq_sinara_test` and check LEDs are lighting up one after another


## Common problems

### 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). 

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 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 
   ```shell
   *** buffer overflow detected ***: terminated
   Aborted (core dumped)
   ```
   , which is okay if `Verify: Success` was also emitted.

### no valid window/delay

```pycon
ValueError: no valid window/delay
```

Check with the customer to see if synchronization is necessary, and disable it if it is not. 
In any case, simply restart the test.

### Noise instead of signal

It may be due to misconfiguration of SUServo. Check that both firmware and pins enable/disable the SUServo mode.

### Improper frequency

This can happen due to lack/bad clock source connection. Check that clock source is connected respective to the customer needs,
and if it is connected to the [Clocker](clocker.md), check that clocker receives clock signal properly.

### Urukul proto_rev mismatch

```pycon
ValueError: Urukul proto_rev mismatch
```

Check the ports are connected respectively to the JSON description.

### PLL lock timeout

```pycon
ValueError: PLL lock timeout
```

This can happen due to lack/bad clock source connection. Check that clock source is connected respective to the customer needs,
and if it is connected to the [Clocker](clocker.md), check that clocker receives clock signal properly and `EXT`/`INT` pin 
matches real clocker source.

### Urukul AD9910 AUX_DAC mismatch

```pycon
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.