nidaqmx.task

class nidaqmx.task.Task(new_task_name='', *, grpc_options=None)[source]

Bases: object

Represents a DAQmx Task.

__eq__(other)[source]

Return self==value.

__hash__()[source]

Return hash(self).

__init__(new_task_name='', *, grpc_options=None)[source]

Creates a DAQmx task.

Parameters

  • new_task_name (Optional[str]) –

    Specifies the name to assign to the task.

    If you use this method in a loop and specify a name for the task, you must use the DAQmx Clear Task method within the loop after you are finished with the task. Otherwise, NI-DAQmx attempts to create multiple tasks with the same name, which results in an error.

  • grpc_options (Optional[GrpcSessionOptions]) – Specifies the gRPC session options.

__ne__(other)[source]

Return self!=value.

__repr__()[source]

Return repr(self).

__weakref__

list of weak references to the object (if defined)

add_global_channels(global_channels)[source]

Adds global virtual channels from MAX to the given task.

Parameters

global_channels (List[nidaqmx.system.storage.persisted_channel.PersistedChannel]) –

Specifies the channels to add to the task.

These channels must be valid channels available from MAX. If you pass an invalid channel, NI-DAQmx returns an error. This value is ignored if it is empty.

property ai_channels

nidaqmx._task_modules.ai_channel_collection.AIChannelCollection: Gets the collection of analog input channels for this task.

property ao_channels

nidaqmx._task_modules.ao_channel_collection.AOChannelCollection: Gets the collection of analog output channels for this task.

property channel_names

Indicates the names of all virtual channels in the task.

Type

List[str]

property channels

Specifies a channel object that represents the entire list of virtual channels in this task.

Type

nidaqmx._task_modules.channels.channel.Channel

property ci_channels

nidaqmx._task_modules.ci_channel_collection.CIChannelCollection: Gets the collection of counter input channels for this task.

close()[source]

Clears the task.

Before clearing, this method aborts the task, if necessary, and releases any resources the task reserved. You cannot use a task after you clear it unless you recreate the task.

If you create a DAQmx Task object within a loop, use this method within the loop after you are finished with the task to avoid allocating unnecessary memory.

property co_channels

nidaqmx._task_modules.co_channel_collection.COChannelCollection: Gets the collection of counter output channels for this task.

control(action)[source]

Alters the state of a task according to the action you specify.

Parameters

action (nidaqmx.constants.TaskMode) – Specifies how to alter the task state.

property devices

Indicates a list of Device objects representing all the devices in the task.

Type

List[nidaqmx.system.device.Device]

property di_channels

nidaqmx._task_modules.di_channel_collection.DIChannelCollection: Gets the collection of digital input channels for this task.

property do_channels

nidaqmx._task_modules.do_channel_collection.DOChannelCollection: Gets the collection of digital output channels for this task.

property export_signals

Gets the exported signal configurations for the task.

Type

nidaqmx._task_modules.export_signals.ExportSignals

property in_stream

Gets the read configurations for the task.

Type

nidaqmx._task_modules.in_stream.InStream

is_task_done()[source]

Queries the status of the task and indicates if it completed execution. Use this function to ensure that the specified operation is complete before you stop the task.

Returns

Indicates if the measurement or generation completed.

Return type

bool

property name

Indicates the name of the task.

Type

str

property number_of_channels

Indicates the number of virtual channels in the task.

Type

int

property number_of_devices

Indicates the number of devices in the task.

Type

int

property out_stream

Gets the write configurations for the task.

Type

nidaqmx._task_modules.out_stream.OutStream

read(number_of_samples_per_channel=<nidaqmx.task.UnsetNumSamplesSentinel object>, timeout=10.0)[source]

Reads samples from the task or virtual channels you specify.

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.

For digital input measurements, the data type of the samples returned is determined by the line grouping format of the digital lines. If the line grouping format is set to “one channel for all lines”, the data type of the samples returned is int. If the line grouping format is set to “one channel per line”, the data type of the samples returned is boolean.

If you do not set the number of samples per channel, this method assumes one sample was requested. This method then returns either a scalar (1 channel to read) or a list (N channels to read).

If you set the number of samples per channel to ANY value (even 1), this method assumes multiple samples were requested. This method then returns either a list (1 channel to read) or a list of lists (N channels to read).

Parameters

  • number_of_samples_per_channel (Optional[int]) –

    Specifies the number of samples to read. If this input is not set, assumes samples to read is 1. Conversely, if this input is set, assumes there are multiple samples to read.

    If you set this input to 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

