---
alias: user-guide-driver-serial
tags:
- connect iot
description: "This documentation details a serial driver for IoT devices, enabling communication via RS232, managing data types, and handling protocol parameters"
---

# Connect IoT - Serial Driver

Serial Communications (compliance with the RS232 standard) is a communication interface through which information transfers in or out one bit at a time.

Is a widely communication interface still used today (if not natively, with USB-Serial converters) in a variety of devices.

On this driver, parsers are used to take raw serial data and transform them into usable messages.

## Data Types

These are the supported specific data types:

Name | Description
---------|---------------
String|String Value
Boolean|Boolean Value
Integer|Integer value
Decimal|Decimal value
Object|Structured value

## Protocol Parameters

The protocol supports the following parameters:

Name | Type | Possible Values | Default Value |  Description
--- | --- | --- | --- | ---
Port Name | String | | COM1 | Name of the port to connect (e.g.: COM1, /dev/tty-usbserial1, ...). On driver startup, list of available ports is printed.
BaudRate | Integer | | 9600 |The baud rate of the port to be opened. This should match one of the commonly available baud rates, such as 110, 300, 1200, 2400, 4800, 9600, 14400, 19200, 38400, 57600, or 115200. Custom rates are supported best effort per platform. The device connected to the serial port is not guaranteed to support the requested baud rate, even if the port itself supports that baud rate
Data Bits| Integer | | 8 | Must be one of these: 8, 7, 6, or 5
Stop Bits| Integer | | 1 | Must be one of these: 1 or 2
Serial Parity| Enum | none<br>even<br>odd<br>mark<br>space | none | Serial Parity Configuration
Flow Control Handshake| Enum | none<br>RTS/CTS<br>XON/XOFF<br>| none | Flow control with hardware, software or none.
highWaterMark | Integer | | 65536 | The size of the read and write buffers
parserType | Enum | Raw<br>Readline<br>ByteLength<br>Delimiter<br>InterByteTimeout<br>Ready<br>Regex | ReadLine | Select the parser used to determine when the received data from the device is to be recognized and ready to be processed (check specific section about each of the parsers for more information).
delimiter | string | | "\r\n" | Used in parsers *Readline* , *Delimiter*, *Ready*, *RegularExpression*: String delimiter to split incoming text. Simple string substitutions can be used like \r\n\t. If parser is RegularExpression you can use regular expressions such as: [\r\n]+
encoding | Enum | ascii<br>utf8<br>utf16le<br>ucs2<br>base64<br>binary<br>hex | ascii | Used in parsers *Readline*, *Regex*: Text encoding for the received data
byteLengthNumber | Integer | | 8 | Used in parsers *ByteLength*: Number of bytes to receive before triggering the event
timeoutValue | Integer | | 1000 | Used in parsers *InterByteTimeout*: Period of silence in milliseconds after which data is emitted
maxBufferSize | Integer | | 65536 | Used in parsers: *InterByteTimeout*: Maximum number of bytes after which data will be emitted
Default Convert Non Printable ASCII Chars On Send | Boolean | | False | Does character substitution on sent values. Replaces ASCII token names with the correspondent ASCII value. (See table *Non Printable ASCII Chars - Token/Value Substitution*).
Default Convert Non Printable ASCII Chars On Receive| Boolean | | False | Does character substitution on received values. Replaces non printable ascii codes to correspondent &lt;NAME&gt;. (See table *Non Printable ASCII Chars - Token/Value Substitution*).
Default Command Message Start| String | | | Default value used in the beginning of the command
Default Command Message Separator| String | | | Default value used between command parameters
Default Command Message Device Id Separator| String | | | Default value used between command and first command parameter
Default Command Message End| String | | | Default value used in the end of the command

## Parsers

Parsers are collection of transform streams to process incoming data. The following parsers are available:

Name | Parameters | Description
--- | --- | ---
Raw | | Any data received will be immediately processed.
Readline | delimiter | Data is emitted after the configured newline delimiter is received.
ByteLength | byteLengthSize | Data is emitted right after a specific number of bytes are received.
Delimiter | delimiter | Data is emitted each time a specific sequence is received.
InterByte Timeout | timeoutValue<br>maxBufferSize | Data is emitted after not receiving any bytes for the specified amount of time or if the buffer becomes full.
Ready | delimiter | Data is not emitted until a sequence of *ready* bytes (that match the *delimiter* parameter) before emitting a ready event and emitting data events
Regex | delimiter<br>encoding | A regular expression (delimiter parameter) is used to split the incoming text. The matches are emitted as data to be processed.

