Overview

The IoT Gateway supports extensions - custom connectors and converters written in Python. Use them to connect to any device or protocol not covered by the built-in connectors.

  tb_gateway.json
  └── "connectors": [
        { "type": "serial", "class": "SerialConnector", ... }
      ]
               │
               ▼  loaded from extensions folder
  extensions/serial/serial_connector.py
  └── SerialConnector(Connector)                         ← connector
  extensions/serial/custom_serial_downlink_converter.py
  └── SerialDownlinkConverter(Converter)                 ← converter
  extensions/serial/custom_serial_uplink_converter.py
  └── SerialUplinkConverter(Converter)                   ← converter

Registering a custom connector

Add the connector entry to the "connectors" array in tb_gateway.json:

"connectors": [
  {
    "name": "My Custom Connector",
    "type": "folder_name_with_connector",
    "class": "MyConnectorClassName",
    "configuration": "my_connector_config.json"
  }
]

Field	Description
name	Connector name. Used by the gateway to match saved devices to their connector.
type	Name of the subfolder inside the extensions folder containing the connector file.
class	Python class name of the connector (must inherit from `Connector`).
configuration	Filename of the connector’s JSON configuration, placed in the gateway config folder.

Restart the gateway after adding a new connector.

Registering a custom converter

Custom converters are referenced from the connector’s own JSON configuration file — not from tb_gateway.json. The parameter name depends on the connector implementation; "converter" (uplink) and "downlink_converter" are the conventional names.

MQTT connector example:

"topicFilter": "custom/sensors/+",
"converter": {
  "type": "custom",
  "extension": "CustomMqttUplinkConverter",
  "cached": true,
  "extension-config": {
    "temperatureBytes": 2,
    "humidityBytes": 2,
    "batteryLevelBytes": 1
  }
}

OPC-UA connector example:

"mapping": [
  {
    "deviceNodePattern": "Root\\.Objects\\.Device1",
    "deviceNamePattern": "Device ${Root\\.Objects\\.Device1\\.serialNumber}",
    "converter": "CustomOpcUaConverter",
    "attributes": [
      { "key": "temperature °C", "path": "${ns=2;i=5}" }
    ]
  }
]

Restart only the connector (not the full gateway) to apply converter changes.

In this section

Methods and data types

Reference for gateway service methods, utility methods, and the data types used in custom connector and converter development.

Read the reference →

Serial connector example

End-to-end tutorial: implement a serial port connector with uplink and downlink converters from scratch.

Follow the tutorial →