How to register operators

An extraction/control operator is the required software (e.g., python script) that is executed on a device in order to connect their sensors/actuators to the MBP. Examples of ready-to-use extraction and control operators in the form of scripts can be found in the MBP Operators Repository.

A monitoring operator is a software that is executed on an IoT device, in order to monitor health states and resources of the IoT device, for example its CPU temperature or CPU usage. Examples of ready-to-use monitoring operators can be found in the MBP Operators Repository.

Registering ready-to-use operators
Registering your OWN operators
Registering monitoring operators

---

Registering ready-to-use operators

Go to Main Navigation > Operators > Extraction/Control Operators and press the ➕ ​button to add the new operator. Fill the properties inclusive operator scripts.

⚠️ The MBP is currently unable to work with operator scripts that use Windows line endings (CRLF) instead of Unix line endings (LF). If you are using Windows and opened/edited the scripts, make sure the scripts are saved with Unix line endings.

If the operator takes input parameters, such as in this example, press the + button in the Parameters area, and fill out the name, type, unit and if it is a mandatory parameter.

Operators need a registered data model to describe the sensor data which will be sent to the MBP via the scripts of the operator. If you don't have yet registered a data model for the operator you can create it by using the data model creation tool. For ready-to-use operators a dataModel.json file is provided in the respective resource folder which is the definition of a data model fitting the implementation of the ready-to-use operator scripts. How to use this file for the creation of new data models can be read here.

Finally, press Register. After registration, the new operator should be visible in the list of registered operators.

---

Registering your OWN operators

How should I proceed if there is not an operator for my sensor/actuator included in the MBP Operators Repository?

• You can embrace a new challenge and learn how to do it.
• You can write in our discussions/issues about your sensor/actuator, see if someone already created the operator and can share it with you.

If you choose the first answer, let's start then! 💪 In order to facilitate the development of new operators, we provide the mbp_client, a python-based library, which provide functions to connect and communicate to the MBP in a simple manner.

⚠️ The MBP is currently unable to work with operator scripts that use Windows line endings (CRLF) instead of Unix line endings (LF). If you are using Windows and opened/edited the scripts, make sure the scripts are saved with Unix line endings.

To start creating your own operator, we recommend to first learn the basics of Python. Click here for a getting started manual.

Operators can be implemented in any programming language, however, the MBP requires then to contain specific lifecycle management scripts for the operator (i.e., install.sh, start.sh, running.sh, and stop.sh), in order to automate the deployment of user-defined operators. The application logic of these management scripts can, however, still be defined by the user, e.g., by specifying necessary software that needs to be installed.

Within the MBP, an operator is a set of Python and Shell scripts code in the following structure:

• mbp_client.py: This python script contains the logic to connect and to communicate with the MBP. It abstracts a MQTT client and further configuration steps. Be aware that all data you want to send to the MBP must be conform to a standardized JSON object structure (see here) and that the sensor data must be conform with a pre-registered data model.
• entry-file-name: This file contains solely the name of your main python script including its extension.
• <sensor-type>_<IoT_device-type>.py: This is your main python script, which contains the logic for your own sensor/actuator and uses the mbp_client to send these data to the MBP.
• install.sh: This file installs the necessary libraries to run the mbp_client and the main python script.
• start.sh: This file starts the execution of the main python script, the one indicated in the entry-file-name.
• running.sh: This file checks if the main python script is running.
• stop.sh: This file stops the execution of the main python script.

You can find some code examples in the MBP Operators Repository. Note that operators using the mbp_client contain symbolic links in their folders to the files in the mbp_client folder as shown in the figure below.

On Windows OS, if you cannot access the linked files by clicking on the symbolic links, you can still access the files directly in the mbp_client folder. Otherwise, you can also create symbolic links on Windows by executing the following command in the operator folder:

mklink install.sh ....\mbp_client\install.sh

Basically you can copy an operator from the MBP Operator Repository and change the following files:

• <sensor-type>_<IoT_device-type>.py: update the name. Here comes your main code to your sensor/actuator.
• entry-file-name: update the content with above name.
• install.sh: check if you have used any extra library and include in here.

Registering monitoring operators

Go to Main Navigation > Operators > Monitoring Operators and press the ➕ button to add the new operator. Fill the properties inclusive operator scripts.

⚠️ The MBP is currently unable to work with operator scripts that use Windows line endings (CRLF) instead of Unix line endings (LF). If you are using Windows and opened/edited the scripts, make sure the scripts are saved with Unix line endings.

Choose one or more device types, which are able to execute this operator, for example Raspberry Piand Computer. You can find examples of monitoring operators here:

• cpu-temperature_raspberry-pi: operator scripts to read CPU temperature (°C) of Raspberry Pis.
• cpu-usage_raspberry-pi: operator scripts to read CPU usage (%) of Raspberry Pis.

If the operator takes input parameters, press the ➕ button in the Parameters area, and fill out the name, type, unit and if it is a mandatory parameter for starting the operator. Finally, press Register.

After registration, the new operator should be visible in the list of registered monitoring operators.

For each registered device, it will be automatically shown on its device detail view (Devices > 'Device Name'), which monitoring operators are available for the corresponding device type. To activate the monitoring operator for the device, which should be on the state Ready, click on the Enable switch.

Monitoring operators can be on the following states:

• Not ready: the monitoring operator is not ready, for example because the device is Unavailable or Not connected.
• Ready: the monitoring operator is ready to be executed on the device, which has the state Connected.
• Running: the monitoring operator is currently running on the device.
• Unknown: the state of the monitoring operator is not known, an error might have occurred. Please click on Unknown to try again to retrieve the state, otherwise please check the properties values you have provided.

Once the monitoring operator is running, it will send values to the MBP, which can be visualized in live values and historical values charts in the device details view.