## Extended Parameters

As with other protocol drivers, some extra parameters are necessary to provide more context to the behavior expected.

### Property

Name | Type | Possible Values | Default Value |  Description
--- | --- | --- | --- | ---
identifierType | Enum | None<br>RegularExpression<br>Token | None | Method used to identify a property. If `None` is used, `identifierValue` will be ignored and all messages will update that property. `Token` type will match `identifierValue` text only on the beginning of the message and `RegularExpression` will match on configured Regular Expression `identifierValue` field.
identifierValue | String | | | Value of the Property Identifier. Valid on `RegularExpression` (enter a valid regular expression) or `Token` (enter the expected text) `identifierType`.
convertIdentifierNonPrintableASCIIChars | Boolean | | false | If `true`, does character substitution on `Identifier Value`. Replaces non printable ascii codes to correspondent &lt;NAME&gt;. (See table *Non Printable ASCII Chars - Token/Value Substitution*).

#### Remarks/Behavior

* The identifiers used on properties are used to identify a property, and not to extract any kind of information from the property. To extract information from the value of a property you can use the controller workflow (e.g., with a `Regular Evaluator` task with a `Regular Expression` type). 


## Event

Name | Type | Possible Values | Default Value |  Description
--- | --- | --- | --- | ---
triggerMode | Enum | AllValues<br>DifferentValues<br>Periodic | AllValues | Determines how and when the data can be emitted as an event.<br>`AllValues`: every time the trigger property value is received<br>`DifferentValues`: every time a different trigger property value is received<br>`Periodic`: On a periodic basis (every `periodicDataInterval`, in milliseconds), disregarding property update cycles or values.
periodicDataInterval | Integer | | 1000 | Number of milliseconds to publish data. Only valid on triggerMode `Periodic`

### Event Property

Name | Type | Possible Values | Default Value |  Description
--- | --- | --- | --- | ---
isTrigger | Boolean | | true | Trigger the event when the property is received (event triggerMode `AllValues`), or when the value is changed (event triggerMode `AllValues` or `DifferentValues`)

### Remarks/Behavior

* When an event has more than one property with the `isTrigger` flag:
    * It will be triggered every time any of the properties value changes.
    * The value of the other properties will be requested at that time.
    * It is possible to have multiple triggers with the same set values (because they have not changed). If this behavior is not intended, separate into multiple events each one with its own trigger set.
* When an event has no property with the isTrigger flag, it will **never** be triggered (unless event is defined as `Periodic`)

## Command

Name | Type | Possible Values | Default Value |  Description
--- | --- | --- | --- | ---
Command Structure Behavior | Enum | UseEquipmentSetupTaskSettings<br>UseCurrentCommandSettings<br>RawCommandParameters<br>RawCommand|UseEquipmentSetupTaskSettings | Commands can use configurations (tokens and ASCII conversion definition) from Equipment Setup Task (**Use Equipment Setup Task Tokens**) or custom on each command (**Use Current Command Tokens**). On **RawCommand** mode, no tokens are used and Device Id data is sent. On **RawCommandParameters** mode, command parameters are concatenated and sent.
Command Device ID Usage | Enum | AtBeginning<br>AtEnd<br>NotUsed|AtBeginning | Command device id can be used at beginning of the sent message, at the end of the sent message or simply not used and the message will only contain the command parameters. Please note that if **commandBehavior** is **RawCommand** or **RawCommandParameters** then this field is ignored.
Convert Non Printable ASCII Chars on Send Value | Boolean | | False | If true, does token substitution on Command Send Value. Replaces ASCII token names with character value. (See table *Non Printable ASCII Chars - Token/Value Substitution*).
Message Start Token | String | | | Value used in the beginning of the command
Message Separator Token | String | | | Value used between command parameters
Message Device Id Separator Token | String | | | Value used between command and first command parameter
Message End Token | String | | | Message End Token
Reply Expected | Boolean | | False| Should be true, if this command should expect a reply
Convert Non Printable ASCII Chars on Reply | Boolean | | False| If true, does character substitution on Command Reply received values. Replaces non printable ascii codes on reply to correspondent &lt;NAME&gt;  (See table *Non Printable ASCII Chars - Token/Value Substitution*).
Reply TimeOut (ms) | Integer | | 1000 | Command Reply times out at specified milliseconds value.

### Remarks/Behavior

