Protocols

VizIoT supports two types of device connection, one-way and two-way.

One-way - the server simply receives data from the device and is implemented by sending HTTP GET requests from the device to the server.

Two-way - the server receives data from the device and send commands to the device and is implemented through an MQTT broker.

HTTP GET requests

The Hypertext Transfer Protocol (HTTP) — application layer protocol for data transmission. Messages are exchanged according to the usual request-response scheme. HTTP resources are identified and located on the network by Uniform Resource Locators (URLs). Each HTTP message consists of three parts, which are transmitted in the specified order:

  • Starting line — defines the type of message;
  • Headers — characterize the message body, transmission parameters and other information;
  • Message Body — message data. Must be separated from headers by an empty line. The body of the message may be missing, but the start line and header are required.

More information about the protocol can be found here https://www.w3.org/.

Most devices have already implemented the HTTP protocol:

  • Arduino Uno + Arduino Ethernet Shield – library Ethernet.h.
  • Arduino Uno + Arduino WiFi Shield – library WiFi.h.
  • Arduino Uno + SIM800 – library TinyGsmClient.h and ArduinoHttpClient.h.
  • ESP8266 (development environment Arduino IDE) – library ESP8266WiFi.h and WiFiClient.h.
  • Raspberry Pi or another Linux computer – cURL, Python (library urllib), Node.js (library http).

Basic Requirements (All requests must meet the requirements otherwise they will be rejected.):

  • the length of the request must be less than 2083 characters;
  • the request body is empty;
  • keys are written in Latin;
  • values must be integer or floating point;
  • required parameters must be present;
  • if the date parameter is not passed, requests should be at most once per second.

Mandatory parameters of a GET request:

  • URL request address https://viziot.com/update or http://viziot.com/update
  • key: your device access key
  • pass: your device access password

Optional parameters:

  • date: used to indicate date and time. The value must be specified in the format Unix Timestamp UTC+0. If you do not pass the parameter, then the time of data recording on the server will be used.
  • All other parameters are considered device parameters.

Request example: https://viziot.com/update?key=123456789ABCDEFG&pass=123456789ABCDEFGabcd&date=1527897593

MQTT

MQTT (Message Queue Telemetry Transport) — simplified network protocol, runs over TCP / IP. Used to exchange messages between devices on a publisher-subscriber basis. Capabilities:

  • Easy to use. The protocol is a software block without unnecessary functionality that can be easily integrated into any complex system.
  • The publisher-subscriber design pattern is handy for most sensor solutions. Allows devices to communicate and post messages that were not previously known or predetermined.
  • Easy to administer.
  • Reduced the load on the communication channel.
  • Work in conditions of constant communication loss or other problems on the line.
  • No restrictions on the format of the transmitted data.

More information about the protocol can be found here http://mqtt.org/.

libraries for running MQTT on different devices:

  • Arduino Uno + Arduino Ethernet Shield – library Ethernet.h and PubSubClient.h.
  • Arduino Uno + Arduino WiFi Shield – library WiFi.h and PubSubClient.h.
  • Arduino Uno + SIM800 – library TinyGsmClient.h and PubSubClient.h.
  • ESP8266 (среда разработки Arduino IDE) – library ESP8266WiFi.h, WiFiClient.h and PubSubClient.h.
  • Raspberry Pi or another Linux computer – Python (library paho-mqtt), Node.js (library mqtt).

To transfer data via the MQTT protocol, you need to connect to our MQTT broker.

Connection parameters:

  • SERVER: viziot.com
  • PORT: 48651
  • CLIENTID: any text (can match USERNAME)
  • USERNAME: access key that is generated when the device is created
  • PASSWORD: access password that is generated when the device is created
  • Topic for sending data: /devices/USERNAME/packet
  • Topic for getting data: /devices/USERNAME/param/+

When publishing data, the payload must be in JSON format. for example, {"date":"1527897593","rsst":"-64","t1":"28.90"}.

To specify the date and time, use the date key with a value in the format Unix Timestamp UTC+0. If you do not pass the parameter, then the time of data recording on the server will be used. All other parameters are considered device parameters.