---
alias: user-guide-driver-tcpip
tags:
- connect iot
description: "This documentation describes a TCPIP driver for IoT devices, enabling TCP/IP communication with configurable protocols, parsers, and event handling"
---

# 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<br>Passive | Active | Actively connects to the device (`Active`) or passively waits for the device to connect (`Passive`).<br>On `Active` mode:  Driver uses .connect(), Device uses .listen().<br>On `Passive` mode: Device uses .connect(), Driver uses .listen()
host | String | | 0.0.0.0 | `Active` Mode: Host that the driver should connect to.<br>`Passive` Mode: Address to bind the listen() call
port | Integer | | 0 | `Active` Mode: Port that the socket should connect to.<br>`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<br>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<br>utf8<br>utf16le<br>ucs2<br>base64<br>binary<br>hex | ascii | Stream encoding
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
byteLengthSize | 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
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*).
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*).
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). 

## 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:

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