Add task.read_waveform() for analog inputs (#807)

mikeprosserni · Mike Prosser · web-flow · commit c1e9869575e4 · 2025-08-19T11:40:16.000-05:00
* add task.read_waveform() for analog inputs

* test___analog_multi_channel_finite___read_waveform_too_many_samples___returns_waveforms_with_correct_number_of_samples

* address feedback

---------

Co-authored-by: Mike Prosser &lt;Mike.Prosser@emerson.com&gt;
diff --git a/examples/analog_in/voltage_acq_int_clk_wfm.py b/examples/analog_in/voltage_acq_int_clk_wfm.py
@@ -9,15 +9,13 @@
 os.environ["NIDAQMX_ENABLE_WAVEFORM_SUPPORT"] = "1"
 
 import nidaqmx  # noqa: E402 # Must import after setting environment variable
-from nidaqmx.constants import AcquisitionType, READ_ALL_AVAILABLE  # noqa: E402
-from nidaqmx.stream_readers import AnalogSingleChannelReader  # noqa: E402
+from nidaqmx.constants import AcquisitionType  # noqa: E402
 
 with nidaqmx.Task() as task:
     task.ai_channels.add_ai_voltage_chan("Dev1/ai0")
     task.timing.cfg_samp_clk_timing(1000.0, sample_mode=AcquisitionType.FINITE, samps_per_chan=50)
 
-    reader = AnalogSingleChannelReader(task.in_stream)
-    waveform = reader.read_waveform(READ_ALL_AVAILABLE)
+    waveform = task.read_waveform()
     print(f"Acquired data: {waveform.scaled_data}")
     print(f"Channel name: {waveform.channel_name}")
     print(f"Unit description: {waveform.unit_description}")
diff --git a/generated/nidaqmx/stream_readers.py b/generated/nidaqmx/stream_readers.py
@@ -303,7 +303,7 @@ def read_waveform(
                 number_of_samples_per_channel))
 
         if waveform is None:
