MATLAB®

Getting Started with Serial I/O

Example: Getting Started

This example illustrates some basic serial port commands.

If you have a device connected to the serial port COM1 and configured for a baud rate of 4800, execute the following example.

s = serial('COM1');
set(s,'BaudRate',4800);
fopen(s);
fprintf(s,'*IDN?')
out = fscanf(s);
fclose(s)
delete(s)
clear s

The *IDN? command queries the device for identification information, which is returned to out. If your device does not support this command, or if it is connected to a different serial port, modify the previous example accordingly.

Note    *IDN? is one of the commands supported by the Standard Commands for Programmable Instruments (SCPI) language, which is used by many modern devices. Refer to your device documentation to see if it supports the SCPI language.

Back to Top

The Serial Port Session

This example describes the steps you use to perform any serial port task from beginning to end.

The serial port session comprises all the steps you are likely to take when communicating with a device connected to a serial port. These steps are:

1. Create a serial port object — Create a serial port object for a specific serial port using the serial creation function.

   Configure properties during object creation if necessary. In particular, you might want to configure properties associated with serial port communications such as the baud rate, the number of data bits, and so on.

2. Connect to the device — Connect the serial port object to the device using the fopen function.

   After the object is connected, alter the necessary device settings by configuring property values, read data, and write data.

3. Configure properties — To establish the desired serial port object behavior, assign values to properties using the set function or dot notation.

   In practice, you can configure many of the properties at any time including during, or just after, object creation. Conversely, depending on your device settings and the requirements of your serial port application, you might be able to accept the default property values and skip this step.

4. Write and read data — Write data to the device using the fprintf or fwrite function, and read data from the device using the fgetl, fgets, fread, fscanf, or readasync function.

   The serial port object behaves according to the previously configured or default property values.

5. Disconnect and clean up — When you no longer need the serial port object, disconnect it from the device using the fclose function, remove it from memory using the delete function, and remove it from the MATLAB^® workspace using the clear command.

The serial port session is reinforced in many of the serial port documentation examples. To see a basic example that uses the steps shown above, see Example: Getting Started.

Back to Top

Configuring and Returning Properties

This example describes how you display serial port property names and property values, and how you assign values to properties.

You establish the desired serial port object behavior by configuring property values. You can display or configure property values using the set function, the get function, or dot notation.

Displaying Property Names and Property Values

After you create the serial port object, use the set function to display all the configurable properties to the command line. Additionally, if a property has a finite set of string values, set also displays these values.

s = serial('COM1');
set(s)
    ByteOrder: [ {littleEndian} | bigEndian ] 
    BytesAvailableFcn
    BytesAvailableFcnCount
    BytesAvailableFcnMode: [ {terminator} | byte ]
    ErrorFcn
    InputBufferSize
    Name
    OutputBufferSize
    OutputEmptyFcn
    RecordDetail: [ {compact} | verbose ]
    RecordMode: [ {overwrite} | append | index ]
    RecordName
    Tag
    Timeout
    TimerFcn
    TimerPeriod
    UserData

    SERIAL specific properties:
    BaudRate
    BreakInterruptFcn
    DataBits
    DataTerminalReady: [ {on} | off ]
    FlowControl: [ {none} | hardware | software ]
    Parity: [ {none} | odd | even | mark | space ]
    PinStatusFcn
    Port
    ReadAsyncMode: [ {continuous} | manual ]
    RequestToSend: [ {on} | off ]
    StopBits
    Terminator

Use the get function to display one or more properties and their current values to the command line. To display all properties and their current values:

get(s)
    ByteOrder = littleEndian
    BytesAvailable = 0
    BytesAvailableFcn = 
    BytesAvailableFcnCount = 48
    BytesAvailableFcnMode = terminator
    BytesToOutput = 0
    ErrorFcn = 
    InputBufferSize = 512
    Name = Serial-COM1
    OutputBufferSize = 512
    OutputEmptyFcn = 
    RecordDetail = compact
    RecordMode = overwrite
    RecordName = record.txt
    RecordStatus = off
    Status = closed
    Tag = 
    Timeout = 10
    TimerFcn = 
    TimerPeriod = 1
    TransferStatus = idle
    Type = serial
    UserData = []
    ValuesReceived = 0
    ValuesSent = 0

    SERIAL specific properties:
    BaudRate = 9600
    BreakInterruptFcn = 
    DataBits = 8
    DataTerminalReady = on
    FlowControl = none
    Parity = none
    PinStatus = [1x1 struct]
    PinStatusFcn = 
    Port = COM1
    ReadAsyncMode = continuous
    RequestToSend = on
    StopBits = 1
    Terminator = LF

To display the current value for one property, supply the property name to get.

get(s,'OutputBufferSize')
ans =
   512

To display the current values for multiple properties, include the property names as elements of a cell array.

get(s,{'Parity','TransferStatus'})
ans = 
    'none'    'idle'

Use the dot notation to display a single property value.

s.Parity
ans =
none

Configuring Property Values

You can configure property values using the set function:

set(s,'BaudRate',4800);

or the dot notation:

s.BaudRate = 4800;

To configure values for multiple properties, supply multiple property name/property value pairs to set.

set(s,'DataBits',7,'Name','Test1-serial')

Note that you can configure only one property value at a time using the dot notation.

In practice, you can configure many of the properties at any time while the serial port object exists — including during object creation. However, some properties are not configurable while the object is connected to the device or when recording information to disk. For information about when a property is configurable, see Property Reference.

Specifying Property Names

Serial port property names are presented using mixed case. While this makes property names easier to read, use any case you want when specifying property names. Additionally, you need use only enough letters to identify the property name uniquely, so you can abbreviate most property names. For example, you can configure the BaudRate property any of these ways:

set(s,'BaudRate',4800)
set(s,'baudrate',4800)
set(s,'BAUD',4800)

When you include property names in an M-file, you should use the full property name. This practice can prevent problems with future releases of MATLAB software if a shortened name is no longer unique because of the addition of new properties.

Default Property Values

Whenever you do not explicitly define a value for a property, the default value is used. All configurable properties have default values.

Note    Your operating system provides default values for all serial port settings such as the baud rate. However, these settings are overridden by your MATLAB code and have no effect on your serial port application.

If a property has a finite set of string values, the default value is enclosed by {}. For example, the default value for the Parity property is none.

set(s,'Parity')
[ {none} | odd | even | mark | space ]

You can find the default value for any property in the property reference pages.

Back to Top

Overview of the Serial Port

Creating a Serial Port Object