read

R2026b

Read data acquired by hardware

collapse all in page

Syntax

scanData = read(d)
scanData = read(d,span)
[scanData,triggerTime] = read(___)
scanData = read(___,OutputFormat=format)
[scanData,timeStamp,triggerTime] = read(___,OutputFormat="Matrix")

Description

scanData = read(d) reads a single input scan from all input channels on the DataAcquisition object d, and returns the scan data as a timetable.

example

scanData = read(d,span) reads a span of input scans from the DataAcquisition object d. You can specify span as a duration, number of scans, or "all". When you read a span of input scans, counter inputs are reset to the initial value.

[scanData,triggerTime] = read(___) reads acquired scans, and returns the scan data as a timetable and the scan trigger time as a datetime.

example

scanData = read(___,OutputFormat=format) sets the format of the returned data as a matrix or a timetable. The default format is timetable.

example

[scanData,timeStamp,triggerTime] = read(___,OutputFormat="Matrix") reads acquired scans, and returns the scan data, timestamps, and trigger time as a matrix. The function returns timestamps as the second output argument only when you set the OutputFormat to "Matrix".

Note

The read operation occurs synchronously (in the foreground) or asynchronously (in the background).

  • Foreground acquisition (synchronous read) — To initiate foreground data acquisition, call the read function. This action acquires data while blocking interaction with MATLAB® until the read operation completes.

  • Background acquisition (asynchronous read) — To initiate background data acquisition, call the start function before calling the read function. The start function triggers the acquisition in the background and fills an internal buffer asynchronously. The read function, which you invoke later, acquires the specified range of data from this internal buffer. You can read any data remaining in the internal buffer even if you stop the acquisition.

example

Examples

collapse all

Use the read function to acquire a single on-demand scan of all channels by specifying only the DataAcquisition object.

d = daq("ni")
addinput(d,"Dev1",1,"Voltage"); % add more channels as needed
scanData = read(d)
data =

  timetable

    Time     Dev1_ai1
    _____    ________

    0 sec    -1.9525

Create a DataAcquisition object and add two input channels.

d = daq("ni");
ch = addinput(d,"Dev1",1:2,"Voltage")
ch = 

    Index    Type    Device    Channel    Measurement Type          Range              Name   
    _____    ____    ______    _______    ________________    __________________    __________

      1      "ai"    "Dev1"     "ai1"     "Voltage (Diff)"    "-10 to +10 Volts"    "Dev1_ai1"
      2      "ai"    "Dev1"     "ai2"     "Voltage (Diff)"    "-10 to +10 Volts"    "Dev1_ai2"

Read five scans of data from all channels.

scanData = read(d,5)
scanData =

  5×2 timetable

      Time       Dev1_ai1    Dev1_ai2
    _________    ________    ________

    0 sec         0.1621     0.62579 
    0.001 sec    0.42124     0.56955 
    0.002 sec    0.51069     0.56002 
    0.003 sec    0.54193     0.56166 
    0.004 sec    0.55377     0.56396

Read 5 milliseconds of data from all channels.

d.Rate = 1000;
scanData = read(d,seconds(0.005))
scanData =

  5×2 timetable

      Time       Dev1_ai1    Dev1_ai2
    _________    ________    ________

    0 sec         0.2259     0.33278 
    0.001 sec    0.28871     0.31699 
    0.002 sec     0.3068     0.31633 
    0.003 sec     0.3137     0.31929 
    0.004 sec    0.31732     0.32028

Query the DataAcquisition object for trigger time while reading the scanned data.

[scanData triggerTime] = read(d,5)
scanData =

  5×2 timetable

      Time       Dev1_ai1    Dev1_ai2
    _________    ________    ________

    0 sec         0.1621     0.62579 
    0.001 sec    0.42124     0.56955 
    0.002 sec    0.51069     0.56002 
    0.003 sec    0.54193     0.56166 
    0.004 sec    0.55377     0.56396

triggerTime = 

  datetime

   22-May-2024 12:22:35.899

Read the data into arrays of double values. In this example, when you read data acquired from five scans on two channels, the function returns a 5-by-2 matrix. The number of columns corresponds to the number of channels read.

scanData = read(d,5,OutputFormat="Matrix")
scanData =

    0.0424    0.0644
    0.0572    0.0621
    0.0605    0.0638
    0.0618    0.0641
    0.0631    0.0648

Create a DataAcquisition object, add an input channel, and start background acquisition of data using the start function.

d = daq("ni");
ch = addinput(d,"Dev1",1:2,"Voltage")
start(d,"NumScans",5)
Background operation has started.
Background operation will stop after 0.005 s.
To read acquired scans, use read.

Use the read function to import data.

scanData = read(d,"all",OutputFormat="Timetable")
scanData =

  5×2 timetable

      Time       Dev1_ai1    Dev1_ai2
    _________    ________    ________

    0 sec        0.012466    0.023977
    0.001 sec    0.019373    0.023319
    0.002 sec    0.021017     0.02299
    0.003 sec    0.021346     0.02299
    0.004 sec    0.022661    0.023648

Create a DataAcquisition object, add an input channel, and start background acquisition of data using the start function.

d = daq("ni");
ch = addinput(d,"Dev1",1,"Voltage")
start(d,"Duration",seconds(30))
Background operation has started.
Background operation will stop after 30 s.

Create matrices to store acquired data.

dataAll = [];
timestampsAll = [];

Read data in chunks of 1 second and continuously plot the acquired data.

chunkDuration = seconds(1);
while d.Running
    [data, timestamps] = read(d,chunkDuration,OutputFormat="Matrix");
    dataAll = [dataAll;data];
    timestampsAll = [timestampsAll;timestamps];
    plot(timestampsAll,dataAll)
    pause(0.5*seconds(chunkDuration))
end

dynamically updating plot with acquired data

Input Arguments

collapse all

Data acquisition interface, specified as a DataAcquisition object created using the daq function.

Example: d = daq()

Length of the read operation, specified as a duration or double. Specify the time duration of acquisition as a duration value, and the number of scans as a double value.

During background acquisition, specify "all" to acquire all the data in the DataAcquisition object buffer.

Example: read(dObj,seconds(5))

Data Types: double | duration

Format of read operation output, specified as one of:

  • "Timetable": The function returns only scanData and triggerTime when you specify this option, as timetable and datetime values, respectively.

  • "Matrix": The function returns scanData, timeStamp, and triggerTime as matrices when you specify this option.

Example: read(dObj,10,OutputFormat="Matrix")

Data Types: string

Output Arguments

collapse all

Input scan data from the device, returned as a timetable or M-by-N double matrix, depending on the OutputFormat setting. When scanData is a matrix, M is the number of scans, and N is the number of input channels. Each column contains the data from one channel.

The timetable stores the timestamp for each scan as a duration value relative to the trigger time. You can also access the scan trigger time as a datetime value in the Properties.CustomProperties.TriggerTime property of the returned timetable variable, scanData.

Data acquisition start time, returned as a datetime if OutputFormat is "Timetable" (default), or as a double if OutputFormat is "Matrix". The double value represents the date in the format returned by datenum. This information is also available as a datetime value in the Properties.CustomProperties.TriggerTime property of the returned timetable variable, scanData.

Relative timestamps of data acquisition, returned as an M-by-1 double vector where M is the number of scans. Each value represents relative time in seconds after the first scan. The function returns the timestamps in the second output argument only when you set OutputFormat to "Matrix".

Version History

Introduced in R2020a

See Also

Functions

Topics