-            waveform = AnalogWaveform(raw_data=numpy.zeros(number_of_samples_per_channel, dtype=numpy.float64))
+            waveform = AnalogWaveform(number_of_samples_per_channel)
         elif number_of_samples_per_channel > waveform.sample_count:
             # TODO: AB#3228924 - if allowed by the caller, increase the sample count of the waveform
             raise DaqError(
@@ -519,7 +519,7 @@ def read_waveforms(
 
         if waveforms is None:
             waveforms = [
-                AnalogWaveform(raw_data=numpy.zeros(number_of_samples_per_channel, dtype=numpy.float64))
+                AnalogWaveform(number_of_samples_per_channel)
                 for _ in range(number_of_channels)
             ]
         else:
diff --git a/generated/nidaqmx/task/_task.py b/generated/nidaqmx/task/_task.py
@@ -3,10 +3,11 @@
 import threading
 import warnings
 from enum import Enum
-from typing import List, Tuple, Union
 
 import numpy
+from nitypes.waveform import AnalogWaveform
 from nidaqmx import utils
+from nidaqmx._feature_toggles import WAVEFORM_SUPPORT, requires_feature
 from nidaqmx.task.channels._channel import Channel
 from nidaqmx.task._export_signals import ExportSignals
 from nidaqmx.task._in_stream import InStream
@@ -516,6 +517,7 @@ def read(self, number_of_samples_per_channel=NUM_SAMPLES_UNSET,
 
         This read method is dynamic, and is capable of inferring an appropriate
         return type based on these factors:
+
         - The channel type of the task.
         - The number of channels to read.
         - The number of samples per channel.
@@ -768,6 +770,117 @@ def _read_power(
                     for v, i in zip(voltages, currents)
                 ][:samples_read]
 
+    @requires_feature(WAVEFORM_SUPPORT)
+    def read_waveform(self, number_of_samples_per_channel=READ_ALL_AVAILABLE,
+             timeout=10.0):
+        """
+        Reads samples from the task or virtual channels you specify, and returns them as waveforms.
+
+        This read method is dynamic, and is capable of inferring an appropriate
+        return type based on these factors:
+
+        - The channel type of the task.
+        - The number of channels to read.
+        - The number of samples per channel.
+
+        The data type of the samples returned is independently determined by
+        the channel type of the task.
+
+        If you do not set the number of samples per channel, this method
+        reads all available data for each channel.
+
+        Args:
+            number_of_samples_per_channel (Optional[int]): Specifies the
+                number of samples to read. If this input is not set,
+                it defaults to nidaqmx.constants.READ_ALL_AVAILABLE.
+
+                If this input is nidaqmx.constants.READ_ALL_AVAILABLE, 
+                NI-DAQmx determines how many samples
+                to read based on if the task acquires samples
+                continuously or acquires a finite number of samples.
+
+                If the task acquires samples continuously and you set
+                this input to nidaqmx.constants.READ_ALL_AVAILABLE, this
+                method reads all the samples currently available in the
+                buffer.
+
+                If the task acquires a finite number of samples and you
+                set this input to nidaqmx.constants.READ_ALL_AVAILABLE,
+                the method waits for the task to acquire all requested
+                samples, then reads those samples. If you set the
+                "read_all_avail_samp" property to True, the method reads
+                the samples currently available in the buffer and does
+                not wait for the task to acquire all requested samples.
+            timeout (Optional[float]): Specifies the amount of time in
+                seconds to wait for samples to become available. If the
+                time elapses, the method returns an error and any
+                samples read before the timeout elapsed. The default
+                timeout is 10 seconds. If you set timeout to
+                nidaqmx.constants.WAIT_INFINITELY, the method waits
+                indefinitely. If you set timeout to 0, the method tries
+                once to read the requested samples and returns an error
+                if it is unable to.
+        Returns:
+            dynamic:
+
+            The samples requested in the form of a waveform (for a single channel)
+            or a list of waveforms (for multiple channels).
+            See method docstring for more info.
+
+            NI-DAQmx scales the data to the units of the measurement,
+            including any custom scaling you apply to the channels. Use a
+            DAQmx Create Channel method to specify these units.
+
+        Example:
+            >>> task = Task()
+            >>> task.ai_channels.add_ai_voltage_chan('Dev1/ai0')
+            >>> data = task.read_waveform()
+            >>> type(data)
+            <type 'AnalogWaveform'>
+        """
+        channels_to_read = self.in_stream.channels_to_read
+        number_of_channels = len(channels_to_read.channel_names)
+        read_chan_type = channels_to_read.chan_type
+
+        number_of_samples_per_channel = self._calculate_num_samps_per_chan(
+            number_of_samples_per_channel)
+
+        if read_chan_type == ChannelType.ANALOG_INPUT:
+            if number_of_channels == 1:
+                waveform = AnalogWaveform(number_of_samples_per_channel)
+                self._interpreter.read_analog_waveform(
+                    self._handle,
+                    number_of_samples_per_channel,
+                    timeout,
+                    waveform,
+                    self._in_stream.waveform_attribute_mode,
+                )
+                return waveform
+            else:
+                waveforms = [
+                    AnalogWaveform(number_of_samples_per_channel)
+                    for _ in range(number_of_channels)
+                ]
+                self._interpreter.read_analog_waveforms(
+                    self._handle,
+                    number_of_samples_per_channel,
+                    timeout,
+                    waveforms,
+                    self._in_stream.waveform_attribute_mode,
+                )
+                return waveforms
+
+        elif (read_chan_type == ChannelType.DIGITAL_INPUT or
+                read_chan_type == ChannelType.DIGITAL_OUTPUT):
+            raise NotImplementedError("Digital input/output reading is not implemented yet.")
+
+        else:
+            raise DaqError(
+                'Read failed, because there are no channels in this task from '
+                'which data can be read.',
+                DAQmxErrors.READ_NO_INPUT_CHANS_IN_TASK,
+                task_name=self.name)
+
     def register_done_event(self, callback_method):
         """
         Registers a callback function to receive an event when a task stops due
diff --git a/pyproject.toml b/pyproject.toml
@@ -186,6 +186,7 @@ reportArgumentType = false
 reportAttributeAccessIssue = false
 reportInvalidTypeForm = false
 reportOperatorIssue = false
+reportOptionalIterable = false
 reportOptionalMemberAccess = false
 reportReturnType = false
 
diff --git a/src/handwritten/stream_readers.py b/src/handwritten/stream_readers.py
@@ -303,7 +303,7 @@ def read_waveform(
                 number_of_samples_per_channel))
 
         if waveform is None:
-            waveform = AnalogWaveform(raw_data=numpy.zeros(number_of_samples_per_channel, dtype=numpy.float64))
+            waveform = AnalogWaveform(number_of_samples_per_channel)
         elif number_of_samples_per_channel > waveform.sample_count:
             # TODO: AB#3228924 - if allowed by the caller, increase the sample count of the waveform
             raise DaqError(
@@ -519,7 +519,7 @@ def read_waveforms(
 
         if waveforms is None:
             waveforms = [
-                AnalogWaveform(raw_data=numpy.zeros(number_of_samples_per_channel, dtype=numpy.float64))
+                AnalogWaveform(number_of_samples_per_channel)
                 for _ in range(number_of_channels)
             ]
         else:
diff --git a/src/handwritten/task/_task.py b/src/handwritten/task/_task.py
@@ -3,10 +3,11 @@
 import threading
 import warnings
 from enum import Enum
-from typing import List, Tuple, Union
 
 import numpy
+from nitypes.waveform import AnalogWaveform
 from nidaqmx import utils
+from nidaqmx._feature_toggles import WAVEFORM_SUPPORT, requires_feature
 from nidaqmx.task.channels._channel import Channel
 from nidaqmx.task._export_signals import ExportSignals
 from nidaqmx.task._in_stream import InStream
@@ -516,6 +517,7 @@ def read(self, number_of_samples_per_channel=NUM_SAMPLES_UNSET,
 
         This read method is dynamic, and is capable of inferring an appropriate
         return type based on these factors:
+
         - The channel type of the task.
         - The number of channels to read.
         - The number of samples per channel.
@@ -768,6 +770,117 @@ def _read_power(
                     for v, i in zip(voltages, currents)
                 ][:samples_read]
 
+    @requires_feature(WAVEFORM_SUPPORT)
+    def read_waveform(self, number_of_samples_per_channel=READ_ALL_AVAILABLE,
+             timeout=10.0):
+        """
+        Reads samples from the task or virtual channels you specify, and returns them as waveforms.
+
+        This read method is dynamic, and is capable of inferring an appropriate
+        return type based on these factors:
+
+        - The channel type of the task.
+        - The number of channels to read.
+        - The number of samples per channel.
+
+        The data type of the samples returned is independently determined by
+        the channel type of the task.
+
+        If you do not set the number of samples per channel, this method
+        reads all available data for each channel.
+
+        Args:
+            number_of_samples_per_channel (Optional[int]): Specifies the
+                number of samples to read. If this input is not set,
+                it defaults to nidaqmx.constants.READ_ALL_AVAILABLE.
+
+                If this input is nidaqmx.constants.READ_ALL_AVAILABLE, 
+                NI-DAQmx determines how many samples
+                to read based on if the task acquires samples
+                continuously or acquires a finite number of samples.
+
+                If the task acquires samples continuously and you set
+                this input to nidaqmx.constants.READ_ALL_AVAILABLE, this
+                method reads all the samples currently available in the
+                buffer.
+
+                If the task acquires a finite number of samples and you
+                set this input to nidaqmx.constants.READ_ALL_AVAILABLE,
+                the method waits for the task to acquire all requested
+                samples, then reads those samples. If you set the
+                "read_all_avail_samp" property to True, the method reads
+                the samples currently available in the buffer and does
+                not wait for the task to acquire all requested samples.
+            timeout (Optional[float]): Specifies the amount of time in
+                seconds to wait for samples to become available. If the
+                time elapses, the method returns an error and any
+                samples read before the timeout elapsed. The default
+                timeout is 10 seconds. If you set timeout to
+                nidaqmx.constants.WAIT_INFINITELY, the method waits
+                indefinitely. If you set timeout to 0, the method tries
+                once to read the requested samples and returns an error
+                if it is unable to.
+        Returns:
+            dynamic:
+
+            The samples requested in the form of a waveform (for a single channel)
+            or a list of waveforms (for multiple channels).
+            See method docstring for more info.
+
+            NI-DAQmx scales the data to the units of the measurement,
+            including any custom scaling you apply to the channels. Use a
+            DAQmx Create Channel method to specify these units.
+
+        Example:
+            >>> task = Task()
+            >>> task.ai_channels.add_ai_voltage_chan('Dev1/ai0')
+            >>> data = task.read_waveform()
+            >>> type(data)
+            <type 'AnalogWaveform'>
+        """
+        channels_to_read = self.in_stream.channels_to_read
+        number_of_channels = len(channels_to_read.channel_names)
+        read_chan_type = channels_to_read.chan_type
+
+        number_of_samples_per_channel = self._calculate_num_samps_per_chan(
+            number_of_samples_per_channel)
+
+        if read_chan_type == ChannelType.ANALOG_INPUT:
+            if number_of_channels == 1:
+                waveform = AnalogWaveform(number_of_samples_per_channel)
+                self._interpreter.read_analog_waveform(
+                    self._handle,
+                    number_of_samples_per_channel,
+                    timeout,
+                    waveform,
+                    self._in_stream.waveform_attribute_mode,
+                )
+                return waveform
+            else:
+                waveforms = [
+                    AnalogWaveform(number_of_samples_per_channel)
+                    for _ in range(number_of_channels)
+                ]
+                self._interpreter.read_analog_waveforms(
+                    self._handle,
+                    number_of_samples_per_channel,
+                    timeout,
+                    waveforms,
+                    self._in_stream.waveform_attribute_mode,
+                )
+                return waveforms
+
+        elif (read_chan_type == ChannelType.DIGITAL_INPUT or
+                read_chan_type == ChannelType.DIGITAL_OUTPUT):
+            raise NotImplementedError("Digital input/output reading is not implemented yet.")
+
+        else:
+            raise DaqError(
+                'Read failed, because there are no channels in this task from '
+                'which data can be read.',
+                DAQmxErrors.READ_NO_INPUT_CHANS_IN_TASK,
+                task_name=self.name)
+
     def register_done_event(self, callback_method):
         """
         Registers a callback function to receive an event when a task stops due
diff --git a/tests/component/test_stream_readers_ai.py b/tests/component/test_stream_readers_ai.py
diff --git a/tests/component/test_task_read_waveform_ai.py b/tests/component/test_task_read_waveform_ai.py
