In the previous step, you included in the sketch features implemented by the Opla features library.

However, this section will explain how you can implement and add your own features, and how to add them to the IoT Agent.

How a feature works

A feature is a set of properties and commands.
The IoT Agent from the ditto examples library can have multiple features, get values for their properties, and execute commands on them.

The feature constructor consists of two arguments: a feature name and a vector of definitions.

A feature can have none, one or multiple definitions based on Eclipse Vorto information models, which describe the feature in detail.
A list of useful Vorto models from the public repository is available in the Bosch IoT Suite UI > Search Services and features > Vorto models.

Feature feature("feature id", std::vector<String>{...})

The Feature class has methods for adding properties and commands:

feature.addProperty("name", Category::STATUS, QoS::EVENT, function, 1000)
feature.addCommand("name", commandHandler)

Properties

A feature property has:

a name,
a category,
which can be either Category::STATUS or Category::CONFIGURATION, based on the Vorto model definition,
a QoS (QoS::EVENT or QoS::TELEMETRY),
through which you can specify whether you want to receive absolutely every value reported by the sensors (event) or if some values may be skipped (telemetry)
If you are interested in detailed information about the different QoS levels, check the sections on Telemetry messages and Event messages in the Recommendations by the device connectivity layer.

For some sensors, e.g. temperature, which report data frequently and their values do not change that often or such changes are not critical, you may choose to skip some values to reduce traffic.

On the other hand, for some values that are critical for an alert for example, you would opt to receive every single one.
a function to get the value for the property.
an optional argument for the reporting period, defined in milliseconds

Every time the IoT Agent's loop function is called, it goes through every feature's property.

If the acquisition function yields a different result than the last reported value, and the time since the previous report exceeds the reporting period for that property, the property is automatically sent as telemetry or event depending on the defined QoS property value.

Commands

A feature command is an operation which a backend application sends to the feature. After every agent's loop function call, the agent executes the commands received.
A command has:

a name and
a function corresponding to that command.

The arguments of the command are automatically converted by the IoT Agent into the type supported by the function receiving the command.

Examples

This is a sample implementation of the Opla IoT Kit's temperature sensor as a feature.

It is based on the org.eclipse.vorto.std.sensor:TemperatureSensor:1.0.0 Vorto model, which defines that:

the feature category is status
its display name is TemperatureSensor and
its measurement unit is degrees Celsius

This feature only reports property values and does not accept commands.

A list of useful Vorto models from the public repository is available in the Bosch IoT Suite UI > Search Services and features > Vorto models.

*/
Feature temperatureFeature() {
  return Feature("temperature", std::vector<String> {"org.eclipse.vorto.std.sensor:TemperatureSensor:1.0.0"})
    .addProperty("value", Category::STATUS, QoS::EVENT, temperature, 10000);
}
 
float temperature() {
  return __carrier->Env.readTemperature();
}

Find more examples in features_opla.cpp.

Add features to the sketch

After a feature is set up, use the addFeature method of the IoT Agent in the sketch, and it will automatically handle it.

agent.addFeature(feature)