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
note

When using the Lobaro Platform including remote firmware updates, you must use the default CBOR payload format. Currently, JSON is not supported for firmware update traffic.

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

Currently remote firmware updates over MQTT are only supported when using the default CBOR format (cbor or no explicit format prefix). If you select json (e.g. json+mqtts://...), normal uplink/downlink communication works, but remote firmware updates will not.

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 the Lobaro Platform (platform.lobaro.com) and communicate using CBOR (required for remote firmware updates):

    mqtts://platform.lobaro.com

  • Connect via MQTTS using username foo and password bar to the Lobaro Platform and communicate using CBOR, but without sending a client certificate:

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

  • Connect via MQTTS using username foo and password bar to example.com and communicate using JSON (no remote firmware updates in JSON mode):

    json+mqtts://foo:bar@example.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: mqtts://platform.lobaro.com,mqtt://foo:bar@platform.lobaro.com.