The samples requested in the form of a scalar, a list, or a list of lists. 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.

Return type

dynamic

Example

>>> task = Task()
>>> task.ai_channels.add_ai_voltage_chan('Dev1/ai0:3')
>>> data = task.read()
>>> type(data)
<type 'list'>
>>> type(data[0])
<type 'float'>
register_done_event(callback_method)[source]

Registers a callback function to receive an event when a task stops due to an error or when a finite acquisition task or finite generation task completes execution. A Done event does not occur when a task is stopped explicitly, such as by calling DAQmx Stop Task.

Parameters

callback_method (function) –

Specifies the function that you want DAQmx to call when the event occurs. The function you pass in this parameter must have the following prototype:

>>> def callback(task_handle, status, callback_data):
>>>     return 0

Upon entry to the callback, the task_handle parameter contains the handle to the task on which the event occurred. The status parameter contains the status of the task when the event occurred. If the status value is negative, it indicates an error. If the status value is zero, it indicates no error. If the status value is positive, it indicates a warning. The callbackData parameter contains the value you passed in the callbackData parameter of this function.

Passing None for this parameter unregisters the event callback function.

register_every_n_samples_acquired_into_buffer_event(sample_interval, callback_method)[source]

Registers a callback function to receive an event when the specified number of samples is written from the device to the buffer. This function only works with devices that support buffered tasks.

When you stop a task explicitly any pending events are discarded. For example, if you call DAQmx Stop Task then you do not receive any pending events.

Parameters

  • sample_interval (int) – Specifies the number of samples after which each event should occur.

  • callback_method (function) –

    Specifies the function that you want DAQmx to call when the event occurs. The function you pass in this parameter must have the following prototype:

    >>> def callback(task_handle, every_n_samples_event_type,
>>>         number_of_samples, callback_data):
>>>     return 0

    Upon entry to the callback, the task_handle parameter contains the handle to the task on which the event occurred. The every_n_samples_event_type parameter contains the EveryNSamplesEventType.ACQUIRED_INTO_BUFFER value. The number_of_samples parameter contains the value you passed in the sample_interval parameter of this function. The callback_data parameter contains the value you passed in the callback_data parameter of this function.

    Passing None for this parameter unregisters the event callback function.

register_every_n_samples_transferred_from_buffer_event(sample_interval, callback_method)[source]

Registers a callback function to receive an event when the specified number of samples is written from the buffer to the device. This function only works with devices that support buffered tasks.

When you stop a task explicitly any pending events are discarded. For example, if you call DAQmx Stop Task then you do not receive any pending events.

Parameters

  • sample_interval (int) – Specifies the number of samples after which each event should occur.

  • callback_method (function) –

    Specifies the function that you want DAQmx to call when the event occurs. The function you pass in this parameter must have the following prototype:

    >>> def callback(task_handle, every_n_samples_event_type,
>>>         number_of_samples, callback_data):
>>>     return 0

    Upon entry to the callback, the task_handle parameter contains the handle to the task on which the event occurred. The every_n_samples_event_type parameter contains the EveryNSamplesEventType.TRANSFERRED_FROM_BUFFER value. The number_of_samples parameter contains the value you passed in the sample_interval parameter of this function. The callback_data parameter contains the value you passed in the callback_data parameter of this function.

    Passing None for this parameter unregisters the event callback function.

register_signal_event(signal_type, callback_method)[source]

Registers a callback function to receive an event when the specified hardware event occurs.

When you stop a task explicitly any pending events are discarded. For example, if you call DAQmx Stop Task then you do not receive any pending events.

Parameters

  • signal_type (nidaqmx.constants.Signal) – Specifies the type of signal for which you want to receive results.

  • callback_method (function) –

    Specifies the function that you want DAQmx to call when the event occurs. The function you pass in this parameter must have the following prototype:

    >>> def callback(task_handle, signal_type, callback_data):
>>>     return 0

    Upon entry to the callback, the task_handle parameter contains the handle to the task on which the event occurred. The signal_type parameter contains the integer value you passed in the signal_type parameter of this function. The callback_data parameter contains the value you passed in the callback_data parameter of this function.

    Passing None for this parameter unregisters the event callback function.

save(save_as='', author='', overwrite_existing_task=False, allow_interactive_editing=True, allow_interactive_deletion=True)[source]

Saves this task and any local channels it contains to MAX.

This function does not save global channels. Use the DAQmx Save Global Channel function to save global channels.

