assembly/src/hw/suservo.md

# SUServo (Sampler + Urukul)

## JSON

```json
{
  "type": "suservo",
  "sampler_ports": [<port num>, <port num>],
  "urukul0_ports": [<port num>, <port num>],
  "urukul1_ports": [<port num>, <port num>], // optional
  "clk_sel": 2
}
```

With enabled SUServo mode, you only need to add `suservo` to JSON file, with its Sampler and Urukul(s) removed.

## Setup

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`:

```text
*** Testing SUServos.
Initializing modules...
suservo0
...done
Setting up SUServo channels...
suservo0_ch0
suservo0_ch1
suservo0_ch2
suservo0_ch3
suservo0_ch4
suservo0_ch5
suservo0_ch6
suservo0_ch7
...done
Enabling...
suservo0
...done
Each Sampler channel applies proportional amplitude control
on the respective Urukul0 (ADC 0-3) and Urukul1 (ADC 4-7, if
present) channels.
Frequency: 10 MHz, output power: about -9 dBm at 0 V and about -15 dBm at 1.5 V
Verify frequency and power behavior.
```

1. Connect oscilloscope to the `urukul0` port and configure with time and voltage scale and trigger threshold
   so that you'll see sine wave, like on the picture: ![](../img/urukul_suservo_output_without_battery.jpg)
2. Verify amplitude and frequency
3. Apply 1.5V (connect the AA-battery) to the `sampler0` port, as on the
   picture: ![](../img/urukul_sampler_susevo_connections.jpg)
4. You should see significant amplitude decrease, as in the picture: ![](../img/urukul_suservo_output_with_battery.jpg)
5. Verify amplitude difference, and the frequency to be unchanged
6. Repeat steps 1-5 for every available channel.