* If `Reply Expected` is true, while waiting for `Reply TimeOut (ms)`, no other command will be sent (it will be queued and sent after reply received or timeout value reached)
* If `Reply TimeOut` is equal or less than 0, default value is loaded (1 second)

### Example Scenarios

#### Command Device ID Usage

Selected Option|Command Sent Value
-------------------|----------------------
**AtBeginning** | &lt;StartToken&gt;**CommandDeviceID**&lt;SeparatorToken&gt;Parameter_1_Value&lt;SeparatorToken&gt;Parameter_2_Value&lt;EndToken&gt;
**AtEnd** | &lt;StartToken&gt;Parameter_1_Value&lt;SeparatorToken&gt;Parameter_2_Value&lt;SeparatorToken&gt;**CommandDeviceID**&lt;EndToken&gt;
**NotUsed** | &lt;StartToken&gt;&lt;SeparatorToken&gt;Parameter_1_Value&lt;SeparatorToken&gt;Parameter_2_Value&lt;EndToken&gt;

#### Convert Non Printable ASCII Chars on Send Value

Before Conversion | After Conversion
----------------------|---------------------
&lt;DeviceID&lt;TAB&gt;Parameter_1_Value&gt;|&lt;DeviceID\tParameter_1_Value&gt;

* Note:
    * Start Token: &lt;
    * Separator Token: &lt;TAB&gt;
    * End Token: &gt;

## Command Parameters

Name | Type | Possible Values | Default Value |  Description
--- | --- | --- | --- | ---
Parameter Type| Enum | CommandParameter<br>RawCommandParameter| CommandParameter |Allows configuration of this parameter as a regular command parameter or a RAW command. If `Command Structure Behavior` is `RawCommandParameters` then there should be at least one Parameter Type as `RawCommandParameter` (if multiple defined, concatenation is performed).

### Examples

#### RAW Command Example

#### Parameters

* Test Scenario:
    * **Command Structure Behavior**: **RawCommandParameters**
    * Parameter 01: Parameter Type: **CommandParameter**
    * Parameter 01 Value: TestPar_1
    * Parameter 02: Parameter Type: **RawCommandParameter**
    * Parameter 02 Value: TestRaw_2
    * Parameter 03: Parameter Type: **RawCommandParameter**
    * Parameter 03 Value: TestRaw_3
    * Start Token: &lt;
    * Separator Token: &lt;TAB&gt;
    * End Token: &gt;
* Value Sent:
    * TestRaw_2TestRaw_3

#### DeviceId

* Test Scenario:
    * **Command Structure Behavior**: **RawCommand**
    * **Command Device Id**: DeviceId
    * Parameter 01: Parameter Type: **CommandParameter**
    * Parameter 01 Value: TestPar_1
    * Parameter 02: Parameter Type: **RawCommandParameter**
    * Parameter 02 Value: TestRaw_2
    * Parameter 03: Parameter Type: **RawCommandParameter**
    * Parameter 03 Value: TestRaw_3
    * Start Token: &lt;
    * Separator Token: &lt;TAB&gt;
    * End Token: &gt;
* Value Sent:
    * DeviceId

## Non Printable ASCII Chars - Token/Value Substitution

|token|value|token|value|token|value|token|value|token|value|
|---------|---------|---------|---------|---------|---------|---------|---------|---------|---------|
|&lt;NUL&gt;|0|&lt;SOH&gt;|1|&lt;STX&gt;|2|&lt;ETX&gt;|3|&lt;EOT&gt;|4|
|&lt;ENQ&gt;|5|&lt;ACK&gt;|6|&lt;BEL&gt;|7|&lt;BS&gt;|8|&lt;TAB&gt;|9|
|&lt;LF&gt;|10|&lt;VT&gt;|11|&lt;FF&gt;|12|&lt;CR&gt;|13|&lt;SO&gt;|14|
|&lt;SI&gt;|15|&lt;DLE&gt;|16|&lt;DC1&gt;|17|&lt;DC2&gt;|18|&lt;DC3&gt;|19|
|&lt;DC4&gt;|20|&lt;NAK&gt;|21|&lt;SYN&gt;|22|&lt;ETB&gt;|23|&lt;CAN&gt;|24|
|&lt;EM&gt;|25|&lt;SUB&gt;|26|&lt;ESC&gt;|27|&lt;FS&gt;|28|&lt;GS&gt;|29|
|&lt;RS&gt;|30|&lt;US&gt;|31|&lt;DEL&gt;|127|

Please note: 

* Values presented are in decimal notation.
* These token/values substitution values are hardcoded.