Skip to main content

Host Parameter

This page describes how the Host configuration parameter needs to be formatted to connect to an MQTT broker.

Host Parameter Generator​

To generate the Host configuration parameter for your device, please enter the connection details of your MQTT broker:

JSON

Host Parameter Specification​

The MQTT Host parameter is formatted as follows:

[format+]protocol://[user[:password]@]host[:port][/topic prefix/][?arguments]

Supported formats:

  • cbor (default)
  • json
CBOR to JSON Mapping
  • Byte arrays are encoded as base64 strings in JSON, but have a separate type in CBOR.
  • Map keys are always strings in JSON, despite CBOR supports any type.

Supported protocols:

  • mqtt
  • mqtts
warning

When using MQTTS, the gateway presents its client certificate to the server unless the cert=0 parameter is used (see below). Your MQTT broker should add the Lobaro certificate as a trusted CA; otherwise, the gateway will not connect to the broker. The certificate can be downloaded here. You should add it as a trusted CA on your server. Device certificates could also be changed, please contact Lobaro for more information on this topic.

Username and password are optional. Each of them has a maximum length of 64 characters.

note

Username and password need to be URL encoded!

The host may be either a DNS hostname or an IPv4 address. IPv6 is currently not supported.

note

TLS Server Name Identification (SNI) is only supported when a hostname is set!

The port is optional. Default ports:

  • mqtt: Port 1883.
  • mqtts: Port 8883.

The topic prefix is optional. Default prefix: LOB/.

note

Make sure to include a trailing slash in your topic prefix!

The following arguments are currently supported and can be included as URL query string:

  • cert=0: Disable client-certificate authentication when using MQTTS.
info

The MQTT client ID is the DevEui and cannot be changed.

Example Host Parameters​

  • Connect via MQTTS using client-certificate authentication to platform.lobaro.com and communicate using CBOR:

mqtts://platform.lobaro.com

  • Connect via MQTTS using username foo and password bar to platform.lobaro.com and communicate using JSON.:

json+mqtts://foo:bar@platform.lobaro.com?cert=0

  • Connect via MQTT using username foo and password bar to example.com on port 1234 and communicate using JSON on path prefix /mydevice/:

json+mqtt://foo:bar@example.com:1234/mydevice/

Host with Fallback​

To configure MQTT broker fallbacks, include multiple broker URLs separated by commas. The device will then use the first broker to which it can successfully connect.

Example: json+mqtts://platform.lobaro.com,json+mqtt://foo:bar@platform.lobaro.com.