XMPP

The XMPP Connector collects data from IoT devices over the XMPP protocol and forwards it to ThingsBoard.

To enable this connector, add it to the connectors list in tb_gateway.json — see the General Configuration reference.

Connector configuration: xmpp.json

The connector reads its settings from a JSON file. Below is a full example:

{
  "server": {
    "jid": "gateway@localhost",
    "password": "password",
    "host": "localhost",
    "port": 5222,
    "use_ssl": false,
    "disable_starttls": false,
    "force_starttls": true,
    "timeout": 10000,
    "plugins": [
      "xep_0030",
      "xep_0323",
      "xep_0325"
    ]
  },
  "devices": [
    {
      "jid": "device@localhost/TMP_1101",
      "deviceNameExpression": "${serialNumber}",
      "deviceTypeExpression": "default",
      "attributes": [
        {
          "key": "temperature",
          "value": "${temp}"
        }
      ],
      "timeseries": [
        {
          "key": "humidity",
          "value": "${hum}"
        },
        {
          "key": "combination",
          "value": "${temp}:${hum}"
        }
      ],
      "attributeUpdates": [
        {
          "attributeOnThingsBoard": "shared",
          "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
        }
      ],
      "serverSideRpc": [
        {
          "methodRPC": "rpc1",
          "withResponse": true,
          "valueExpression": "${params}"
        }
      ]
    }
  ]
}

Section “server”

Configures the gateway’s XMPP account and connection to the XMPP server.

Parameter	Default	Description
`jid`	`gateway@localhost`	JID (Jabber ID) of the gateway’s XMPP account
`password`		Password for the gateway’s XMPP account
`host`	`localhost`	XMPP server hostname
`port`	`5222`	XMPP server port
`use_ssl`	`false`	Use legacy SSL instead of STARTTLS
`disable_starttls`	`false`	Disable TLS entirely for the connection
`force_starttls`	`true`	Abort the connection if the server does not advertise STARTTLS support
`timeout`	`10000`	Connection timeout in milliseconds
`plugins`	`["xep_0030","xep_0323","xep_0325"]`	XMPP extension plugins to register with the client

"server": {
  "jid": "gateway@localhost",
  "password": "password",
  "host": "localhost",
  "port": 5222,
  "use_ssl": false,
  "disable_starttls": false,
  "force_starttls": true,
  "timeout": 10000,
  "plugins": [
    "xep_0030",
    "xep_0323",
    "xep_0325"
  ]
}

Section “devices”

An array of devices the connector is allowed to communicate with. Any device whose JID is not listed here is rejected.

Each entry in the array configures one device and may contain the following subsections: attributeUpdates and serverSideRpc are optional.

Device object

Parameter	Default	Description
`jid`		JID of the device’s XMPP account
`deviceNameExpression`		JSON-path expression to extract the device name from incoming messages
`deviceTypeExpression`		JSON-path expression to determine the device type (profile)
`attributes`		Group addresses mapped to ThingsBoard device attributes (see below)
`timeseries`		Group addresses mapped to ThingsBoard time-series telemetry (see below)

Both attributes and timeseries entries share the same field structure:

Parameter	Description
`key`	ThingsBoard attribute or telemetry key name
`value`	JSON-path expression to extract the value from the incoming message

{
  "jid": "device@localhost/TMP_1101",
  "deviceNameExpression": "${serialNumber}",
  "deviceTypeExpression": "default",
  "attributes": [
    {
      "key": "temperature",
      "value": "${temp}"
    }
  ],
  "timeseries": [
    {
      "key": "humidity",
      "value": "${hum}"
    },
    {
      "key": "combination",
      "value": "${temp}:${hum}"
    }
  ]
}

Subsection “attributeUpdates”

ThingsBoard allows the provisioning of device attributes and fetches some of them from the device application. You can treat this as a remote configuration for devices, enabling them to request shared attributes from ThingsBoard. See user guide for more details.

The “attributeUpdates” configuration allows you to configure the format of the corresponding attribute data that will be sent to the XMPP device.

Parameter	Default	Description
`attributeOnThingsBoard`		Shared attribute name to subscribe to
`valueExpression`		JSON-path expression used to build the message payload sent to the device

"attributeUpdates": [
  {
    "attributeOnThingsBoard": "shared",
    "valueExpression": "{\"${attributeKey}\":\"${attributeValue}\"}"
  }
]

Subsection “serverSideRpc”

ThingsBoard allows sending RPC commands to the device connected to ThingsBoard directly or via Gateway.

Configuration, provided in this section is used for sending RPC requests from ThingsBoard to the device.

Parameter	Default	Description
`methodRPC`		RPC method name to bind
`withResponse`	`true`	Send the device’s response back to ThingsBoard
`valueExpression`		JSON-path expression used to build the message payload sent to the device

"serverSideRpc": [
  {
    "methodRPC": "rpc1",
    "withResponse": true,
    "valueExpression": "${params}"
  }
]