A getting started guide for integrating your application with Spotto's MQTT broker
Spotto has an MQTT broker that publishes all live updates as they occur in Spotto. As assets move to new zones and other significant state changes take place, these events are published to topics on the broker.
This article helps you get started with connecting to Spotto's MQTT broker, subscribing to topics, and understanding the different kinds of Spotto events you can subscribe to.
Spotto’s MQTT broker is hosted at mqtt://mqtt.spotto.cloud
To connect to the broker you will need to retrieve your login credentials using the GetMQTTSettings API endpoint
Use the username and password, along with the hostname to connect. If your MQTT library requires a client ID please use a randomised string. This ensures that the connection won’t be stolen by another client attempting to use the same ID. Most MQTT libraries will randomise this ID automatically.
Javascript Example code for connecting to the broker:
We recommend using MQTT-Explorer to get familiar with MQTT. Use the details from the GetMQTTSettings API and the hostname above to login, then subscribe to the root topic returned from the API. See the subscribing to a topic section for more information on this.
Once connected to Spotto’s MQTT broker you can subscribe to topics and receive messages.
In Spotto, topics are constructed using the following pattern.
{OrganisationID}/{EventType}/{EntityID}
The root topic from the GetMQTTSettings API subscribes to all events for your organisation and will look something like this - 012345678901234567890123/#. You can choose to subscribe to specific sub-topics as well.
Build your subscriptions using the root topic as a base as our broker will block you from subscribing to other top-level topics for security reasons.
For example, if you wanted to subscribe to all Arrived events for asset A1, you would use the topic {OrganisationID}/Arrived/A1. See the Spotto Events section below for more information on the different kinds of Spotto events.
If you are using MQTT explorer you can experiment with subscribing to different sub topics easily. A good place to start is subscribing to all Arrived events using the topic {OrganisationID}/Arrived/#.
Javascript example code for subscribing to a topic
The Spotto MQTT broker does not allow clients to publish to topics. It is designed as a subscribe only service so that applications can hook into the event stream.
A Spotto event represents a moment in time where something significant occurred, this may be a reader coming online or an asset moving. Spotto has multiple event types that indicate the type of action that took place. The ID and names of any relevant entities are also included in the message payload.
Spotto exposes the following types of Events:
Arrived events occur when an asset has moved from one location to another. Assets are the primary entity and Arrived events are published according to the following topic structure and payload.
{OrganisationID}/Arrived/{AssetID}
ReaderArrived events occur when a roving reader moves to a new location. Reader is the primary entity and ReaderArrived events are published according to the following topic structure and payload.
{OrganisationID}/ReaderArrived/{ReaderID}
ReaderOnline events occur when a reader comes online. Reader is the primary entity and ReaderOnline events are published according to the following topic structure and payload.
{OrganisationID}/ReaderOnline/{ReaderID}
ReaderOffline events occur when a reader goes offline. Reader is the primary entity and ReaderOffline events are published according to the following topic structure and payload.
{OrganisationID}/ReaderOffline/{ReaderID}