██╗    ██╗ ██████╗ ██╗     ██╗  ██╗ ██████╗ ██████╗ ███╗   ██╗███╗   ██╗███████╗ ██████╗████████╗
██║    ██║██╔═══██╗██║     ██║ ██╔╝██╔════╝██╔═══██╗████╗  ██║████╗  ██║██╔════╝██╔════╝╚══██╔══╝
██║ █╗ ██║██║   ██║██║     █████╔╝ ██║     ██║   ██║██╔██╗ ██║██╔██╗ ██║█████╗  ██║        ██║   
██║███╗██║██║   ██║██║     ██╔═██╗ ██║     ██║   ██║██║╚██╗██║██║╚██╗██║██╔══╝  ██║        ██║   
╚███╔███╔╝╚██████╔╝███████╗██║  ██╗╚██████╗╚██████╔╝██║ ╚████║██║ ╚████║███████╗╚██████╗   ██║   
 ╚══╝╚══╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═══╝╚══════╝ ╚═════╝   ╚═╝   
                                                                                                 
                                                                          ██████╗██████╗ ██████╗ 
                                                                         ██╔════╝██╔══██╗██╔══██╗
                                                                   █████╗██║     ██████╔╝██████╔╝
                                                                   ╚════╝██║     ██╔═══╝ ██╔═══╝ 
                                                                         ╚██████╗██║     ██║     
                                                                          ╚═════╝╚═╝     ╚═╝     

---

WolkAbout C++11 Connector library for connecting devices to WolkAbout IoT platform instance .

Supported protocol:

• Wolkabout Protocol/Digital Twin (22.GA)

Installing from source

This repository must be cloned from the command line using:

git clone --recurse-submodules https://github.com/Wolkabout/WolkConnect-Cpp.git

Prerequisite

Following tools/libraries are required in order to build WolkAbout C++ connector:

• CMake (version 3.5+)
• GNU C++ Compiler
• LibSSL
• PThread

And all of them can be installed this way:

apt update
apt install cmake g++ libssl-dev libpthread-stubs0-dev

Configuring & Building

Afterwards dependencies are installed, the Makefile build system can be generated by invoking:

cd WolkConnect-Cpp # Change the directory if you haven't
./configure.sh

Generated build system is located inside out directory

cd out # Change the directory if you haven't
make -j$(nproc) # Make the library
make tests -j$(nproc) # Make and run the tests
make full_example/pull_example/register_example/simple_example -j$(nproc) # Make any of the examples

Example Usage

There are 4 examples that each show some other functionalities of the WolkConnect-Cpp:

• Simple Example - Simplest PUSH device just sending data periodically.
• Register Example - Device registering its own feed and attribute.
• Pull Example - Device that is periodically connected to the platform and does data PULL when online.
• Full Feature Example - A fully featured device with File Management and Firmware Update functionality.

Basic Guide

Establishing connection with WolkAbout IoT platform:

// Defining device information
auto device = wolkabout::Device(DEVICE_KEY, DEVICE_PASSWORD, wolkabout::OutboundDataMode::PUSH /* or PULL */);

// Creating the Wolk instance
auto wolk = wolkabout::Wolk::newBuilder(device).host(PLATFORM_HOST).build();

// Connecting to the platform
wolk->connect();

Here we're going to list out all the WolkBuilder methods. Note, these all are optional calls, all of them have some default value already set:

// Creating the Wolk instance
auto wolkBuilder = wolkabout::Wolk::newBuilder(device)
        .host(PLATFORM_HOST) // Sets the MQTT broker path - used to connect with the platform
        .caCertPath(CA_CERT_PATH) // Path to a `ca.crt` file - used to establish a secure connection with the platform
        .feedUpdateHandler(...) // Sets the callback which will receive FeedValues updates sent by the platform
        .parameterHandler(...) // Set the callback which will receive Parameter updates sent by the platform
        .withPersistence(...) // Sets the default message persistence - used while the connection is offline
        .withDataProtocol(...) // Sets a custom DataProtocol implementation
        .withFileTransfer(...) // Enables the FileManagement functionality with only platform transfers enabled - Use only if device is PUSH
        .withFileURLDownload(...) // Enables the FileManagement functionality with the File URL downloading enabled (and platform transfers optionally) - Use only if device is PUSH
        .withFileListener(...) // Sets an object that will receive information about newly added/removed files - Use only if device is PUSH
        .withFirmwareUpdate(...) // Enables the FirmwareUpdate functionality in either FirmwareInstall mode (for PUSH devices) or FirmwareParametersListener (for PULL devices).

Connecting and disconnecting

wolk->connect();

wolk->disconnect();

Publishing feed values:

wolk->addReading("T", 20.4);
wolk->addReading("SW", false, 1638537962000); // Optional timestamp value in milliseconds

Registering feeds and attributes

// Defining a feed
auto feed = Feed{"New Feed Name", "NFN", wolkabout::FeedType::IN, wolkabout::Unit::NUMERIC};
wolk->registerFeed(feed);

// Defining an attribute
auto attribute = wolkabout::Attribute{"New Attribute", wolkabout::DataType::NUMERIC,
                                      std::to_string(std::chrono::system_clock::now().time_since_epoch().count())};
wolk->addAttribute(attribute);

Removing feeds

wolk->removeFeed("NFN"); // Reference of the feed we registered above.

Updating parameters
Be careful with updating parameters!

wolk->updateParameter(wolkabout::ParameterName::EXTERNAL_ID, "Device ID");

Pulling feed values & parameters

If you have set a FeedValueHandler using .feedUpdateHandler(), or ParameterHandler using .parameterHandler(), you can use pull methods to receive values:

wolk->pullFeedValues();
wolk->pullParameters();