Concepts
Describe, then run
Everything that describes a task is a frozen dataclass: it is checked when you create it (a ValueError says
what is wrong, before any driver call), it can be compared, stored, shared between threads and written in a
configuration file.
What |
Objects |
|---|---|
Channels |
|
Timing |
|
Start trigger |
|
Whole task |
|
A typed task is built from a TaskConfig. One class per kind of task: AnalogInputTask,
AnalogOutputTask, CounterInputTask, CounterOutputTask, DigitalTask. Each has the verbs that make
sense for it (read_analog, write_analog, write_levels, read_counter, read_digital,
write_digital) and all share start, stop and close. A task is also a context manager that closes
itself. To change a setting, close the task and build another one: a configuration never changes.
What comes back
read_analog returns a float64 array shaped (channels, samples), always 2D, whatever the number of
channels and samples (the driver itself returns a float, a list or a list of lists depending on the case).
read_counter does the same for counters and read_digital returns booleans.
Errors
Wrong values in a description are a
ValueErrorraised when you create it, or when you pass the wrong data to a task (for instance data for two channels on a one-channel task).Anything the driver refuses is a
nidaqmx.DaqError, with itserror_code. A read that waits too long is anidaqmx.DaqReadError(code -200284). There is noIOError.Without the NI-DAQmx driver,
NIDAQSystemlists no device, and creating a task raisesnidaqmx.errors.DaqNotFoundError.
Hardware discovery
NIDAQSystem tells what the computer’s NI hardware offers: devices, channels by kind, terminals, voltage ranges,
maximum rates, whether a start trigger is available. It asks the driver once and remembers the answer until you call
refresh(). It returns plain strings, numbers and tuples, so nothing of the driver leaks out.
Clocks and triggers
A task with a sample clock takes the clock in ClockSettings. source is a terminal: empty means the onboard
clock, /Dev2/PFI0 an external signal, and counter_output_terminal('Dev2/ctr1') the pulses of a counter output
(see the counter_rate example). A digital line such as Dev2/port0/line0 cannot be used as a trigger source
(the driver refuses it): use a PFI terminal.
Several tasks together
A task cannot mix subsystems (analog in, analog out, digital, counters). To acquire and generate at the same time,
use one task per subsystem and synchronise them with a shared clock or trigger (ClockSettings.source,
DigitalEdgeTrigger). TaskGroup(*tasks) runs them as one: start() starts the tasks in the order given (put
first those that wait for a signal, last the one that produces it), stop() and close() work in the reverse
order. If a task cannot start, the ones already started are stopped before the error is raised; close() closes
every task even if one fails, then raises the first error. A group is also a context manager that closes itself.
See the counter_rate example.
Callbacks and threads
A task tells its listeners what happens. Derive from TaskListener, reimplement what you need and register the
object with task.add_listener: on_samples_ready(data) is called for each block of n samples per channel when
the task was started with start(notify_every=n) (analog input only for now), and on_done(status) when the task
ends (status is 0 on success, else a driver error code). A closed task forgets its listeners.
The driver calls these from threads of its own, one per call, and does not guarantee any order between the two. Keep them short and hand the data over (a queue, an event); never touch a widget from them. The task keeps the callbacks alive for you: the driver only holds them weakly.
A ClockSettings without samples is a continuous acquisition: the task runs until it is stopped and you get
its data only through the listeners (read_analog raises an error, as there is no end to wait for).
In a PyMoDAQ plugin, do not touch the plugin from the listener: use QtTaskBridge
(pymodaq_plugins_daqmx.hardware.national_instruments.qt_task_bridge). It is a listener that relays each event, as a
Qt signal (samples_ready, done), to the thread that created it, which is the plugin thread when it is created
in a plugin method. Call its close() before closing the task.
Other kinds of task do not notify about samples for now.
Good to know
The driver does not always check ranges (a simulated PCIe-6363 accepts a ±1000 V range). The description objects only check that
min_val < max_val: useNIDAQSystem.ai_voltage_rangesif you need more.A finite task can be started again after
stop().read_analogwaits for the whole acquisition by default (duration plus 5 s); passtimeoutto change it.