Controlling a remote device via MQTT

Introduction

In some cases, you will want to control a device that is not in the same network as you. This tutorial will show you how to use the Cloud MQTT broker as a bridge to control your ZBOS device.

The MQTT API is the most complete way of controlling an external device. For simpler usecases (e.g. trigger a specific action), it is advised to use the webhook functionality instead (requires at least ZBOS version 2.8).

Authentication

There are 2 ways to get MQTT account credentials, depending on your use case.

1) Create your own web application based on OAuth 2.0.

This is only relevant for large scale integrations with the ZBOS platform. Please contact support for more information about the different options and requirements. See the next method for all other cases.

2) Use the MQTT account that ZBOS Control uses.

This is good for simple usecases.

You can easily find out the MQTT credentials that ZBOS Control uses. Follow these steps:

  1. Go to the ZBOS Control web application

  2. Make sure you are logged out (use the top right account menu to log out)

  3. Open the developer tools in your browser (this depends on the browser, to open the developer console in Google Chrome, open the Chrome Menu in the upper-right-hand corner of the browser window and select More Tools > Developer Tools. You can also use Option + ⌘ + J (on macOS), or Shift + CTRL + J (on Windows/Linux).)

  4. Click the "Network" tab and type "account" in filters (again, this may be different depending on your browser)

  5. Log in to ZBOS Control

  6. The response from the ZBOS User API will now be logged in the console, copy the username and password from there:

mqtt account via devtools

Connecting to the Cloud broker

Use the following information to connect your MQTT client:

protocol

mqtt (websockets is also possible)

host

mqtt.zorabots.be

port

1884 (other options also possible)

username

the username retrieved in previous step

password

the password retrieved in previous step

Subscribing and publishing

The ZBOS Cloud broker limits what you can subscribe and publish on in order to make sure you have access to your, and only your, devices. To publish something to a specific device (that is linked to your account), you need to include the serial number in the topic name.

The format is as following:

  • Publish: zbos/ becomes zbos/<serial>

  • Subscribe: zbos/ becomes push/<serial>

For example, if the serial number of your destination device is ABCDEF, the simple topic to make the device speak, zbos/dialog/set/message, becomes zbos/ABCDEF/dialog/set/message. Similarly to know when the speech starts, subscribe to push/ABCDEF/dialog/tts/start, replacing ABCDEF with the serial of your target device.

Refer to the RAIL and Cloud MQTT docs for more information on what you can do with the API: