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:
-
Make sure you are logged out (use the top right account menu to log out)
-
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).)
-
Click the "Network" tab and type "account" in filters (again, this may be different depending on your browser)
-
Log in to ZBOS Control
-
The response from the ZBOS User API will now be logged in the console, copy the username and password from there:
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/
becomeszbos/<serial>
-
Subscribe:
zbos/
becomespush/<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: