Skip to content
View as markdown Ask ChatGPT Ask Claude

Connect IoT - TCPIP Driver#

This driver interacts on the TCP/IP layer allowing active and passive connections.

Parsers are used to take raw TCP/IP 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
mode Enum Active
Passive		 Active Actively connects to the device (Active) or passively waits for the device to connect (Passive).
On Active mode: Driver uses .connect(), Device uses .listen().
On Passive mode: Device uses .connect(), Driver uses .listen()
In Passive mode, commands are sent to every connected device, and a device disconnecting does not change the communication state.
host String 0.0.0.0 Active Mode: Host that the driver should connect to.
Passive Mode: Address to bind the listen() call
port Integer 0 Active Mode: Port that the socket should connect to.
Passive Mode: Port where the driver will listen to device connections. If port is 0, the operating system will assign an arbitrary unused port, which can be retrieved on driver execution log during runtime.
localAddress String 0.0.0.0 Active mode only: Local address the socket should connect from.
localPort Integer 0 Active mode only: Local port the socket should connect from.
family Enum 4
6		 4 Version of IP stack, can be either 4 or 6.
maxClients Integer 1 Passive mode only: Maximum number of clients sockets allowed.
keepAliveTime Integer 10000 (Passive & Active Mode): Keep Alive Time (ms)
socketEncoding Enum ascii
utf8
utf16le
ucs2
base64
binary
hex		 ascii Stream encoding
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, Regex: String delimiter to split incoming text. In Readline, Delimiter, and Ready, the first \r, the first \n, and the first \t of the value are replaced by the carriage return, line feed, and tab characters, and later occurrences are kept as written. If parser is Regex 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
defaultConvertNonPrintableASCIICharsOnSend 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).
defaultConvertNonPrintableASCIICharsOnReceive 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).
commandMessageStart String Default value used in the beginning of the command
commandMessageSeparator String Default value used between command parameters
commandMessageDeviceIdSeparator String Default value used between command and first command parameter
commandMessageEnd 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 byteLengthNumber 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, parserIdentifierValue is ignored and all messages update that property. The Token type matches parserIdentifierValue text only on the beginning of the message and RegularExpression matches on configured Regular Expression parserIdentifierValue field.
parserIdentifierValue 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).
useIdentifierValueAsParser Boolean false If true, parses data using Identifier Value as Parser. Only applies to Identifier Type "RegularExpression", where properties values will only have a value that matches the defined Regular Expression.

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).

Writing a property value, for example with the Set Equipment Properties task, sends nothing to the device. The driver only updates the value it holds for that property.

Event#

Name Type Possible Values Default Value Description
workingMode 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 workingMode Periodic

Event Property#

Name Type Possible Values Default Value Description
isTrigger Boolean true Trigger the event when the property is received (event workingMode AllValues), or when the value is changed (event workingMode 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)

With Reply Expected, the next data the parser emits after the command is sent is taken as the reply, whatever its content, and it updates no property and raises no event. The driver adds nothing to a command beyond the configured tokens, the device ID, and the parameters, so the delimiter is not appended.

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:

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