4410: add SU-Servo

ARTIQ example for SU-Servo is using API prior to artiq PR 1500.
Will need to update to the latest beta at some point.

4410-4412.tex

@@ -47,6 +47,7 @@
 \item{Dynamic low-noise RF source.}
 \item{Driving RF electrodes in ion traps.}
 \item{Driving acousto-optic modulators.}
+\item{Form a laser intensity servo with 5108 Sampler.}
 \end{itemize}
 
 \section{General Description}
@@ -837,10 +838,102 @@ def run(self):
 \end{minted}
 Two phase-coherent RF signal with the same waveform as the previous figure (from either RAM examples) should be generated.
 
+\subsection{Voltage-controlled DDS Amplitude (SU-Servo Only)}
+The SU-Servo feature can be enabled by integrating the 4410 Urukul with a 5108 Sampler.
+Amplitude of the DDS output can be controlled by the ADC input of the Sampler through PI control, characterised by the following transfer function.
+\[H(s)=k_p+\frac{k_i}{s+\frac{k_i}{g}}\]
+In the following example, the amplitude of DDS is proportional to the ADC input from Sampler.
+First, initialize the RTIO, SU-Servo and its channel.
+Note that the programmable gain of the Sampler is $10^0=1$, the input range is [-10V, 10V].
+\begin{minted}{python}
+@kernel
+def run(self):
+    self.core.reset()
+    self.core.break_realtime()
+    self.suservo.init()
+    self.suservo.set_pgia_mu(0, 0)  # unity gain
+    self.suservo.cpld0.set_att(0, 15.)
+    self.channel.set_y(profile=0, y=0.) # Clear integrator
+\end{minted}
+
+Next, setup the PI control as an IIR filter. It has -1 proportional gain $k_p$ and no integrator gain $k_i$.
+
+\begin{minted}{python}
+    self.channel.set_iir(
+        profile=0,
+        adc=0,          # take data from Sampler channel 0
+        kp=-1.,         # -1 P gain
+        ki=0./s,        # no integrator gain
+        g=0.,           # no integrator gain limit
+        delay=0.        # no IIR update delay after enabling
+    )
+\end{minted}
+
+Then, configure the DDS frequency to 10 MHz with 3V input offset.
+At input offset voltage, the DDS output amplitude is 0.
+
+\begin{minted}{python}
+    self.channel.set_dds(
+        profile=0,
+        offset=-.3,     # 3V with above PGIA settings
+                        # Note the inverted sign
+        frequency=10*MHz,
+        phase=0.)
+\end{minted}
+
+SU-Servo encodes the ADC voltage in a linear scale [-1, 1].
+Therefore, 3V is converted to 0.3.
+Note that the ASF of all DDS channels are capped at 1.0, the amplitude clips when ADC input $\leq -7V$ with the above IIR filter.
+
+Finally, enable the SU-Servo channel with the IIR filter programmed beforehand.
+
+\begin{minted}{python}
+    self.channel.set(en_out=1, en_iir=1, profile=0)
+    self.suservo.set_config(enable=1)
+\end{minted}
+
+A 10 MHz DDS signal is generated from the example above, with amplitude controllable by ADC.
+The RMS voltage of the DDS channel against the ADC voltage is plotted.
+The DDS channel is terminated with 50\textOmega.
+
+\begin{center}
+\begin{tikzpicture}[
+    declare function={
+        func(\x)= and(\x>=-10, \x<-7) * (160) +
+            and(\x>=-7, \x<3) * (16*(3-x)) +
+            and(\x>=3, \x<10) * (0);
+    }
+]
+\begin{axis}[
+    axis x line=middle, axis y line=middle,
+    every axis x label/.style={
+        at={(axis description cs:0.5,-0.1)},
+        anchor=north,
+    },
+    every axis y label/.style={
+        at={(ticklabel* cs:1.05)},
+        anchor=south,
+    },
+    minor tick num=3,
+    grid=both,
+    height=8cm,
+    width=12cm,
+    ymin=0, ymax=160, ytick={0,16,...,160}, ylabel=DDS RMS Voltage ($mV_{rms}$),
+    xmin=-10, xmax=10, xtick={-10,-8,...,10}, xlabel=Sampler Voltage ($V$),
+]
+
+\addplot[blue, samples=21, domain=-10:10]{func(x)};
+\end{axis}
+\end{tikzpicture}
+\end{center}
+
+Note: DDS signal should be attenuated. High output power may affect the linearity.
+
 \section{Ordering Information}
 To order, please visit \url{https://m-labs.hk} and select the 4410 Urukul in the ARTIQ Sinara crate configuration tool.
 The default chip is AD9910 (4410 Urukul), which supports more features.
 If you need the higher frequency resolution of the AD9912 (4412 Urukul), leave us a note when placing the order.
+To enable SU-Servo feature between 4410 Urukul and 5108 Sampler, specify that SU-Servo is to be integrated into the gateware when placing the order.
 The cards may also be ordered separately by writing to \url{mailto:sales@m-labs.hk}.
 
 \section*{}