platformio_usage.md

Usage with PlatformIO

Installation

An often more straightforward alternative to the Arduino IDE is the PlatformIO framework. It is integrated well into Visual Studio Code on all platforms and can also be used via a terminal, which is the recommended approach on Linux/Unix systems and is detailed in the following.

Install PlatformIO Core by following the official instructions.

Similarly, this library is not yet easily available on platformio. Therefore, we recommend cloning the library code to your platformio project's /lib folder:

git clone git@gitlab.sensirion.lokal:MSO-SW/unified-prototyping-toolkit/arduino-upt-mqtt-client.git lib/arduino-upt-mqtt-client

Finally, it is possible to run the example by building and flashing it, and then monitoring the device:

pio run -e basicUsage -t upload && pio device monitor

Additional insight into the program's actions can be gained by enabling logging messages, which can be done by utilizing the develop environment and setting the desired logging level in platformio.ini.

Configuration

PlatformIO users benefit of a quality-of-life feature: connection parameters (such as WiFi AP SSID, WiFi password, MQTT broker domain etc...) can be specified in mqtt_config.json. A python script (set_env_vars_from_json.py) will then be exectuted during the build process, setting appropriate environment variables. The following macros become available in the code:

WIFI_SSID_OVERRIDE
WIFI_PW_OVERRIDE

MQTT_LWT_TOPIC_OVERRIDE
MQTT_LWT_MSG_OVERRIDE
MQTT_QOS_OVERRIDE
MQTT_RETAIN_FLAG_OVERRIDE
MQTT_BROKER_FULL_URI_OVERRIDE
MQTT_BROKER_CERTIFICATE_OVERRIDE
MQTT_USE_SSL_OVERRIDE

In case the definition of the environment variables fails, the program reverts to the definitions in src/mqtt_cfg.h and src/wifi_cfg.h for MQTT and WiFi params, respectively. Insights of the build process can be gained by examining the logs/buildlog.log file generated by pio run, which contains an environment dump.

The pio run command also automatically copies the example .inoscript file to a .cpp file to successfully compile.

This library was developed utilizing the ESP logging library. To see info messages, be sure to set the desired verbosity level (see platformio.ini).