Quantcast

Documentation Center

  • Trial Software
  • Product Updates

Events and Callbacks

Events and Callbacks Basics

You can enhance the power and flexibility of your analog output application by utilizing events. An event occurs at a particular time after a condition is met and might result in one or more callbacks.

While the analog output object is running, you can use events to display a message, display data, analyze data, and so on. Callbacks are controlled through callback properties and callback functions. All event types have an associated callback property. Callback functions are MATLAB® functions that you construct to suit your specific data acquisition needs.

You execute a callback when a particular event occurs by specifying the name of the callback function as the value for the associated callback property. Refer to Create and Execute Callback Functions to learn how to create callback functions. Note that daqcallback is the default value for some callback properties.

Event Types

The analog output event types and associated callback properties are described below.

Table 7-8. Analog Output Callback Properties

Event Type

Property Name

Run-time error

RuntimeErrorFcn

Samples output

SamplesOutputFcn

SamplesOutputFcnCount

Start

StartFcn

Stop

StopFcn

Timer

TimerFcn

TimerPeriod

Trigger

TriggerFcn

Run-time Error Event

A run-time error event is generated immediately after a run-time error occurs. This event executes the callback function specified for RuntimeErrorFcn. Additionally, a toolbox error message is automatically displayed to the MATLAB workspace. If an error occurs that is not explicitly handled by the toolbox, then the hardware-specific error message is displayed.

The default value for RunTimeErrorFcn is daqcallback, which displays the event type, the time the event occurred, the device object name, and the error message.

Run-time errors include hardware errors and timeouts. Run-time errors do not include configuration errors such as setting an invalid property value.

Samples Output Event

A samples output event is generated immediately after the number of samples specified by the SamplesOutputFcnCount property is output for each channel group member. This event executes the callback function specified for SamplesOutputFcn.

Start Event

A start event is generated immediately after the start function is issued. This event executes the callback function specified for StartFcn. When the callback function has finished executing, Running is automatically set to On and the device object and hardware device begin executing. The device object is not started if an error occurs while executing the callback function.

Stop Event

A stop event is generated immediately after the device object and hardware device stop running. This occurs when

  • The stop function is issued.

  • The requested number of samples is output.

  • A run-time error occurs.

A stop event executes the callback function specified for StopFcn. Under most circumstances, the callback function is not guaranteed to complete execution until sometime after the device object and hardware device stop running, and the Running property is set to Off.

Timer Event

A timer event is generated whenever the time specified by the TimerPeriod property passes. This event executes the callback function specified for TimerFcn. Time is measured relative to when the device object starts running.

Some timer events might not be processed if your system is significantly slowed or if the TimerPeriod value is too small. For example, a common application for timer events is to display data. However, because displaying data is a CPU-intensive task, some of these events might be dropped. To guarantee that events are not dropped, you can use the SamplesOutputFcn property.

Trigger Event

A trigger event is generated immediately after a trigger occurs. This event executes the callback function specified for TriggerFcn. Under most circumstances, the callback function is not guaranteed to complete execution until sometime after Sending is set to On.

Record and Retrieve Event Information

While the analog output object is running, certain information is automatically recorded in the EventLog property for some of the event types listed in the preceding section. EventLog is a structure that contains two fields: Type and Data. The Type field contains the event type. The Data field contains event-specific information. Events are recorded in the order in which they occur. The first EventLog entry reflects the first event recorded, the second EventLog entry reflects the second event recorded, and so on.

The event types recorded in EventLog for analog output objects, as well as the values for the Type and Data fields, are as follows:

Event Type

Type Field Value

Data Field Value

Run-time error

Error

AbsTime

RelSample

String

Start

Start

AbsTime

RelSample

Stop

Stop

AbsTime

RelSample

Trigger

Trigger

AbsTime

RelSample

Channel

Trigger

Samples output events and timer events are not stored in EventLog.

    Note   Unless a run-time error occurs, EventLog records a start event, a trigger event, and stop event for each data acquisition session.

The Data field values are described below.

AbsTime

AbsTime is used by all analog output events stored in EventLog to indicate the absolute time the event occurred. The absolute time is returned using the MATLAB clock format.

day-month-year hour:minute:second

Channel

Channel is used by the input overrange event and the trigger event. For the input overrange event, Channel indicates the index number of the input channel that experienced an overrange signal. For the trigger event, Channel indicates the index number for each input channel serving as a trigger source.

RelSample

RelSample is used by all events stored in EventLog to indicate the sample number that was output when the event occurred. RelSample is 0 for the start event and for the first trigger event regardless of the trigger type. RelSample is NaN for any event that occurs before the trigger executes.

String

