Skip to content

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
even
odd
mark
space		 none Serial Parity Configuration
Flow Control Handshake Enum none
RTS/CTS
XON/XOFF
 none Flow control with hardware, software or none.
highWaterMark Integer 65536 The size of the read and write buffers
parserType Enum Raw
Readline
ByteLength
Delimiter
InterByteTimeout
Ready
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
utf8
utf16le
ucs2
base64
binary
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 <NAME>. (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
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
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
RegularExpression
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 <NAME>. (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
DifferentValues
Periodic		 AllValues Determines how and when the data can be emitted as an event.
AllValues: every time the trigger property value is received
DifferentValues: every time a different trigger property value is received
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
UseCurrentCommandSettings
RawCommandParameters
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
AtEnd
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 <NAME> (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 <StartToken>CommandDeviceID<SeparatorToken>Parameter_1_Value<SeparatorToken>Parameter_2_Value<EndToken>
AtEnd <StartToken>Parameter_1_Value<SeparatorToken>Parameter_2_Value<SeparatorToken>CommandDeviceID<EndToken>
NotUsed <StartToken><SeparatorToken>Parameter_1_Value<SeparatorToken>Parameter_2_Value<EndToken>

Convert Non Printable ASCII Chars on Send Value#

Before Conversion After Conversion
<DeviceID<TAB>Parameter_1_Value> <DeviceID\tParameter_1_Value>
  • Note:
    • Start Token: <
    • Separator Token: <TAB>
    • End Token: >

Command Parameters#

Name Type Possible Values Default Value Description
Parameter Type Enum CommandParameter
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: <
    • Separator Token: <TAB>
    • End Token: >
  • 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: <
    • Separator Token: <TAB>
    • End Token: >
  • Value Sent:
    • DeviceId

Non Printable ASCII Chars - Token/Value Substitution#

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

Please note:

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