Add instruction for SUServo

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

README.md

@@ -27,9 +27,11 @@ feel free to push them.
 Tips for adding hardware instructions:
 
 1. Compose a chapter in a new Markdown file in `src/hw`
-2. Add pictures if needed, store them in `src/img`
+2. Add pictures if needed, store them in `src/img`, assure them to be clear, informative and compressed
+   (you can use `convert <INPUT IMAGE> -quality 80% -resize <width>x<height> <OUTPUT IMAGE>` for optimizing)
 3. Add link to the new chapter to the `src/SUMMARY.md`
 4. Do not forget to tell about all hidden/non-obvious obstacles and pitfalls
 5. Add testing steps, even if the "obvious" ones
 6. Add JSON sample if needed
-7. View changed and added pages with `mdbook build` (see building instructions above)
+7. Add hardware setup (e.g. pins, switches) steps if needed
+8. View changed and added pages with `mdbook build` (see building instructions above)

src/SUMMARY.md

@@ -4,3 +4,4 @@
 - [Hardware](./hw/hardware.md)
   - [Sinara 4624 AWG Phaser (Upconverter)](./hw/phaser_upconverter.md)
   - [Sinara 4456 synthesizer Mirny](./hw/mirny.md)
+  - [SUServo (Sampler + Urukul)](./hw/suservo.md)

src/hw/suservo.md

@@ -0,0 +1,55 @@
+# SUServo (Sampler + Urukul)
+
+## JSON
+
+```json
+{
+  "type": "suservo",
+  "sampler_ports": [<port num>, <port num>],
+  "urukulN_ports": [<port num>, <port num>],
+  "urukulM_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
+
+On bottoms of each Urukul, switch first pins 1 and 2 to `ON`, as on the picture:
+![](../img/urukul_pins_suservo.jpeg)
+
+## Testing
+
+```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.