servIoTicy allows for the interaction with the platform through protocols that are not HTTP/REST. Support for MQTT, STOMP-over-TCP and STOMP-over-WS is provided. This page describes how to leverage this protocols for easy interaction with the platform.
They can be used in three different forms:
- For cient/server interaction with servIoTicy, emulating the behaviour of the REST API
- For data streams subscriptions: A client can subscribe to a data stream and receive all the updates being send to a SO stream. Note that given that the platform provides eventual consistency, this is a good way to get most recent updates for a SO stram asynchronously and in real-time. Polling is not recommended.
- For actuations: This is described in a separate document here. Some information contained in this page is still relevant.
Information for communicating with the platform using MQTT/WS/TCP:
- MQTT Endpoint: api.servioticy.com:1883
- STOMP/TCP Endpoint: api.servioticy.com:1883
- STOMP/WS Endpoint: api.servioticy.com:61623
- User: compose
- Password: shines
- Sending data from the Web Object: “<API_TOKEN>/from” (MQTT) – “/topic/<API_TOKEN>.from” (STOMP)
- Sending data to the Web Object (HTTP responses): “<API_TOKEN>/to” (MQTT) – “/topic/<API_TOKEN>.to” (STOMP)
- Updates produced by subscriptions: “<API_TOKEN>/<SO_Id>/streams/<streamId>/updates” (MQTT) – “/topic/<API_TOKEN>.<SO_Id>.streams.<streamId>.updates” (STOMP)
Subscribing to data streams:
We would POST the following JSON document to the URL:
Note that the filed “destination” is here the API_TOKEN of the subscriber.
REST API is mapped on top of a topic using the following structure (note the use of an optional “messageId” field to match queries and responses):
An example of how to to list all the SOs belonging to a user:
An example of how to push data to the platform:
A sample python code for pushing data to the platform (based on Paho):
The actual Node.js multi-protocol bridge between the broker and the platform:
Note that it uses STOMP+TCP, and therefore uses a topic notation that is: “/topic/field1.field2.field3….”