Ecosyste.ms: Awesome

An open API service indexing awesome lists of open source software.

Awesome Lists | Featured Topics | Projects

https://github.com/wolkabout/wolkconnect-cpp

C++11 library which provides easy connectivity to WolkAbout IoT Platform.
https://github.com/wolkabout/wolkconnect-cpp

client-library connectivity cpp fota iot iot-platform wolkabout wolkconnect

Last synced: about 2 months ago
JSON representation

C++11 library which provides easy connectivity to WolkAbout IoT Platform.

Awesome Lists containing this project

README 

        
```

██╗    ██╗ ██████╗ ██╗     ██╗  ██╗ ██████╗ ██████╗ ███╗   ██╗███╗   ██╗███████╗ ██████╗████████╗

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

██║ █╗ ██║██║   ██║██║     █████╔╝ ██║     ██║   ██║██╔██╗ ██║██╔██╗ ██║█████╗  ██║        ██║   

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

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

 ╚══╝╚══╝  ╚═════╝ ╚══════╝╚═╝  ╚═╝ ╚═════╝ ╚═════╝ ╚═╝  ╚═══╝╚═╝  ╚═══╝╚══════╝ ╚═════╝   ╚═╝   

                                                                                                 

                                                                          ██████╗██████╗ ██████╗ 

                                                                         ██╔════╝██╔══██╗██╔══██╗

                                                                   █████╗██║     ██████╔╝██████╔╝

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

                                                                         ╚██████╗██║     ██║     

                                                                          ╚═════╝╚═╝     ╚═╝     

```



----

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:



```sh

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:



```shell

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:



```shell

cd WolkConnect-Cpp # Change the directory if you haven't

./configure.sh

```



Generated build system is located inside `out` directory



```shell

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](./examples/simple/Application.cpp) - Simplest PUSH device just sending data periodically.

- [Register Example](./examples/register_feed_and_attribute/Application.cpp) - Device registering its own feed and

  attribute.

- [Pull Example](./examples/pull/Application.cpp) - Device that is periodically connected to the platform and does data

  PULL when online.

- [Full Feature Example](./examples/full_feature/Application.cpp) - A fully featured device with File Management and

  Firmware Update functionality.



## Basic Guide



**Establishing connection with WolkAbout IoT platform:**



```c++

// 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:



```c++

// 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**



```c++

wolk->connect();



wolk->disconnect();

```



**Publishing feed values:**



```c++

wolk->addReading("T", 20.4);

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

```



**Registering feeds and attributes**



```c++

// 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**



```c++

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

```



**Updating parameters**


*Be careful with updating parameters!*



```c++

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:



```c++

wolk->pullFeedValues();

wolk->pullParameters();

```