Log Information to Disk

Analog Input Logging Properties

While an analog input object is running, you can log this information to a disk file:

  • Acquired data

  • Event information

  • Device object and channel information

  • Hardware information

Logging information to disk provides a permanent record of your data acquisition session, and is an easy way to debug your application.

As shown below, you can think of the logged information as a stream of data and events.

The properties associated with logging information to a disk file are as follows:

Property Name

Description

LogFileName

Specify the name of the disk file to which information is logged.

Logging

Indicate if data is being logged.

LoggingMode

Specify the destination for acquired data.

LogToDiskMode

Specify whether data, device object information, and hardware information is saved to one disk file or to multiple disk files.

You can initiate logging by setting LoggingMode to Disk or Disk&Memory. A new log file is created each time you issue the start function, and each different analog input object must log information to a separate log file. Writing to disk is performed as soon as possible after the current data block is filled.

You can choose whether a log file is overwritten or if multiple log files are created with the LogToDiskMode property. If LogToDiskMode is Overwrite, the log file is overwritten. If LogToDiskMode is Index, new log files are created, each with an indexed name based on the value of LogFileName.

Specify a Filename

You specify the name of the log file with the LogFileName property. You can specify any value for LogFileName, including a directory path, provided the filename is supported by your operating system. Additionally, if LogToDiskMode is Index, then the log filename also follows these rules:

  • Indexed log filenames are identified by a number. This number precedes the filename extension and increments by one for successive log files.

  • If no number is specified as part of the initial log filename, then the first log file does not have a number associated with it. For example, if LogFileName is myfile.daq, then myfile.daq is the name of the first log file, myfile01.daq is the name of the second log file, and so on.

  • LogFileName is updated after the log file is written (after the stop event occurs).

  • If the specified log filename already exists, then the existing file is overwritten.

Retrieve Logged Information

You retrieve logged information with the daqread function. You can retrieve any part of the information stored in a log file with one call to daqread. However, you will probably use daqread in one of these two ways:

  • Retrieving data and time information

  • Retrieving event, device object, channel, and hardware information

Retrieve Data and Time Information

You can characterize logged data by the sample number or the time the sample was acquired. To retrieve data and time information, you use the syntax shown below:

[data,time,abstime] = daqread('file','P1',V1,'P2',V2,...); 

where

  • data is the retrieved data. Data is returned as an m-by-n matrix where m is the number of samples and n is the number of channels.

  • time (optional) is the relative time associated with the retrieved data. Time is returned as an m-by-1 matrix where m is the number of samples.

  • abstime (optional) is the absolute time of the first trigger. Absolute time is returned as a clock vector.

  • file is the name of the log file.

  • 'P1',V2,'P2',V2,...(optional) are the property name/property value pairs, which allow you to select the amount of data to retrieve, among other things (see below).

daqread returns data and time information in the same format as getdata. If data from multiple triggers is retrieved, each trigger is separated by a NaN.

You select the amount of data returned and the format of that data with the properties given below.

Table 11-1. daqread Properties

Property Name

Description

Samples

Specify the sample range.

Time

Specify the relative time range.

Triggers

Specify the trigger range.

Channels

Specify the channel range. Channel names can be specified as a cell array.

DataFormat

Specify the data format as doubles or native.

TimeFormat

Specify the time format as vector or matrix.

The Samples, Time, and Triggers properties are mutually exclusive. If none of these three properties is specified, then all the data is returned.

Retrieving Event, Device Object, Channel, and Hardware Information

You can retrieve event, device object, channel, and hardware information, along with data and time information, using the syntax shown below.

[data,time,abstime,events,daqinfo] = 
daqread('file','P1',V1,'P2',V2,...); 

events is a structure containing event information associated with the logged data. The events retrieved depend on the value of the Samples, Time, or Triggers property. At a minimum, the trigger event associated with the selected data is returned. The entire event log is returned to events only if Samples, Time, or Triggers is not specified.

daqinfo is a structure that stores device object, channel, and hardware information in two fields: ObjInfo and HwInfo. ObjInfo is a structure containing property values for the device object and any channels it contains. The property values are returned in the same format as returned by get. HwInfo is a structure containing hardware information. The hardware information is identical to the information returned by daqhwinfo(obj).

Alternatively, you can return only object, channel, and hardware information with the command

daqinfo = daqread('file','info');

    Note   When you retrieve object information, the entire event log is returned to daqinfo.ObjInfo.EventLog regardless of the number of samples retrieved.

Log and Retrieve Information

This example illustrates how to log information to a disk file and then retrieve the logged information to the MATLAB® workspace using various calls to daqread.

