Webthing-CPP is a modern CPP/C++17 implementation of the WebThings API. Goal of the project is to offer an easy way to set up digital twins with web interface for arbitrary things by just specifying their properties, actions and events. This projects focus lies on an easy to use API heavily inspired by similar projects from the Java and Python world.
Webthing-CPP comes with MIT license without any warranty. DISCLAIMER: At the moment this project is in an early stage. Please make sure to perform sufficient number of tests if it suits your needs regarding stability before using it in production.
This project follows a header only approach to make integration into own projects easier. Nevertheless it relies on some dependencies to implement its features:
- µWebSockets is used as backing http/websocket server.
- nlohmann::json and json-schema-validator are used to make working with json more comfortable.
- mdns is used for easy service discovery.
- OpenSSL is used when SSL support is required.
The projects sources can be found in the include folder. Beside the library sources the project is shipped with some examples for demonstration purposes located in the examples folder. In addition some unit tests backed by Catch2 framework can be found in test folder. In tools folder there are some helpers available related to vcpkg, tests and certificates.
WT_USE_JSON_SCHEMA_VALIDATION
When WT_USE_JSON_SCHEMA_VALIDATION is defined Webthing-CPP will validate JSON input for thing properties and thing actions against JSON scheme defined by the thing description. Otherwise validation will be omitted.
WT_UNORDERED_JSON_OBJECT_LAYOUT
Webthing-CPP uses nlohmann::ordered_json as default json implementation. This specialization maintains the insertion order of object keys. By defining WT_UNORDERED_JSON_OBJECT_LAYOUT Webthing-CPP will use nlohmann::json as json implementation.
WT_WITH_SSL
By defining WT_WITH_SSL Webthing-CPP will use the uWS::SSLApp as backing webserver. When definition is missing it will use uWS::App.
Webthing-CPP uses cmake in conjunction with vcpkg as default build system. By default, the build system is configured to statically link all dependencies to build simple self-contained executables.
The build.sh script is a little helper to ensure cmake is called with correct parameters and vcpkg installs all required dependencies. For Windows users there is an alternative build.bat script available. Following arguments are supported:
clean
Deletes the build folder that cmake creates to ensure a fresh rebuild.
release
Use Release as cmake build type. Debug will be used as default.
with_ssl
Configures the project to support SSL for WebThingServer and installs additional required dependencies.
win32
Windows only: Use Win32 as target architecture. x64 will be used as default.
Build project with SSL support.
./build.sh clean release with_sslA self signed certificate for test purposes can be created by using the create-pems.sh script from the tools folder. This will create a key.pem as well as a cert.pem. Make sure to configure the WebThingServer with correct SSLOptions e.g.:
SSLOptions ssl_options;
ssl_options.key_file_name = "key.pem";
ssl_options.cert_file_name = "cert.pem";
ssl_options.passphrase = "1234";
auto server = WebThingServer::host(things)
.port(8888)
.ssl_options(ssl_options)
.build();At the moment three example applications are available.
- single-thing.cpp Shows how to set up a simple WebThing with two properties and an action.
- multiple-thing.cpp Shows how to host more then one WebThing in a single application. Things are a fake light and a fake humidity sensor.
- gui-thing.cpp Demonstrates how to embed a HTML GUI of a fake slot machine and how interact with it.
In this code-walkthrough we will set up a dimmable light and a humidity sensor (both using fake data, of course). All working examples can be found in the examples directory.
Imagine you have a dimmable light that you want to expose via the WebThings API. The light can be turned on/off and the brightness can be set from 0% to 100%. Besides the name, description, and type, a Light is required to expose two properties:
-
on: the state of the light, whether it is turned on or off- Setting this property via a
PUT {"on": true/false}call to the REST API toggles the light.
- Setting this property via a
-
brightness: the brightness level of the light from 0-100%- Setting this property via a PUT call to the REST API sets the brightness level of this light.
First we create a new Thing:
auto thing = make_thing("urn:dev:ops:my-lamp-1234", "My Lamp",
std::vector<std::string>({"OnOffSwitch", "Light"}),
"A web connected lamp");Now we can add the required properties.
The on property reports and sets the on/off state of the light. For this, we need to have a Value object which holds the actual state and also a method to turn the light on/off. For our purposes, we just want to log the new state if the light is switched on/off.
auto on_value = make_value(true, [](auto v){
logger::info("On-State is now " + std::string( v ? "on" : "off"));
});
link_property(thing, "on", on_value, {
{"@type", "OnOffProperty"},
{"title", "On/Off"},
{"type", "boolean"},
{"description", "Whether the lamp is turned on"}});The brightness property reports the brightness level of the light and sets the level. Like before, instead of actually setting the level of a light, we just log the level.
auto brightness_value = make_value(50, [](auto v){
logger::info("Brightness is now " + std::to_string(v));
});
link_property(thing, "brightness", brightness_value, {
{"@type", "BrightnessProperty"},
{"title", "Brightness"},
{"type", "integer"},
{"description", "The level of light from 0-100"},
{"minimum", 0},
{"maximum", 100},
{"unit", "percent"}});Now we can add our newly created thing to the server and start it:
// If adding more than one thing, use MultipleThings() with a name.
// In the single thing case, the thing's name will be broadcast.
WebThingServer::host(SingleThing(thing.get())).port(8888).start();This will start the server, making the light available via the WebThings REST API and announcing it as a discoverable resource on your local network via mDNS.
Let's now also connect a humidity sensor to the server we set up for our light.
A MultiLevelSensor (a sensor that returns a level instead of just on/off) has one required property (besides the name, type, and optional description): level. We want to monitor this property and get notified if the value changes.
First we create a new Thing with a level property (Here we specify the property within the constructor of our custom Thing object):
-
level: tells us what the sensor is actually reading- Contrary to the light, the value cannot be set via an API call, as it wouldn't make much sense, to SET what a sensor is reading. Therefore, we are creating a readOnly property.
struct FakeGpioHumiditySensor : public Thing
{
FakeGpioHumiditySensor() : Thing(
"urn:dev:ops:my-humidity-sensor-1234", "My Humidity Sensor",
"MultiLevelSensor", "A web connected humidity sensor")
{
level = make_value(0.0);
link_property(this, "level", level, {
{"@type", "LevelProperty"},
{"title", "Humidity"},
{"type", "number"},
{"description", "The current humidity in %"},
{"minimum", 0},
{"maximum", 100},
{"unit", "percent"},
{"readOnly", true}});
}
std::shared_ptr<Value<double>> level;
};Now we have a sensor that constantly reports 0%. To make it usable, we need a thread or some kind of input when the sensor has a new reading available. For this purpose we start a thread that queries the physical sensor every few seconds. For our purposes, it just calls a fake method.
struct FakeGpioHumiditySensor : public Thing
{
FakeGpioHumiditySensor() : Thing(
"urn:dev:ops:my-humidity-sensor-1234", "My Humidity Sensor",
"MultiLevelSensor", "A web connected humidity sensor")
{
level = make_value(0.0);
link_property(this, "level", level, {
{"@type", "LevelProperty"},
{"title", "Humidity"},
{"type", "number"},
{"description", "The current humidity in %"},
{"minimum", 0},
{"maximum", 100},
{"unit", "percent"},
{"readOnly", true}});
// Start a thread that polls the sensor reading every 3 seconds
std::thread([this]{
while(true)
{
std::this_thread::sleep_for(std::chrono::seconds(3));
// Update the underlying value, which in turn notifies
// all listeners
level->notify_of_external_update(read_from_gpio());
}
}).detach();
}
// Mimic an actual sensor updating its reading every couple seconds.
double read_from_gpio()
{
std::random_device rd;
std::mt19937 gen(rd());
std::uniform_real_distribution<double> dist(0.0, 100.0);
return dist(gen);
}
std::shared_ptr<Value<double>> level;
};This will update our Value object with the sensor readings via the level->notify_of_external_update(read_from_gpio()) call. The Value object now notifies the property and the thing that the value has changed, which in turn notifies all websocket listeners.
To add your web thing to the WebThings Gateway, install the "Web Thing" add-on and follow the instructions here.