The Losant Arduino MQTT client provides a simple way for your Arduino-based devices to connect and communicate with the Losant Enterprise IoT Platform.
Installation for PlatformIO
The latest stable version is available in PlatformIO and can be installed adding dependency (lib_deps) to your project configuration file platformio.ini
[env:myenv]
platform = ...
board = ...
framework = arduino
lib_deps = losant-mqtt-arduinoUsing PlatformIO IDE requires a single include directive:
#include <Losant.h>The Losant Arduino MQTT client is distributed as an Arduino library. It can be installed in two ways:
- Download a zip of this repository and include it into your Arduino Sketch. Select
Sketch -> Include Library -> Add .ZIPlibrary from the Arduino menu. - Clone the contents of the repository into Arduino's library folder on your system. This location changes based on OS, but on Mac and Windows it's typically at
Documents / Arduino / libraries.
Once installed, using the library requires a single include directive.
#include <Losant.h>The Losant Arduino MQTT client depends on ArduinoJson and MQTT Client. These libraries must be installed before using the Losant MQTT client. When using Platform.io, these dependencies are installed automatically, but when using the Arduino IDE they must be installed manually. Please refer to their documentation for specific installation instructions.
You’ll possibly hit the default MQTT packet size limit defined in the Losant Arduino MQTT Client library. Unfortunately the packet is blocked before reaching any of your code, so it’s hard to debug. It simply looks like the command was never received. For example:
{ "foo" : "bar" } works, whereas { "somethingLarger" : "with a longer value" } doesn’t work. This is because the default packet size is 256, which provides enough room for the command meta info and a small payload. Fortunately, this is easily fixed by defining a larger value for MQTT_MAX_PACKET_SIZE in your Arduino code.
For specific examples for various boards, please refer to the examples folder.
State and commands are the main two communication constructs of the Losant platform. A state represents a current snapshot of the device at a moment in time. On typical IoT devices, attributes of a device's state typically correspond to individual sensors (e.g. "temperature", "light level", or "sound level"). States can be reported to Losant as often as needed.
Commands allow you to control your device remotely. What commands a device
supports is entirely up to the device's firmware. A command is comprised of
a name and an optional payload. The name indicates what command the device
should invoke (e.g. "start recording") and the payload provide parameters
to the command (e.g. { "resolution": 1080 }).
The LosantDevice class represents a single connection to the Losant platform. Use this class to report state information and subscribe to commands.
Losant device constructor. The only parameter is the device ID. A Losant device ID can be obtained by registering your device using the Losant dashboard.
LosantDevice device('my-device-id');Losant device constructor that does not require a device ID. The ID can be set at a later time using setId() The ID must be set before connect() can be called.
LosantDevice device;Gets the device ID that was set through the constructor or setId() call.
LosantDevice device('my-device-id');
const *char deviceId = device.getId();Sets the device ID. Typically called if the ID was not passed through the constructor.
LosantDevice device;
device.setId('my-device-id');LosantDevice device('my-device-id');
const *char deviceId = device.getId();Creates an unsecured connection to the Losant platform.
WiFiClient client;
...
LosantDevice device('my-device-id');
device.connect(client, 'my-access-key', 'my-access-secret');Creates a TLS encrypted connection to the Losant platform.
WiFiSSLClient client;
...
LosantDevice device('my-device-id');
device.connectSecure(client, 'my-access-key', 'my-access-secret');Registers a function that will be called whenever a command is received from the Losant platform.
void handleCommand(LosantCommand *command) {
Serial.print("Command received: ");
Serial.println(command->name);
Serial.println(command->time);
// { "foo" : 10 }
JsonObject payload = *command->payload;
long bar = payload["foo"];
}
LosantDevice device('my-device-id');
device.connectSecure(client, 'my-access-key', 'my-access-secret');
device.onCommand(&handleCommand);The command callback function is passed a LosantCommand object with details
about the command. These include name, time, and payload. name is a
string containing the command's name. time is the UTC ISO string of the date
and time when the command was received by the Losant platform. payload is a
JsonObject with whatever arguments was passed to the command when it was sent.
Sends a state update to Losant. The state of an object is defined as a simple Json object with keys and values. Refer to the ArduinoJson library for detailed documentation.
StaticJsonDocument<200> jsonBuffer;
JsonObject state = jsonBuffer.to<JsonObject>();
state["temperature"] = 72;
// Send the state to Losant.
device.sendState(state);Loops the underlying Client to perform any required MQTT communication. Must be called periodically, no less than once every few seconds.
device.loop();Copyright (c) 2023 Losant IoT, Inc