Main Content

read

Read data acquired by hardware

Since R2020a

collapse all in page

Syntax

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

Description

example

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

scanData = read(d,span) reads a span of input scans from the DataAcquisition interface, and returns a timetable to scanData. You can specify span as a duration, a number of scans, or "all".

  • If the DataAcquisition is not running and has no acquired data, the DataAcquisition starts a foreground finite acquisition to read the requested number of scans. MATLAB is blocked until the acquisition and read are complete.

  • If the DataAcquisition is running when you call this function, it reads data already acquired, if necessary waiting until the specified number of scans are available. MATLAB is blocked until the acquisition and read are complete. This is typical when start is called to run a background acquisition prior to calling read.

  • If the DataAcquisition is not running but has acquired data from a previous run, it reads the specified number of scans or all the data, whichever is less.

[scanData,triggerTime] = read(___) performs the specified read, and returns a timetable to scanData and scan trigger time to triggerTime as a datetime.

example

scanData = read(___,"OutputFormat","Matrix") performs the specified read, and returns an M-by-N matrix of doubles to scanData, where M is the number of scans and N is the number of input channels. Each column contains the data from one channel.

[scanData,timeStamp,triggerTime] = read(___,"OutputFormat","Matrix") performs the specified read and returns the scan timestamps to timeStamp, as an M-by-1 vector of doubles representing the relative time in seconds after the first scan. The rows of the timeStamp vector correspond to the rows of the scanData matrix. The scan trigger time is returned to triggerTime as a datenum double.

Examples

collapse all

Without specifying a duration or number of scans, the read function acquires a single on-demand scan on all channels.

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

If there is no data available to be read from the device, the read function initiates a foreground acquisition, blocking MATLAB until complete.

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 on 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 on 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

You can also read the data into arrays of double values. Five scans on two channels results in a 5-by-2 matrix, with a column for each channel.

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

When a background acquisition is initiated with the start function, use read to import the data.

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.
scanData = read(d,"all")
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

Input Arguments

collapse all

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

Example: d = daq()

Length of read operation, specified as a duration or double. If this is a duration type, it specifies the time duration of acquisition; if a double, it specifies the number of scans.

Example: seconds(5)

Data Types: double | duration

Output Arguments

collapse all

Input scan data from the device, returned as a timetable or matrix of doubles, depending on the OutputFormat setting.

The time stamp 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.

Time that acquisition began, 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.

Times of scan acquisitions, returned as a matrix of doubles. Each value represents relative time in seconds after the first scan. This argument is returned only when OutputFormat is specified as "Matrix".

Version History

Introduced in R2020a

See Also

Functions