Ecosyste.ms: Awesome
An open API service indexing awesome lists of open source software.
https://github.com/wolkabout/wolkgatewaymodule-sdk-cpp
SDK for connecting devices to WolkAbout IoT Platform over WolkGateway.
https://github.com/wolkabout/wolkgatewaymodule-sdk-cpp
Last synced: 5 days ago
JSON representation
SDK for connecting devices to WolkAbout IoT Platform over WolkGateway.
- Host: GitHub
- URL: https://github.com/wolkabout/wolkgatewaymodule-sdk-cpp
- Owner: Wolkabout
- License: apache-2.0
- Created: 2018-03-12T13:11:23.000Z (over 6 years ago)
- Default Branch: master
- Last Pushed: 2021-12-14T12:52:30.000Z (almost 3 years ago)
- Last Synced: 2024-03-27T05:59:29.242Z (8 months ago)
- Language: C++
- Homepage:
- Size: 600 KB
- Stars: 2
- Watchers: 4
- Forks: 0
- Open Issues: 0
-
Metadata Files:
- Readme: README.md
- License: LICENSE
Awesome Lists containing this project
README
# WolkGatewayModule SDK C++
WolkAbout C++11 Connector library for connecting devices to WolkAbout Gateway.
Supported protocol(s):
* JSON_PROTOCOL
Installing from source
----------------------
This repository must be cloned from the command line using:
```sh
git clone --recurse-submodules https://github.com/Wolkabout/WolkGatewayModule-SDK-Cpp.git
```
Prerequisite
------
Following tools/libraries are required in order to build WolkAbout C++ connector
* cmake - version 3.5 or later
* autotools
* autoconf
* libtool
* m4
* zlib1g-dev
* openssl
Former can be installed on Debian based system from terminal by invoking
```sh
apt-get install autotools-dev autoconf libtool m4 zlib1g-dev cmake libssl-dev
```
Afterwards dependencies are built, and Makefile build system is generated by invoking
`./configure`
Generated build system is located inside 'out' directory
WolkAbout C++ Connector library, and example are built from 'out' directory by invoking
`make` in terminal. To make tests, you need to invoke `make tests`.
Example Usage
-------------
**Establishing connection with WolkAbout IoT platform:**
```cpp
wolkabout::Device device("DEVICE_KEY", "DEVICE_PASSWORD", {"ACTUATOR_REFERENCE_ONE", "ACTUATOR_REFERENCE_TWO"});
std::unique_ptr wolk =
wolkabout::Wolk::newBuilder()
.actuationHandler([](const std::string& deviceKey, const std::string& reference, const std::string& value) -> void {
// TODO Invoke your code which activates actuator of specified device.
std::cout << "Actuation request received - Key: " << deviceKey << " Reference: " << reference << " value: " << value << std::endl;
})
.actuatorStatusProvider([](const std::string& deviceKey, const std::string& reference) -> wolkabout::ActuatorStatus {
// TODO Invoke code which reads the state of the actuator of specified device.
if (deviceKey == "DEVICE_KEY" && reference == "SWITCH_ACTUATOR_REF") {
return wolkabout::ActuatorStatus("true", wolkabout::ActuatorStatus::State::READY);
return wolkabout::ActuatorStatus("", wolkabout::ActuatorStatus::State::READY);
})
.configurationHandler([](const std::map& configuration) -> void {
// TODO invoke code which sets device configuration
})
.configurationProvider([]() -> const std::map& {
// TODO invoke code which reads device configuration
return std::map();
})
.deviceStatusProvider([](const std::string& deviceKey) -> wolkabout::DeviceStatus {
// TODO Invoke code which reads the status of specified device.
if (deviceKey == "DEVICE_KEY")
{
return wolkabout::DeviceStatus::CONNECTED;
}
return wolkabout::DeviceStatus::OFFLINE;
})
.build();
wolk->connect();
```
**Creating devices:**
```cpp
wolkabout::SensorManifest temperatureSensor{"Temperature", // name
"TEMPERATURE_REF", // reference
"Temperature sensor", // description
"℃", // unit
"TEMPERATURE", // reading type
wolkabout::SensorManifest::DataType::NUMERIC, // data type
1, // percision
-273.15, // min value
100000000}; // max value
wolkabout::SensorManifest pressureSensor{"Pressure",
"PRESSURE_REF",
"Pressure sensor",
"mb",
"PRESSURE",
wolkabout::SensorManifest::DataType::NUMERIC,
1,
0,
1100};
wolkabout::SensorManifest accelerationSensor{"Acceleration",
"ACCELEROMETER_REF",
"Acceleration sensor",
"m/s²",
"ACCELEROMETER",
wolkabout::SensorManifest::DataType::NUMERIC,
1,
0,
20000,
"%", // delimiter
{"x", "y", "z"}}; // labels
wolkabout::ActuatorManifest switchActuator{"Switch",
"SWITCH_ACTUATOR_REF",
"Switch actuator",
"",
"SW",
wolkabout::ActuatorManifest::DataType::BOOLEAN,
1,
0,
1};
wolkabout::AlarmManifest highHumidityAlarm{"High Humidity", // name
wolkabout::AlarmManifest::AlarmSeverity::ALERT, // severity
"HUMIDITY_ALARM_REF", // reference
"High Humidity", // message
"High Humidity alarm"}; // description
wolkabout::DeviceManifest deviceManifest1{"DEVICE_MANIFEST_NAME",
"DEVICE_MANIFEST_DESCRIPTION",
"JsonProtocol",
"",
{},
{temperatureSensor, pressureSensor},
{},
{switchActuator}};
wolkabout::Device device1{"DEVICE_NAME", "DEVICE_KEY", deviceManifest};
wolk->addDevice(device);
```
**Publishing sensor readings:**
```cpp
wolk->addSensorReading("DEVICE_KEY", "TEMPERATURE_REF", 23.4);
wolk->addSensorReading("DEVICE_KEY", "PRESSURE_REF", 1080);
wolk->addSensorReading("DEVICE_KEY_2", "ACCELEROMETER_REF", {0, -5, 10});
```
**Publishing actuator statuses:**
```cpp
wolk->publishActuatorStatus("DEVICE_KEY", "SWITCH_ACTUATOR_REF");
```
This will invoke the ActuationStatusProvider to read the actuator status,
and publish actuator status.
**Publish device configuration to platform:**
```cpp
wolk->publishConfiguration("DEVICE_KEY");
```
This will invoke the ConfigurationProvider to read the configuration and publish it.
**Publishing alarms:**
```cpp
wolk->addAlarm("DEVICE_KEY", "HUMIDITY_ALARM_REF", "ALARM_VALUE");
```
**Data publish strategy:**
Sensor readings, and alarms are pushed to WolkAbout IoT platform on demand by calling
```cpp
wolk->publish();
wolk->publish("DEVICE_KEY");
```
Publishing without providing device key publishes all available data,
whereas publishing with device key only data for the specified device is published
Actuator statuses are published automatically by calling:
```cpp
wolk->publishActuatorStatus("DEVICE_KEY", "ACTUATOR_REFERENCE_ONE");
```
Configuration is published automatically by calling:
```cpp
wolk->publishConfiguration("DEVICE_KEY");
```
**Disconnecting from the platform:**
```cpp
wolk->disconnect();
```
**Data persistence:**
WolkAbout C++ Connector provides mechanism for persisting data in situations where readings can not be sent to WolkAbout Gateway.
Persisted readings are sent to WolkAbout Gateway once connection is established.
Data persistence mechanism used **by default** stores data in-memory.
In cases when provided in-memory persistence is suboptimal, one can use custom persistence by implementing wolkabout::Persistence interface,
and forwarding it to builder in following manner:
```cpp
std::unique_ptr wolk =
wolkabout::Wolk::newBuilder()
.actuationHandler([](const std::string& deviceKey, const std::string& reference, const std::string& value) -> void {
// TODO Invoke your code which activates actuator of specified device.
std::cout << "Actuation request received - Key: " << deviceKey << " Reference: " << reference << " value: " << value << std::endl;
})
.actuatorStatusProvider([](const std::string& deviceKey, const std::string& reference) -> wolkabout::ActuatorStatus {
// TODO Invoke code which reads the state of the actuator of specified device.
if (deviceKey == "DEVICE_KEY" && reference == "SWITCH_ACTUATOR_REF") {
return wolkabout::ActuatorStatus("true", wolkabout::ActuatorStatus::State::READY);
return wolkabout::ActuatorStatus("", wolkabout::ActuatorStatus::State::READY);
})
.configurationHandler([](const std::map& configuration) -> void {
// TODO invoke code which sets device configuration
})
.configurationProvider([]() -> const std::map& {
// TODO invoke code which reads device configuration
return std::map();
})
.deviceStatusProvider([](const std::string& deviceKey) -> wolkabout::DeviceStatus {
// TODO Invoke code which reads the status of specified device.
if (deviceKey == "DEVICE_KEY")
{
return wolkabout::DeviceStatus::CONNECTED;
}
return wolkabout::DeviceStatus::OFFLINE;
})
.withPersistence(std::make_shared()) // Enable data persistance via custom persistence mechanism
.build();
wolk->connect();
```
For more info on persistence mechanism see wolkabout::Persistence and wolkabout::InMemoryPersistence classes
**Firmware Update**
WolkAbout C++ Connector provides mechanism for updating devices' firmware.
To enable firmware update one must provide implementation for wolkabout::FirmwareInstaller and wolkabout::FirmwareVersionProvider
See code snippet below on how to enable device firmware update for devices.
```c++
class CustomFirmwareInstaller: public wolkabout::FirmwareInstaller
{
public:
void install(const std::string& deviceKey, const std::string& firmwareFile,
std::function onSuccess,
std::function onFail) override
{
// Mock install
std::cout << "Updating firmware for device " << deviceKey << " with file " << firmwareFile << std::endl;
onSuccess(deviceKey);
}
bool abort(const std::string& deviceKey) override
{
// Mock abort
std::cout << "Aborting firmware installation for device " << deviceKey << std::endl;
return false;
}
};
class CustomFirmwareVersionProvider : public wolkabout::FirmwareVersionProvider
{
public:
std::string getFirmwareVersion(const std::string& deviceKey)
{
// return firmware version for the device
return "1.0";
}
};
auto installer = std::make_shared();
auto provider = std::make_shared();
auto builder = wolkabout::Wolk::newBuilder()
.actuationHandler([](const std::string& deviceKey, const std::string& reference, const std::string& value) -> void {
// TODO Invoke your code which activates actuator of specified device.
std::cout << "Actuation request received - Key: " << deviceKey << " Reference: " << reference << " value: " << value << std::endl;
})
.actuatorStatusProvider([](const std::string& deviceKey, const std::string& reference) -> wolkabout::ActuatorStatus {
// TODO Invoke code which reads the state of the actuator of specified device.
if (deviceKey == "DEVICE_KEY" && reference == "SWITCH_ACTUATOR_REF") {
return wolkabout::ActuatorStatus("true", wolkabout::ActuatorStatus::State::READY);
return wolkabout::ActuatorStatus("", wolkabout::ActuatorStatus::State::READY);
})
.configurationHandler([](const std::map& configuration) -> void {
// TODO invoke code which sets device configuration
})
.configurationProvider([]() -> const std::map& {
// TODO invoke code which reads device configuration
return std::map();
})
.deviceStatusProvider([](const std::string& deviceKey) -> wolkabout::DeviceStatus {
// TODO Invoke code which reads the status of specified device.
if (deviceKey == "DEVICE_KEY")
{
return wolkabout::DeviceStatus::CONNECTED;
}
return wolkabout::DeviceStatus::OFFLINE;
})
.withFirmwareUpdate(installer, provider)
.build();
```