MQTT publish

You can invoke a UbiFunction by publishing data through MQTT. This makes it possible to integrate devices and gateways that may have a non-editable JSON payload that is not compatible with our native MQTT broker or our HTTP Data Ingestion API.

Because the UbiFunctions MQTT broker is shared across all functions, subscription requests are not supported and only the MQTT Publish method is accepted. Accordingly, all subscription requests are rejected.

If you'd like to have a private MQTT broker mapped to a UbiFunction, please reach out to our sales team. In this case, subscribe actions can be supported.

The UbiFunction method must be set to POST.

Here are the MQTT settings needed to invoke a UbiFunction over MQTT:

MQTT Settings	Value
URL	functions.ubidots.com
Port	1883 for plain MQTT. 8883 for MQTT over TLS.
Topic	/prv/<your-username>/<function-label>
Username	Your account username
Password	Valid Token from your Ubidots account.
ClientID	Any random string. Preferably longer than 15 characters

Topic structure

To trigger a UbiFunction through MQTT, the publish topic must follow this structure:

/prv/<username>/<function-label>

Where:

• <username> is your Ubidots account username.

• <function-label> is the function name in lowercase, with spaces replaced by dashes.

The base topic corresponds to the UbiFunction HTTPS Endpoint URL's path, as seen in the image below:

Advanced Topics

Additional topic levels are supported. To add more levels, simply add a forward slash ("/") after the base topic:

/prv/<username>/<function-label>/<level-1>/···/<level-N>

Where:

• <level-N> is any additional UTF-8 encoded string that you want to add to the topic.

Topics have the following limits:

Topic Limits	Limit
Length	1500 characters
Levels	10

UbiFunction args

When triggering a UbiFunction through MQTT, you receive a JSON object in the args variable of the main function. The object has this structure:

{
  "topic": "<topic>",
  "payload": "<payload>",
  "from_client_id": "<client_id>",
}

Where:

Key	Type	Value description
topic	String	The multilevel publication topic
payload	String	The payload sent by the device in the publication message.
from_client_id	String	The client ID used in the MQTT connection.

Certificates

Ubidots supports SSL V1.1, TLS V1.2, and V1.3. You can download our root certificates in different formats:

• PEM file: Certificate chain with two root certificates from our certificate authorities (CAs).

• DER file: Same as the PEM file, with an alternative encoding.

• CRT file: Same as the PEM file, with a different extension. Often referred to as .crt, .cert or .cer.

Examples

Port 1883

mosquitto_pub \
-p 1883 \ 
-h functions.ubidots.com \
-t "/prv/<username>/<function-name>" \
-m '{"token": "TOKEN", "device": "device-label", "variable-label": value}' \
-u "<username>" \
-P "TOKEN" \
-q 1 -d

Port 8883