From Xojo Documentation

Revision as of 19:10, 3 September 2020 by THill (talk | contribs) (Text replacement - "{{Deprecated|" to "{{DeprecatedItem|")
You are currently browsing the old Xojo documentation site. Please visit the new Xojo documentation site!

Class (inherits from Object)

Serial controls are used to perform serial communications.

DataAvailable Error LineStateChanged

Baud DTR Parity
Bits DataCarrierDetect fa-lock-32.png RequestToSend
BytesAvailable fa-lock-32.png DataSetReady fa-lock-32.png RingIndicator fa-lock-32.png
BytesLeftToSend fa-lock-32.png DataTerminalReady SerialPort
CTS Handle fa-lock-32.png Stop
ClearToSend fa-lock-32.png LastErrorCode XON

ClearBreak LineChangeNotification Reset
Close LookAhead SetBreak
EndOfFile Open Write
Flush Poll XmitWait
LeaveDTROnClose Read
LineChangeNotification ReadAll

Class Constants

Baud Rates

To set the Baud rate, assign the desired class constant to the Baud property. To get the baud rate, compare the value of the Baud property to the constants in this table.

Baud Rate Value Constant
300 0 Baud300
600 1 Baud600
1200 2 Baud1200
1800 3 Baud1800
2400 4 Baud2400
3600 5 Baud3600
4800 6 Baud4800
7200 7 Baud7200
9600 8 Baud9600
14400 9 Baud14400
19200 10 Baud19200
28800 11 Baud28800
38400 12 Baud38400
57600 13 Baud57600
115200 14 Baud115200
230400 15 Baud230400

Setting nonstandard baud rates is supported only on Windows and macOS and above. On macOS, the system supports arbitrary baud rates by passing the request along to the driver. If the driver supports the passed baud rate, then it is set (or approximated).

On Linux, some non-standard baud rates are possible to achieve by using the Setserial system call and setting your baud rate to a special value.


The following class constants can be used to determine line state changes.

Class Constants Description
LineCTS Clear to send.
LineDCD Data carrier detect.
LineDSR Data set ready.
LineDTR Data Terminal Ready
LineRTS Request to Send
LineRI Ring Indicator


The following class constants can be used to get or set the parity using the Parity property.

Class Constant Description
ParityNone No parity.
ParityOdd Odd parity.
ParityEven Even parity.

Stop Bits

The following class constants can be used to get or set the number of stop bits using the Stop property.

Class Constant Description
StopBits1 1 stop bit.
StopBits15 1.5 stop bits.
StopBits2 2 stop bits.


The following class constants can be use to set the number of bits using the Bits property.

Class Constant Description
Bits5 5 bits.
Bits6 6 bits.
Bits7 7 bits.
Bits8 8 bits.

Error Codes

The following class constants can be used to test the LastErrorCode value.

Class Constant Description
NoError No error code.
AccessDenied Access denied.
PortNotFound Port not found.
InvalidOptions Invalid options.
BreakCondition Hardware detected a break condition. Usually due to a signal rate mismatch.
FramingError Hardware detected a framing error. Occurs when the designated "start" and "stop" bits are not valid.

Refer to this link for additional information on each error:


The Serial class implements the Readable and Writeable class interfaces.


Changing property values does not automatically change the state of the hardware, you must call Reset or re-Open the connection in order for the change to take effect.

The Serial control can be instantiated via code since it is not a subclass of Control. This allows you to easily write code that does communications without adding the control to a window.

The Serial control can be used to communicate via multiple serial ports at once. You can use the properties of the System module to determine the number of serial ports on the computer and get an array of those ports. You should create an interface to allow the end user to choose the desired port, since serial ports are different on different machines and platforms.

When data is received by a serial port connection, the DataAvailable event handler will automatically execute. In this event handler, you would then use the Read or ReadAll functions to access the data in the serial port buffer. These functions remove the data from the serial port buffer as they return the data. If you need to read the data from the serial port buffer without removing it from the buffer, use the LookAhead property. This buffer will use as much memory as it needs from the memory available so there is no need for it to be resized.

Because the Write method is handled asynchronously, you may need to use the XmitWait method to force your app to wait until it has finished sending the data out the serial port.

On macOS and Linux, your app gets exclusive rights to the serial port when opening it. This means that another application cannot also open the serial port after your app has opened it, unless the user is running as root.

Communicating with USB Devices

Most USB devices have a chip in them that makes them appear as a serial device. Typically this chip is a FTDI chip. If the device has this chip, you can communicate with the device with the SerialPort class. If that does not work for you, the Monkeybread plug-in has USB support for a handful of specific types of devices.


The following code opens the serial port. It assumes that the Serial1 control has been added to a window.

If Serial1.Open Then
MsgBox("The serial port is open.")
MsgBox("The serial port could not be opened.")
End if

When the serial device sends data back to the Serial control that is open, the Serial control’s DataAvailable event fires. The data is transferred into a memory buffer. In the DataAvailable event handler, you use the Read or ReadAll methods to get some or all of the data from the buffer. Choose the Read method when you want to get a specific number of bytes (characters) from the buffer. Choose the ReadAll method to get all of the data in the buffer. In both cases, the data returned from the buffer is removed from the buffer to make room for more incoming data. If you need to examine the data in the buffer without removing it from the buffer, you can call the LookAhead method.

This example appends any incoming data to a TextArea.

Sub DataAvailable()
TextArea1.Text = TextArea1.Text + Me.ReadAll
End Sub

Both the Read and ReadAll methods of the Serial class take an optional parameter that enables you to specify the encoding. Use the Encodings module to get the desired encoding and pass it as a parameter. For example, the code above has been modified to specify that the incoming text uses the ANSI encoding, a standard on Windows:

Sub DataAvailable()
TextArea1.Text = TextArea1.Text + Me.ReadAll(Encodings.WindowsANSI)
End Sub

You can send data to the serial device at any time as long as you have opened the serial port with the Serial control’s Open method. You send data using the Serial control's Write method. The data you wish to send must be a string, as the Write method accepts only a string as a parameter.

If Serial1.Open Then
MsgBox("The serial port could not be opened.")
End If

The Write method is performed asynchronously. This means that the next line of code following the Write method can already be executing before all the data has actually been sent to the serial device. If you need your code to wait for all data to be sent to the serial device before continuing, call the Serial control's XmitWait method immediately following a call to the Write method.

The following code directs the Serial control to communicate using Serial port zero (Modem port).

Serial1.SerialPort = System.SerialPort(0)

Watching for Line State Changes

You detect line state changes by passing an array or a ParamArray of line states that you want to watch. In the first instance, you can do it like this. The objects cCTS, cDTD, and so forth are checkboxes that the user sets to indicate which lines to watch.

// Set up an array of the line states that
// you want to watch.
Dim watchThese(-1) As Integer
If cCTS.Value Then // checkbox for CTS..
End If
If cDCD.Value Then
End If
If cDSR.Value Then
End If
If cDTR.Value Then
End If
If cRTS.Value Then
End If
If cRI.Value Then
End If

// Set the lines that we want to watch. Note
// that calling this function will clear any lines
// that we were watching previously, it doesn't
// append.

To use a ParamArray, you simply pass the class constants for the line states you want to watch. You don't need to set up a real array.

Serial1.LineChangeNotification(Serial.LineRI, Serial.LineDTR, Serial.LineCTS)

See Also

SerialPort class; System module; Readable, Writeable class interfaces; GettingStarted:Serial Port Tutorial