` method.
>
> | LineStates |
> |-------------------|
> | ClearToSend |
> | DataCarrierDetect |
> | DataSetReady |
> | DataTerminalReady |
> | RequestToSend |
> | RingIndicator |
SerialConnection.Parities
### Parities
> Specifies the type of parity to be used.
>
> | Parities |
> |----------|
> | Even |
> | Mark |
> | None |
> | Odd |
> | Space |
SerialConnection.StopBits
### StopBits
> Specifies the available stop bit values.
>
> | Stop Bits |
> |--------------|
> | None |
> | One |
> | OnePointFive |
> | Two |
## Property descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Baud
**Baud** As `Integer`
> The rate at which data will be sent and received (see the Baud Rate chart in the Notes section, below).
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Bits
**Bits** As `Integer`
> The number of bits.
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.BytesAvailable
**BytesAvailable** As `Integer`
> The number of bytes of data are available in the internal receive buffer.
>
> This property is read-only.
>
> ``` xojo
> TextField1.Text = Me.BytesAvailable.ToString
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.BytesLeftToSend
**BytesLeftToSend** As `Integer`
> The number of bytes left in the queue remaining to be sent.
>
> This property is read-only.
>
> ``` xojo
> TextField1.Text = Me.BytesLeftToSend.ToString
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.ClearToSend
**ClearToSend** As `Boolean`
> Use to read the state of the ClearToSend line.
>
> This property is read-only.
>
> The code below is from Examples/Communication/Hardware/Serial/Line State Change Tester:
>
> ``` xojo
> ' Loop over each line that has changed and print
> ' out the new state of the line.
> Var i As Integer
>
> For Each i In changedLines
> Select Case i
> Case SerialConnection.LineCTS
> MessageBox("CTS is now " + HighLow(Me.ClearToSend))
> Case SerialConnection.LineRTS
> MessageBox("RTS is now " + HighLow(Me.RequestToSend))
> Case SerialConnection.LineDCD
> MessageBox("DCD is now " + HighLow(Me.DataCarrierDetect))
> Case SerialConnection.LineDSR
> MessageBox("DSR is now " + HighLow(Me.DataSetReady))
> Case SerialConnection.LineDTR
> MessageBox("DTR is now " + HighLow(Me.DataTerminalReady))
> Case SerialConnection.LineRI
> MessageBox("RI is now " + HighLow(Me.RingIndicator))
> End Select
> Next
> ```
>
> The HighLow function returns the printable message. It is:
>
> ``` xojo
> If b Then
> Return "asserted"
> Else
> Return "negated"
> End If
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.CTS
**CTS** As `Boolean`
> Enables CTS (Clear to Send) flow control. Signal to the far end that there is space in the receive buffer. Allows DTS to transmit.
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.DataCarrierDetect
**DataCarrierDetect** As `Boolean`
> Enables you to read the state of the DataCarrierDetect line.
>
> This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.DataSetReady
**DataSetReady** As `Boolean`
> Enables you to read the state of the DataSetReady line.
>
> This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.DataTerminalReady
**DataTerminalReady** As `Boolean`
> Sets the state of the data terminal line.
Note
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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Device
**Device** As `SerialDevice`
> Used to identify the serial device to which the SerialConnection control will communicate.
>
> The code below is from Examples/Communication/Hardware/Serial/Line State Change Tester:
>
> ``` xojo
> ' Populate the popup menu with all of the
> ' serial devices the system has installed.
>
> For i As Integer = 0 To SerialDevice.LastIndex
> PopupMenu1.AddRow(SerialDevice.At(i).Name)
> Next
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.DTR
**DTR** As `Boolean`
> Enables DTR (Data Terminal Ready) flow control.
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Handle
**Handle** As `Integer`
> This is the control's internal descriptor and it can be used with `Declare` statements. This replaces Win32DriverHandler, MacInDriverRefNum, and MacOutDriverRefNum.
>
> This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Parity
**Parity** As `Parities`
> The parity that is being used.
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.RequestToSend
**RequestToSend** As `Boolean`
> Sets the state of the RequestToSend line.
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.RingIndicator
**RingIndicator** As `Boolean`
> Enables you to read the state of the RingIndicator line.
>
> This property is read-only.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.StopBit
**StopBit** As `StopBits`
> The number of stop bits being used.
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.XON
**XON** As `Boolean`
> Enables XON flow control.
>
>
>
>
>
> Note
>
>
>
> 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.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.ClearBreak
**ClearBreak**
> Clears the break signal on the control immediately, without the need to call the Reset method. Available on Windows and macOS.
>
> ``` xojo
> SerialConnection1.ClearBreak
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Close
**Close**
> Closes the connection to the serial device.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Connect
**Connect**
> Attempts to open a connection to the serial device.
>
> If the connection could not be made, an `IOException` is raised. If not device was assigned when the method was called, the error code returned is SerialDeviceNotAssigned.
>
> ``` xojo
> Try
> SerialConnection1.Connect
> MessageBox("The serial connection is open.")
> Catch error As IOException
> MessageBox("The serial connection could not be opened.")
> End Try
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.EndOfFile
**EndOfFile** As `Boolean`
> Returns `True` when there's no more data left to read.
>
> This code reads the rows and columns of data from a tab-delimited text file into a `ListBox`:
>
> ``` xojo
> Var f As FolderItem
> Var textInput As TextInputStream
> Var rowFromFile, oneCell As String
>
> f = FolderItem.ShowOpenFileDialog("text/plain") ' defined as a FileType
> If f <> Nil Then
> textInput = TextInputStream.Open(f)
> textInput.Encoding = Encodings.UTF8
>
> Do
> rowFromFile = textInput.ReadLine
> Var values() As String = rowFromFile.ToArray(String.Chr(9))
> ListBox1.ColumnCount = values.Count
> ListBox1.AddRow("")
> Var col As Integer
> For Each value As String In values
> ListBox1.CellTextAt(ListBox1.LastAddedRowIndex, col) = value
> col = col + 1
> End For
> Loop Until textInput.EndOfFile
>
> textInput.Close
> End If
> ```
>
> This example reads each pair of bytes from a file and writes them in reverse order to a new file. The user chooses the source file using the Open-file dialog box and saves the new file using the Save as dialog box. The EOF property is used to terminate the `Do...Loop`.
>
> ``` xojo
> Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text")
> If readFile <> Nil Then
> Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
> ReadStream.LittleEndian = True
> Var writeFile As FolderItem = FolderItem.ShowSaveFileDialog("", "")
> If writeFile <> Nil Then
> Var writeStream As BinaryStream = BinaryStream.Create(writeFile, True)
> writeStream.LittleEndian = True
> Do Until ReadStream.EndOfFile
> writeStream.WriteInt8(ReadStream.ReadInt8)
> Loop
> writeStream = Nil
> End If
> readStream = Nil
> End If
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Flush
**Flush**
> Immediately sends the contents of internal write buffers to disk or to the output stream.
>
> This function can be useful in point-to-point communication over sockets and similar connections: To optimize for transmission performance, some types of output streams try to collect small pieces of written data into one larger piece for sending instead of sending each piece out individually. By calling Flush, the data collection is stopped and the data is sent without further delay, reducing latency.
>
> When using this on a stream that ends up as a file on disk, it is useful, too: Any short parts of previously written data are written to disk right away, ensuring the data is actually on disk if the application terminates abruptly, e.g. due to a crash.
>
> Avoid calling this method too often. For example, do not call it between successive Write calls because you'll slow down performance without getting much benefit.
>
> A typical use case would look like this:
>
> ``` xojo
> mySocket.Write("you typed: ")
> mySocket.Write(key)
> mySocket.Write(".")
> mySocket.Flush
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.LeaveDTROnClose
**LeaveDTROnClose**
> Tells the serial connection not to negate DTR on close. The serial connection must be open for this method to function.
>
> ``` xojo
> SerialConnection1.LeaveDTROnClose
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.LookAhead
**LookAhead**(encoding As `TextEncoding` = `Nil`) As `String`
> Returns all the unread characters in the buffer without deleting them from the buffer. The optional *encoding* parameter enables you to specify the text encoding of the data to be returned. Use the `Encodings` module to specify a text encoding.
>
> This example stores the lookahead text in a `TextField`.
>
> ``` xojo
> TextField1.Text = SerialConnection1.LookAhead(Encodings.UTF8)
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Poll
**Poll**
> Causes the control's properties to update and causes the DataAvailable event to execute if any new data is available.
>
> ``` xojo
> SerialConnection1.Poll
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Read
**Read**(byteCount As `Integer`, encoding As `TextEncoding` = `Nil`) As `String`
> Reads *byteCount* bytes from the input stream and returns a `String`.
>
> If provided, the optional parameter *encoding* specifies the text encoding to be defined for the `String` to be read.
>
> If *byteCount* is higher than the amount of bytes currently available in the stream, all available bytes will be returned. Therefore, make sure to always consider the case that you get less than you requested. To see if you received all requested bytes, check the returned string's `String.Bytes` property (avoid using `Length` as it may give a different number if the encoding is not nil).
>
> If not enough memory is available, you get back an empty string.
>
> This example reads the first 1000 bytes from a `BinaryStream`.
>
> ``` xojo
> Var readFile As FolderItem = FolderItem.ShowOpenFileDialog("text/plain")
> If readFile <> Nil Then
> Var ReadStream As BinaryStream = BinaryStream.Open(readFile, False)
> ReadStream.LittleEndian = True
> TextArea1.Text = ReadStream.Read(1000, Encodings.UTF8)
> End If
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.ReadAll
**ReadAll**(encoding As `TextEncoding` = `Nil`) As `String`
> Returns all incoming data available in the buffer as a `String`.
>
> The optional *encoding* parameter enables you to specify the text encoding of the data to be read. Use the `Encodings` module to specify a text encoding.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.ReadError
**ReadError** As `Boolean`
> If `True` then an error occurred during reading.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.RequestLineChangeNotification
**RequestLineChangeNotification**(linesToWatch() As `SerialConnection.LineStates`)
> When a line state changes, the `LineStateChanged` event occurs and passes an array of lines whose state has changed.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.RequestLineChangeNotification
**RequestLineChangeNotification**(`ParamArray` linesToWatch As `SerialConnection.LineStates`)
> When a line state changes, the `LineStateChanged` event occurs and passes an array of lines whose state has changed.
>
> To select which lines to watch or see which lines have changed, use `LineStates`.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Reset
**Reset**
> Resets the connection's baud and byte format.
>
> The serial connection must be open for this method to function.
>
> Changes to the serial device are queued so that you can modify multiple properties of it without them all taking effect immediately. For instance, you can set the baud, parity and stop bits as one operation instead of three. The same thing applies to the line state properties. Once you've made all your changes, you need to call .Reset on the serial device to reset the device to the new settings.
>
> ``` xojo
> SerialConnection1.Reset
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.SetBreak
**SetBreak**
> Sets the break signal on the control immediately, without the need to call the Reset method.
>
> ``` xojo
> SerialConnection1.SetBreak
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Write
**Write**(Data As `String`)
> Writes the passed data to the output stream.
>
> Note that in order to make sure that the data actually ends up on disk or gets sent to the socket it is connected to, the stream must either get closed or the `Flush` method be called. Otherwise, the data, if small, may end up temporarily in a write buffer before either a certain time has passed or more data is written. This buffering increases performance when writing lots of small pieces of data, but may be causing unwanted delays when another process, e.g. the other end of a socket connection, is waiting for the data. Consider calling the `Flush` method to reduce latencies that this buffering may cause in such cases.
>
> If Write fails, an `IOException` will be raised.
>
> This example displays the Save As dialog box and writes the contents of the TextArea1 to a text file.
>
> ``` xojo
> Var f As FolderItem
> Var stream As BinaryStream
> f = FolderItem.ShowSaveFileDialog(FileTypes1.Text, "Untitled.txt")
> If f<> Nil Then
> stream = BinaryStream.Create(f, True)
> stream.Write(TextArea1.Text)
> stream.Close
> End If
> ```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.WriteError
**WriteError** As `Boolean`
> If `True` then an error occurred during writing.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.XmitWait
**XmitWait**
> Waits until all data sent to the serial connection with the Write method has been sent.
>
> ``` xojo
> SerialConnection1.XmitWait
> ```
## Event descriptions
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.DataReceived
**DataReceived**
> Occurs when additional data has been received.
>
> It is your responsibility to read the received data using Read or ReadAll methods.
>
>
>
>
>
> Warning
>
>
>
> This event is reentrant which means you should **not** process the data you have received in this event. Instead, copy it into a property, then reset a `Timer` set to Single mode. When the incoming data has a lull, the timer will fire once and your parsing code can safely process the accumulated data. Using `Timer.CallLater
` is **not** recommended here, as it creates a new timer invocation for every call to `DataReceived`, which can result in a flood of timers firing in rapid succession.
>
>
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.Error
**Error**(e As `RuntimeException`)
> Occurs when there is an error with the SerialConnection control.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
forsearch
SerialConnection.LineStateChanged
**LineStateChanged**(changedLines() As `SerialConnection.LineStates`)
> When a line state changes, the LineStateChanged event occurs and passes an array of lines whose state has changed.
## Interfaces
This class implements the `Readable` and `Writeable` class interfaces.
## Notes
Note
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 `DesktopControl`. 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.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### 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:
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
### 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.
## Sample code
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:
``` xojo
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`.
``` xojo
Sub DataReceived()
TextArea1.Text = TextArea1.Text + 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:
``` xojo
Sub DataReceived()
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 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.
``` xojo
Try
SerialConnection1.Connect
SerialConnection1.Write(TextArea1.Text)
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).
``` xojo
SerialConnection1.Device = SerialDevice.At(0)
```
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
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.
``` xojo
' 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.LineStates.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 pass the class constants for the line states you want to watch. You don't need to set up a real array.
``` xojo
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:
``` xojo
Var states() As SerialConnection.LineStates
states.Add(SerialConnection.LineStates.RingIndicator)
states.Add(SerialConnection.LineStates.DataTerminalReady)
states.Add(SerialConnection.LineStates.ClearToSend)
SerialConnection1.RequestLineChangeNotification(states)
```
## Compatibility
| | |
|-----------------------|-----------------------|
| **Project Types** | Console, Desktop, Web |
| **Operating Systems** | All |
`Object` parent class; `SerialDevice` class; `Readable`, `Writeable` class interfaces; `Connecting to a Serial Device`; `Updating Older Projects` topic