A sound card is configured for stereo acquisition, data is logged to memory and to a disk file, four triggers are issued, and 2 seconds of data are collected for each trigger at a sampling rate of 8 kHz. You can run this example by typing daqdoc8_1 at the MATLAB Command Window.

  1. Create a device object — Create the analog input object ai for a sound card. The installed adaptors and hardware IDs are found with daqhwinfo.

    ai = analoginput('winsound');
    %ai = analoginput('nidaq','Dev1');
    %ai = analoginput('mcc',1);
  2. Add channels — Add two hardware channels to ai.

    ch = addchannel(ai,1:2);
    %ch = addchannel(ai,0:1); % For NI and MCC
  3. Configure property values — Define a 2 second acquisition for each trigger, set the trigger to repeat three times, and log information to the file file00.daq.

    duration = 2; % Two seconds of data for each trigger
    ai.SampleRate = 8000
    ActualRate = get(ai,'SampleRate');
    ai.SamplesPerTrigger = duration*ActualRate
    ai.TriggerRepeat = 3
    ai.LogFileName = 'file00.daq'
    ai.LoggingMode = Disk&Memory
  4. Acquire data — Start ai, wait for ai to stop running, and extract all the data stored in the log file as sample-time pairs.

    start(ai)
    % wait slightly longer than the duration of the acquisition times 
    % the number of triggers for the acquisition to complete 
    wait(ai, (ai.TriggerRepeat + 1) * duration + 1)
    [data,time] = daqread('file00.daq');

    Plot the data and label the figure axes.

    subplot(211), plot(data)
    title('Logging and Retrieving Data')
    xlabel('Samples'), ylabel('Signal (Volts)')
    subplot(212), plot(time,data)
    xlabel('Time (seconds)'), ylabel('Signal (Volts)')
  5. Clean up — When you no longer need ai, you should remove it from memory and from the MATLAB workspace.

    delete(ai)
    clear ai

Retrieve Data Based on Samples

You can retrieve data based on samples using the Samples property. To retrieve samples 1000 to 2000 for both sound card channels:

[data,time] = daqread('file00.daq','Samples',[1000 2000]);

Plot the data and label the figure axes.

subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time,data);
xlabel('Time (seconds)'), ylabel('Signal (Volts)')

Retrieve Data Based on Channels

You can retrieve data based on channels using the Channels property. To retrieve samples 1000 to 2000 for the second sound card channel:

[data,time] = daqread('file00.daq','Samples',[1000 2000], 
'Channels',2);

Plot the data and label the figure axes.

subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time,data);
xlabel('Time (seconds)'); ylabel('Signal (Volts)')

Alternatively, you can retrieve data for the second sound card channel by specifying the channel name.

[data,time] = daqread('file00.daq','Samples',[1000 2000], 
'Channels',{'Right'});

Retrieve Data Based on Triggers

You can retrieve data based on triggers using the Triggers property. To retrieve all the data associated with the second and third triggers for both sound card channels:

[data,time] = daqread('file00.daq','Triggers',[2 3]);

Plot the data and label the figure axes.

subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time,data);
xlabel('Time (seconds)'), ylabel('Signal (Volts)')

Retrieve Data Based on Time

You can retrieve data based on time using the Time property. Time must be specified in seconds and Time=0 corresponds to the first logged sample. To retrieve the first 25% of the data acquired for the first trigger:

[data,time] = daqread('file00.daq','Time',[0 0.5]);

Plot the data and label the figure axes.

subplot(211), plot(data);
xlabel('Samples'), ylabel('Signal (Volts)')
subplot(212), plot(time, data);
xlabel('Time (seconds)'), ylabel('Signal (Volts)')

Retrieve Event, Object, Channel, and Hardware Information

You can retrieve event, object, channel, and hardware information by specifying the appropriate arguments to daqread. For example, to retrieve all event information, you must return all the logged data.

[data,time,abstime,events,info] = daqread('file00.daq'); 
{events.Type}
ans = 
'Start' 'Trigger' 'Trigger' 'Trigger' 'Trigger' 'Stop'

If you retrieve part of the data, then only the events associated with the requested data are returned.

[data,time,abstime,events,info] = daqread('file00.daq', 
'Trigger',[1 3]); 
{events.Type}
ans = 
'Trigger' 'Trigger' 'Trigger'

You can retrieve the entire event log as well as object and hardware information by including info as an input argument to daqread.

daqinfo = daqread('file00.daq','info')
daqinfo = 
    ObjInfo: [1x1 struct]
     HwInfo: [1x1 struct]

To return the event log information:

eventinfo = daqinfo.ObjInfo.EventLog
eventinfo = 
6x1 struct array with fields:
    Type
    Data
Was this topic helpful?