Implement ability to specify an external sample clock timebase signal

for analog inputs on an NI-DAQ.

This mitigates issues where the AI clock and the timing pseudoclock
can get out of sync with each other, particularly for long shots.

Author: dihm

docs/source/devices/ni_daqs.rst

@@ -79,6 +79,9 @@ Exact numbers of channels, performance, and configuration depend on the model of
 	AnalogOut('daq_ao0',daq,'ao0')
 	AnalogIn('daq_ai1',daq,'ai1')
 
+WaitMonitors
+------------
+
 NI DAQs are also used within labscript to provide a :class:`WaitMonitor <labscript:labscript.labscript.waitmonitor>`.
 When configured, the `WaitMonitor` allows for arbitrary-length pauses in experiment execution, waiting for some trigger to restart.
 The monitor provides a measurement of the duration of the wait for use in interpreting the resulting data from the experiment.
@@ -105,6 +108,23 @@ Note that the counter connection is specified using the logical label `'ctr0'`.
 The physical wiring for this configuration would have port0/line0 wired directly to PFI9, with PFI1 being sent to the master pseudoclock retriggering system in case of timeout.
 If timeouts are not expected/represent experiment failure, this physical connection can be omitted.
 
+AI timing skew
+--------------
+
+Given how the NI-DAQmx driver currently works,
+all of the outputs (and generally other hardware) are hardware-timed via direct outputs from the parent pseudoclocks.
+Under default usage, this is not true for the analog inputs of the DAQs,
+which are timed via the internal reference oscillator of the DAQ.
+Synchronization between the two is handled at the end by correlating start times and slicing the AI traces at the appropriate times.
+This works fine if the reference clocks for the pseudoclock and the DAQ don't drift relative to each other,
+but that is generally not the case for a longer shot (on the order of 1 second) since the standard clocks for a pulseblaster and a DAQ both have accuracy on the order of 50 ppm.
+
+With version 1.2.0 of the NI-DAQmx driver, this issue can be mitigated by suppling an external sample timebase that is phase synchronous with the DAQ's pseudoclock device.
+This is done using the DAQmx `SampleClkTimebase` synchronization method.
+Simply provide an external clocking signal that is faster than the analog input sampling rate,
+and the DAQ will use an internall PLL to derive the AI sample clock from the provided timebase.
+Specifying an externally provided sample timebase is done using the `AI_timebase_terminal` and `AI_timebase_rate` arguments,
+which specify the input terminal (generally a PFI line) and the clock frequency.
 
 Detailed Documentation
 ~~~~~~~~~~~~~~~~~~~~~~

labscript_devices/NI_DAQmx/blacs_tabs.py

@@ -204,6 +204,8 @@ def initialise_GUI(self):
                     'AI_range': properties['AI_range'],
                     'AI_start_delay': properties['AI_start_delay'],
                     'AI_start_delay_ticks': properties['AI_start_delay_ticks'],
+                    'AI_timebase_terminal': properties.get('AI_timebase_terminal',None),
+                    'AI_timebase_rate': properties.get('AI_timebase_rate',None),
                     'clock_terminal': clock_terminal,
                 },
             )

labscript_devices/NI_DAQmx/blacs_workers.py

@@ -491,6 +491,13 @@ def start_task(self, chans, rate):
                 None,
             )
 
+        if self.AI_timebase_terminal is None:
+            # use internal default
+            pass
+        else:
+            self.task.SetSampClkTimebaseSrc(self.AI_timebase_terminal)
+            self.task.SetSampClkTimebaseRate(self.AI_timebase_rate)
+
         self.task.CfgSampClkTiming(
             "", rate, DAQmx_Val_Rising, DAQmx_Val_ContSamps, num_samples
         )

labscript_devices/NI_DAQmx/labscript_devices.py

@@ -11,7 +11,7 @@
 #                                                                   #
 #####################################################################
 
-__version__ = '1.1.0'
+__version__ = '1.2.0'
 
 
 from labscript import (
@@ -63,6 +63,8 @@ class NI_DAQmx(IntermediateDevice):
                 "AI_start_delay_ticks",
                 "AI_term",
                 "AI_chans",
+                "AI_timebase_terminal",
+                "AI_timebase_rate",
                 "AO_range",
                 "max_AI_multi_chan_rate",
                 "max_AI_single_chan_rate",
@@ -100,6 +102,8 @@ def __init__(
         AI_start_delay_ticks=None,
         AI_term='RSE',
         AI_term_cfg=None,
+        AI_timebase_terminal=None,
+        AI_timebase_rate=None,
         AO_range=None,
         max_AI_multi_chan_rate=None,
         max_AI_single_chan_rate=None,
@@ -149,6 +153,12 @@ def __init__(
             AI_term_cfg (dict, optional): Dictionary of analog input channels and their
                 supported terminations. Best to use `get_capabilities.py` to introspect
                 these.
+            AI_timebase_terminal (str, optional): Channel string that specifies what
+                channel to use for the Sample Clock Timebase signal.
+                If None, use default internal clocks.
+                Must also specify the rate when not using the internal sources.
+            AI_timebase_rate (float, optional): Supplied clock frequency for the AI timebase.
+                Only specify if using an external clock source.
             AO_range (iterable, optional): A `[Vmin, Vmax]` pair that sets the analog
                 output voltage range for all analog outputs.
             max_AI_multi_chan_rate (float, optional): Max supported analog input 
@@ -245,6 +255,13 @@ def __init__(
             # no analog inputs
             self.AI_chans = []
             self.start_delay_ticks = None
+        # special AI timebase handling
+        if num_AI > 0:
+            if (AI_timebase_rate is None) ^ (AI_timebase_terminal is None):
+                raise LabscriptError("You must specify terminal and rate when using an external AI timebase")
+            self.AI_timebase_terminal = AI_timebase_terminal
+            self.AI_timebease_rate = AI_timebase_rate
+                
         self.num_AO = num_AO
         self.num_CI = num_CI
         self.ports = ports if ports is not None else {}