Astarte properties example

This example will guide you through setting up a simple ESP32 application running the Astarte SDK and interacting with a local instance of Astarte.

The example device will, by default perform the following actions:

Connect to a local Astarte instance using a manually generated device ID and credential secret.
Set some predefined device owned properties to predefined values.
When the server will set a new value for any of the server-owned properties, the device will react by setting new values for some of the device-owned properties.

We will assume you already performed the common configuration and satisfy the common prerequisites. You flashed your device with the example firmware and connection between the device and the Astarte instance has been established.

Interaction witt the Astarte instance

We will use two sub-commands of astartectl in this example, send-data, and get-samples. With send-data we can publish new values on a server-owned interface. The syntax is the following:

Plaintext

astartectl appengine --appengine-url http://localhost:4002/ --realm-key <REALM>_private.pem \
    --realm-name <REALM> devices send-data <DEVICE_ID>                                      \
    --interface-type individual-properties --payload-type boolean                           \
    org.astarteplatform.esp32.examples.ServerProperties1 /42/boolean_endpoint <VALUE>

Where <TOKEN> is the shell variable containing the token, <REALM_NAME> is your realm name, and <API_URL> is the API URL as found on the astarte cloud console. <DEVICE_NAME> is the device ID to send the data to, and <VALUE> is the value to send. In this example the data to send is in boolean format, so substitute <VALUE> with true or false.

The device will react to this event by mirroring the received value on a device owned interface.

We can check if the publish from the device has been correctly received on the server using get-samples as follows:

Plaintext

astartectl appengine --appengine-url http://localhost:4002/ --realm-key <REALM>_private.pem \
    --realm-name <REALM> devices get-samples <DEVICE_ID>                                    \
    org.astarteplatform.esp32.examples.DeviceProperties1 /24/boolean_endpoint -c 1

This will print the latest published data from the device that has been stored in the Astarte Cloud instance. To print a longer history of the published data change the number in -c 1 to the history length of your liking.

The command get-samples can be also used to check if the device has set correctly its device owned properties.

Additional example configuration

One of the main use cases for this example is to observe how property retention works between different reboots of a device. For this reason, a set of preprocessor defines has been placed at the beginning of the file. By enabling or disabling them more complex behaviors can be simulated.

One important consideration for this purpose is that using idf.py build flash monitor will not change the content of the NVS flash partition where the properties are stored. The example can be built and flashed over the device with different configurations without changing the set of properties already stored.

Here is a short description of each define and what it does:

#define SET_DEVICE_PROPERTIES: set a few device-owned properties with predefined values
#define UNSET_DEVICE_PROPERTIES: unset a few device-owned properties
#define SET_DEVICE_PROPERTY_TWICE: try to set one device-owned property twice in a row with the same value
#define REPLY_TO_SERVER_PROPERTY_INTERFACE1: upon reception of a set message for a specific server property of interface 1, react setting a device property for the same interface.
#define REPLY_TO_SERVER_PROPERTY_INTERFACE2: upon reception of a set message for a specific server property of interface 2, react setting a device property for the same interface.

One simple behavior can be simulated by first flashing the device with the SET_DEVICE_PROPERTIES define enabled. Observe how the properties are set correctly in the Astarte instance. Then comment out the preprocessor define, and flash the device once more. Observe how the device properties remain set even after multiple reboots. Now enable UNSET_DEVICE_PROPERTIES, build and flash the example once more and observe how some device properties are unset. If the device is power cycled without flashing the firmware the calls to the unset method will print a warning as the property is already unset.