External Interfaces/API

Configuring and Returning 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

Once the serial port object is created, you can 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, then 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
  

You can 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, you supply the property name to get.

• get(s,'OutputBufferSize')
  ans =
     512
  

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

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

You can also 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, you can 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. Refer to Property Reference for information about when a property is configurable.

Specifying Property Names

Serial port property names are presented using mixed case. While this makes property names easier to read, you can 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 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, then 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 will have no effect on your serial port application.

If a property has a finite set of string values, then 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.

The Serial Port Session

Creating a Serial Port Object