configureCallback

Set callback function and trigger condition for communication with serial port device

Syntax

configureCallback(device,"terminator",callbackFcnHdl)

configureCallback(device,"byte",count,callbackFcnHdl)

configureCallback(device,"off")

Description

configureCallback(device,"terminator",callbackFcnHdl) sets the callback function referred to by the handle callbackFcnHdl to trigger whenever a terminator is available to be read from the specified serial port. The syntax sets the BytesAvailableFcnMode property of device to "terminator" and the BytesAvailableFcn property to callbackFcnHdl.

Set the terminator character using configureTerminator.

configureCallback(device,"byte",count,callbackFcnHdl) sets the function referred to by the handle callbackFcnHdl to trigger whenever a new count number of bytes are available to be read. The syntax sets the BytesAvailableFcnMode property of device to "byte", the BytesAvailableFcnCount property to count, and the BytesAvailableFcn property to callbackFcnHdl.

configureCallback(device,"off") turns off callbacks. The syntax sets the BytesAvailableFcnMode property of device to "off".

Examples

Set Serial Port Device Callback and Trigger to "terminator" Mode

Create a connection to a serial port device.

device = serialport("COM3",9600)

device = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
    NumBytesAvailable: 0

  Show all properties, functions

Suppose that you have a function FcnToCall that you want run when a terminator is available to be read. Set the input argument callbackFcnHndl to a handle to FcnToCall. Set the callback function to trigger when a terminator is available to be read.

callbackFcnHndl = @FcnToCall;
configureCallback(device,"terminator",callbackFcnHndl)

View the properties to confirm the change.

device.BytesAvailableFcnMode
device.BytesAvailableFcn

ans = 

    "terminator"


ans =

  function_handle with value:

    @FcnToCall

Turn the callback off.

configureCallback(device,"off")

Verify that the callback is off.

device.BytesAvailableFcnMode

ans = 

    "off"

Set Serial Port Device Callback and Trigger to "byte" Mode

Create a connection to a serial port device.

device = serialport("COM3",9600)

device = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
    NumBytesAvailable: 0

  Show all properties, functions

Set the callback to trigger each time 50 new bytes of data are available to be read.

configureCallback(device,"byte",50,@FcnToCall)

View the properties to confirm the change.

device.BytesAvailableFcnMode
device.BytesAvailableFcnCount
device.BytesAvailableFcn

ans = 

    "byte"


ans =

    50


ans =

  function_handle with value:

    @callbackFcn

Turn the callback off.

configureCallback(device,"off")

Verify that the callback is off.

device.BytesAvailableFcnMode

ans = 

    "off"

Read Data from Serial Port Device Using Callback Function

Create a connection to a serial port device.

device = serialport("COM3",9600)

device = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
    NumBytesAvailable: 0

  Show all properties, functions

Create a callback function that reads ASCII terminated string data and saves it to the UserData property of device.

function readSerialData(src,evt)
    data = readline(src);
    src.UserData = data;
end

Set the callback to trigger when a terminator is available to be read.

configureCallback(device,"terminator",@readSerialData)

Callback Function with Multiple Input Arguments

Suppose your callback function takes external input arguments in addition to the required srcand evt arguments. For instance, consider the following function that reads ASCII terminated string data, increments and multiplies it by the corresponding input arguments, and saves it to the UserData property of device.

function increaseSerialData(src,evt,addOffset,scaleFactor)
    data = (typecast((readline(src),"uint8") + addOffset) * scaleFactor
    src.UserData = data;
end

Create a connection to a serial port device.

device = serialport("COM3",9600)

device = 

  Serialport with properties:

                 Port: "COM3"
             BaudRate: 9600
    NumBytesAvailable: 0

  Show all properties, functions

Create a callback function that triggers when a terminator character is detected, indicating that data is available to be read from the serial device. To do this, create an anonymous function that takes in src and event as inputs and calls increaseSerialData with the designated input arguments. Set the input argument callbackFcnHndl to a handle to the anonymous function.

addOffset = 2;
scaleFactor = 3;
callbackFcnHdl = @(src, evt) increaseSerialData(src, evt, addOffset, scaleFactor);
configureCallback(device,"terminator",callbackFcnHdl)

Input Arguments

device — Serial port connection

serialport object

Serial port connection, specified as a serialport object.

Example: configureCallback(device,"byte",128,@FcnToCall) sets the FcnToCall callback to trigger each time 128 bytes of new data are available to be read from the serial port connection device.

count — Number of bytes of data to trigger callback

positive integer value

Number of bytes of available data to trigger the callback, specified as a positive integer value. Set the BytesAvailableFcnCount property using this argument.

Example: configureCallback(device,"byte",128,@FcnToCall) sets the function referred to by callbackFcnHdl equal to FcnToCall. FcnToCall is triggered each time 128 bytes of new data are available to be read.

Data Types: single | double | int8 | int16 | int32 | int64 | uint8 | uint16 | uint32 | uint64

callbackFcnHdl — Handle to the callback function to run when trigger condition is met

function handle

Handle to the callback function to run when trigger condition is met, specified as a function handle. The function handle can be a named function handle or an anonymous function with input arguments. configureCallback sets the BytesAvailableFcn property of the device to the function handle callbackFcnHdl. The function that the handle refers to runs when the trigger condition occurs.

The function must take src and evt as its first input arguments. src represents the source of the event, typically the device object, and evt contains event-specific data.

Example: configureCallback(device,"terminator",@FcnToCall) sets the callback function to the function referred by the handle @FcnToCall.

Data Types: function_handle

Version History

Introduced in R2019b