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 use cases (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) Retrieve your MQTT Account via the User API

This is good for simple use cases or initial testing.

  1. Go to the accounts page and copy the cloud-id and auth token for the next step.

  2. Request your MQTT Account

GET https://api.talemate.co/api/v1/users/{userId}/mqtt/account
mqtt account via api call

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: