Kuzzle is an open-source backend. It can be installed on-premises, and it features a multi-protocol API allowing to integrate IoT devices.
This article explains how to develop an IoT application using an ESP32 module and Kuzzle, communicating using MQTT.
Specifically, we will build a basic IoT device featuring a RGB LED, and change its colors using Kuzzle's Admin Console.
The following guide allows you to quickly run a Kuzzle instance: Getting Started
By default, Kuzzle does not support MQTT communication, but it features an extensible protocol system: install our official MQTT Protocol to add MQTT capabilities.
For this tutorial, you need the following components:
- 1 × ESP32 DevKit C
- 1 × USB A / micro USB B cable
- 1 × PC running Linux
- 1 × RGB LED
- 3 × 100 ohm resistor
Preparing the Kuzzle IoT Environment
Our IoT application requires a simple storage setup: a data index, data collections and their corresponding mappings.
Read our persistence layer documentation for more information.
The script iot-deploy creates the necessary storage structures in a Kuzzle instance.
Once you have run the script, open the administration console. There should now be an iot index containing these 3 collections:
- device-info: contains information about devices (proprietary, friendly name, ...)
- device-state: keeps track of the device state history. Also used to subscribe to state changes
- fw-update: keeps track of available firmware updates
This first tutorial only uses the device-state collection.
Preparing the ESP32 Development Environment
First, install the ESP32 toolchain and SDK: https://esp-idf.readthedocs.io/en/latest/get-started/index.html
Then, create your project by cloning Espressif's application template:
Make sure you are able to build and flash the application to your ESP32 module.
To allow your application to communicate with Kuzzle, you need 2 components:
- esp-mqtt: MQTT communication layer library for ESP32
- kuzzle-esp32: custom component, for communicating with Kuzzle over MQTT
Clone the esp-mqtt and kuzzle-esp32 components in the components folder to add them to your project:
(components must be located in the project's components subfolder, as explained in the Espressif build system documentation)
Your project folder structure should now look like this:
Wiring the RGB LED to ESP32 DevKit C
he RGB LED will be driven by GPIO 25, 26 and 27.
The following code snippets are excerpts. The whole source code is available in the src folder of this repository.
To connect the device to your local WIFI network, you need to configure its credentials information.
To do so, update the app_main() function, in the file src/main/main.c:
Once connected to the WIFI netwok, initialize the Kuzzle library:
LED Driver Code
Initialize the LED driver:
The device keeps track of its current state (ON/OFF, RGB color...):
Applying new state from Kuzzle to hardware
When the state of the RGB light is changed in Kuzzle, our state callback is called.
It then updates the LED driver accordingly:
Get the Code
The whole source code for the rgb light is available in the src folder.
Visualize the device state
When booting, the device publishes its current state to Kuzzle. It can then be viewed in the administration console, as shown in the screenshot above:
- Open Kuzzle's Admin Console and connect it to your Kuzzle instance
- Open the iot index, and the device-state collection in it
- There should be a document representing the state of your RBG light
- Note the device_id value down, as it will be used in the next step (it is built using the device MAC address)
Control the device state
The device has subscribed to new documents written in the device-state collection: whenever a new document is created, Kuzzle notifies the device about it, in real-time.
We'll propose a partial state change to our device, to modify its color. The device then decides whether it accepts the new value, or not. If the change is accepted, the device sends its updated complete state to Kuzzle.
Click on the Create button and enter the following JSON:
Once you click on the Create button to validate your document, the RGB light should turn to bright blue. When you refresh your browser, you should now have 3 documents:
- The initial one with r,g and b all set to 255,
- The partial one you entered, turning r to 0
- The new complete state published by the device with r set to 0 and g and b still set to 255