read

Read data acquired by hardware

Since R2020a

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.

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".

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

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

[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 if the OutputFormat is Matrix.

Note

• Foreground Acquisition (Synchronous read) : Call the read function to initiate foreground data acquisition. This action blocks the MATLAB in the foreground and acquires data.

• Background Acquisition (Asynchronous read) : Call the start function prior to the read function to initiate background data acquisition. 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.

Examples

Read Single Scan

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

Initiate Foreground Acquisition

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

Read Data from Background Acquisition

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

Read Continuous Data from Background Acquisition

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

Input Arguments

d — DataAcquisition interface

DataAcquisition object

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

Example: d = daq()

span — Length of read operation

duration | double | "all"

Length of the read operation, specified as a duration or double. Time duration of acquisition is specified as duration and number of scans is specified as double.

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 — Format of read operation output

"TimeTable" (default) | "Matrix"

Format of read operation output, specified as one of these:

• "TimeTable": The function returns only scanData and triggerTime when you specify this option.

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

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

Data Types: string

Output Arguments

scanData — Input scan data from device

timetable | matrix

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

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

triggerTime — Data acquisition start time

datetime | datenum double

Data acquisition start time, returned as a datetime if OutputFormat is 'Timetable' (default), or as a double if OutputFormat is 'Matrix'. This information is also available as a datetime value in the timetable property scanData.Properties.CustomProperties.TriggerTime.

timeStamp — Relative timestamps of data acquisition

double

Relative timestamps of data acquisition, returned as an M-by-1 vector of doubles 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