SerialConnection

Class (inherits from Object)

New in 2019r2

SerialConnection controls are used to perform serial communications with serial devices.

Events

Methods

ClearBreak	LeaveDTROnClose	RequestLineChangeNotification
Close	LookAhead	Reset
Connect	Poll	SetBreak
EndOfFile	Read	Write
Flush	ReadAll	XmitWait

Error Codes

The following class constants can be used with the Error event's exception parameter (e.ErrorNumber).

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:
http://en.wikipedia.org/wiki/Universal_asynchronous_receiver/transmitter

Interfaces

The SerialConnection class implements the Readable and Writeable class interfaces.

Notes

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 SerialConnection 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 SerialConnection control can be used to communicate via multiple serial devices at once. You can use the SerialDevice class to determine the number of serial devices on the computer and access them. You should create an interface to allow the end user to choose the desired device, since serial devices are different on different machines and platforms.

When data is received by a SerialConnection control, the DataReceived 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 buffer. These functions remove the data from the serial buffer as they return the data. If you need to read the data from the serial 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 device when opening the connection. This means that another application cannot also open a serial connection to that device 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 SerialDevice class. If that does not work for you, the Monkeybread plug-in has USB support for a handful of specific types of devices.

Examples

The following code opens a serial connection. It assumes that a SerialConnection control (named "SerialConnection1 in this example) has been added to a window. If the connection cannot be made, an IOException is raised:

Try
SerialConnection1.Connect
MessageBox("The serial connection is open.")
Catch error As IOException
MessageBox("The serial connection could not be opened.")
End Try

This example appends any incoming data to a TextArea.

Sub DataReceived()
TextArea1.Value = TextArea1.Value + Me.ReadAll
End Sub

Both the Read and ReadAll methods of the SerialConnection 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 DataReceived()
TextArea1.Value = TextArea1.Value + Me.ReadAll(Encodings.WindowsANSI)
End Sub

You can send data to the serial device at any time as long as you have opened a connection with the SerialConnection control’s Connect method. You send data using the SerialConnection 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.

Try
SerialConnection1.Connect
SerialConnection1.Write(TextArea1.Value)
Catch error As IOException
MessageBox("The serial connection could not be opened.")
End Try

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 SerialConnection control's XmitWait method immediately following a call to the Write method.

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

SerialConnection1.Device = SerialDevice.At(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.
Var watchThese(-1) As Integer
If cCTS.Value Then // checkbox for CTS..
watchThese.Add(SerialConnection.LineStates.ClearToSend)
End If
If cDCD.Value Then
watchThese.Add(SerialConnection.LineStates.DataCarrierDetect)
End If
If cDSR.Value Then
watchThese.Add(SerialConnection.LineStates.DataSetReady)
End If
If cDTR.Value Then
watchThese.Add(SerialConnection.LineStates.DataTerminalReady)
End If
If cRTS.Value Then
watchThese.Add(SerialConnection.LineStates.RequestToSend)
End If
If cRI.Value Then
watchThese.Add(SerialConnection.LneStates.RingIndicator)
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.
SerialConnection1.LineChangeNotification(watchThese)

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.

SerialConnection1.RequestLineChangeNotification(Serial.LineRI, Serial.LineDTR, Serial.LineCTS)

To use an enumeration, create an array of LineStates you wish to watch, then pass in the array:

Var states() As SerialConnection.LineStates
states.Add(SerialConnection.LineStates.RingIndicator)
states.Add(SerialConnection.LineStates.DataTerminalReady)
states.Add(SerialConnection.LineStates.ClearToSend)
SerialConnection1.RequestLineChangeNotification(states)