Merge pull request #102 from dihm/NIDAQ_AI_ext_timebase

Externally clocked analog inputs on NI-DAQmx

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.
@@ -154,6 +157,23 @@ For example, to share the clock in the previous with an additional PXIe-6535 dig
 
 In addition to clocking, the `connected_terminals` argument can be used to link output terminals on an NI DAQ module to shared triggers, then link those shared triggers to input terminals of another NI DAQ module in the same chassis.
 
+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

@@ -206,6 +206,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

@@ -514,6 +514,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 (
@@ -64,6 +64,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",
@@ -102,6 +104,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,
@@ -154,6 +158,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 
@@ -250,6 +260,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 {}