Parameters

  • save_as (Optional[str]) – Is the name to save the task, global channel, or custom scale as. If you do not specify a value for this input, NI-DAQmx uses the name currently assigned to the task, global channel, or custom scale.

  • author (Optional[str]) – Is a name to store with the task, global channel, or custom scale.

  • overwrite_existing_task (Optional[bool]) – Specifies whether to overwrite a task of the same name if one is already saved in MAX. If this input is False and a task of the same name is already saved in MAX, this function returns an error.

  • allow_interactive_editing (Optional[bool]) – Specifies whether to allow the task, global channel, or custom scale to be edited in the DAQ Assistant. If allow_interactive_editing is True, the DAQ Assistant must support all task or global channel settings.

  • allow_interactive_deletion (Optional[bool]) – Specifies whether to allow the task, global channel, or custom scale to be deleted through MAX.

start()[source]

Transitions the task to the running state to begin the measurement or generation. Using this method is required for some applications and is optional for others.

If you do not use this method, a measurement task starts automatically when the DAQmx Read method runs. The autostart input of the DAQmx Write method determines if a generation task starts automatically when the DAQmx Write method runs.

If you do not use the DAQmx Start Task method and the DAQmx Stop Task method when you use the DAQmx Read method or the DAQmx Write method multiple times, such as in a loop, the task starts and stops repeatedly. Starting and stopping a task repeatedly reduces the performance of the application.

stop()[source]

Stops the task and returns it to the state the task was in before the DAQmx Start Task method ran or the DAQmx Write method ran with the autostart input set to TRUE.

If you do not use the DAQmx Start Task method and the DAQmx Stop Task method when you use the DAQmx Read method or the DAQmx Write method multiple times, such as in a loop, the task starts and stops repeatedly. Starting and stopping a task repeatedly reduces the performance of the application.

property timing

Gets the timing configurations for the task.

Type

nidaqmx._task_modules.timing.Timing

property triggers

Gets the trigger configurations for the task.

Type

nidaqmx._task_modules.triggers.Triggers

wait_until_done(timeout=10.0)[source]

Waits for the measurement or generation to complete.

Use this method to ensure that the specified operation is complete before you stop the task.

Parameters

timeout (Optional[float]) – Specifies the maximum amount of time in seconds to wait for the measurement or generation to complete. This method returns an error if the time elapses. The default is 10. If you set timeout (sec) to nidaqmx.WAIT_INFINITELY, the method waits indefinitely. If you set timeout (sec) to 0, the method checks once and returns an error if the measurement or generation is not done.

write(data, auto_start=<nidaqmx.task.UnsetAutoStartSentinel object>, timeout=10.0)[source]

Writes samples to the task or virtual channels you specify.

This write method is dynamic, and is capable of accepting the samples to write in the various forms for most operations:

  • Scalar: Single sample for 1 channel.

  • List/1D numpy.ndarray: Multiple samples for 1 channel or 1 sample for multiple channels.

  • List of lists/2D numpy.ndarray: Multiple samples for multiple channels.

The data type of the samples passed in must be appropriate for the channel type of the task.

For counter output pulse operations, this write method only accepts samples in these forms:

  • Scalar CtrFreq, CtrTime, CtrTick (from nidaqmx.types): Single sample for 1 channel.

  • List of CtrFreq, CtrTime, CtrTick (from nidaqmx.types): Multiple samples for 1 channel or 1 sample for multiple channels.

If the task uses on-demand timing, this method returns only after the device generates all samples. On-demand is the default timing type if you do not use the timing property on the task to configure a sample timing type. If the task uses any timing type other than on-demand, this method returns immediately and does not wait for the device to generate all samples. Your application must determine if the task is done to ensure that the device generated all samples.

Parameters

  • data (dynamic) –

    Contains the samples to write to the task.

    The data you write must be in the units of the generation, including any custom scales. Use the DAQmx Create Channel methods to specify these units.

  • auto_start (Optional[bool]) –

    Specifies if this method automatically starts the task if you did not explicitly start it with the DAQmx Start Task method.

    The default value of this parameter depends on whether you specify one sample or many samples to write to each channel. If one sample per channel was specified, the default value is True. If multiple samples per channel were specified, the default value is False.

  • timeout (Optional[float]) – Specifies the amount of time in seconds to wait for the method to write all samples. NI-DAQmx performs a timeout check only if the method must wait before it writes data. This method returns an error if the time elapses. 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 write the submitted samples. If the method could not write all the submitted samples, it returns an error and the number of samples successfully written.

Returns

Specifies the actual number of samples this method successfully wrote.

Return type

int