String is used by the run-time error event to store the descriptive message that is generated when a run-time error occurs. This message is also displayed at the MATLAB Command Window.

Trigger

Trigger is used by the trigger event to indicate the trigger number. For example, if three trigger events occur, then Trigger is 3 for the third trigger event. The total number of triggers executed is given by the TriggersExecuted property.

Retrieve Event Information

    Note:   You cannot use the legacy interface on 64–bit MATLAB. See Session-Based Interface to acquire and generate data.

Suppose you want to examine the events logged for the example given by Queue Data with putdata. You can do this by accessing the EventLog property.

events = AO.EventLog
events = 
3x1 struct array with fields:
    Type
    Data

By examining the contents of the Type field, you can list the events that were recorded while AO was running.

{events.Type}
ans = 
    'Start'    'Trigger'    'Stop'

To display information about the trigger event, you must access the Data field, which stores the absolute time the trigger occurred and the number of samples output when the trigger occurred.

trigdata = events(2).Data
trigdata = 
      AbsTime: [1999 4 16 9 53 19.9508]
    RelSample: 0

You can display a summary of the event log with the showdaqevents function. For example, to display a summary of the second event contained by the structure events:

showdaqevents(events,2)
   2 Trigger             ( 09:53:19, 0 )

Alternatively, you can display event summary information via the Workspace browser by right-clicking the device object and selecting Explore > Show DAQ Events from the context menu.

Use Callback Properties and Callback Functions

Examples showing how to create callback functions and configure callback properties are given below.

Display Number of Samples Output

    Note:   You cannot use the legacy interface on 64–bit MATLAB. See Session-Based Interface to acquire and generate data.

This example illustrates how to generate samples output events. You can run this example by typing daqdoc6_4 at the MATLAB Command Window. The local callback function daqdoc6_4disp (not shown below) displays the number of events that were output from the engine whenever the samples output event occurred.

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

    AO = analogoutput('winsound');
    %AO = analogoutput('nidaq','Dev1');
    %AO = analogoutput('mcc',1);
  2. Add channels — Add two channels to AO.

    chans = addchannel(AO,1:2);
    %chans = addchannel(AO,0:1); % For NI and MCC
  3. Configure property values — Configure the trigger to repeat four times, specify daqdoc6_4disp as the callback function to execute whenever 8000 samples are output, generate data to be queued, and queue the data with one call to putdata.

    set(AO,'SampleRate',8000)
    ActualRate = get(AO,'SampleRate');
    set(AO,'RepeatOutput',4)
    set(AO,'SamplesOutputFcnCount',8000)
    freq = get(AO,'SamplesOutputFcnCount');
    set(AO,'SamplesOutputFcn',@daqdoc6_4disp)
    data = sin(linspace(0,2*pi*500,3*freq))';
    putdata(AO,[data data])
  4. Output data — Start AO. The wait function blocks the MATLAB Command Window, and waits for AO to stop running.

    start(AO)
    wait(AO,20)
    
  5. Clean up — When you no longer need AO, you should remove it from memory and from the MATLAB workspace.

    delete(AO)
    clear AO

Display EventLog Information

    Note:   You cannot use the legacy interface on 64–bit MATLAB. See Session-Based Interface to acquire and generate data.

This example illustrates how callback functions allow you to easily display information stored in the EventLog property. You can run this example by typing daqdoc6_5 at the MATLAB Command Window. The local callback function daqdoc6_5disp (not shown below) displays the absolute time and relative sample associated with the start, trigger, and stop events.

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

    AO = analogoutput('winsound');
    %AO = analogoutput('nidaq','Dev1');
    %AO = analogoutput('mcc',1);
  2. Add channels — Add one channel to AO.

    chan = addchannel(AO,1);
    %chan = addchannel(AO,0); % For NI and MCC
  3. Configure property values — Specify daqdoc6_5disp as the callback function to execute when the start, trigger, and stop events occur, generate data to be queued, and queue the data with one call to putdata.

    set(AO,'SampleRate',8000)
    ActualRate = get(AO,'SampleRate');
    set(AO,'StartFcn',@daqdoc6_5disp)
    set(AO,'TriggerFcn',@daqdoc6_5disp)
    set(AO,'StopFcn',@daqdoc6_5disp)
    data = sin(linspace(0,2*pi*500,ActualRate));
    data = [data data data];
    time = (length(data)/AO.SampleRate);
    putdata(AO,data')
  4. Output data — Start AO. The wait function blocks the MATLAB Command Window, and waits for AO to stop running.

    start(AO)
    wait(AO,5)
  5. Clean up — When you no longer need AO, you should remove it from memory and from the MATLAB workspace.

    delete(AO)
    clear AO
Was this topic helpful?