Tutorial Developer SensorClientExecuterProcessableOutput

Tutorial - Developer - AlertR Sensor Client Executer Processable Output

This tutorial describes how to write your own scripts that can be executed by the AlertR Sensor Client Executer and its output parsed to be processed by AlertR. This tutorial assumes you have set up the AlertR Sensor Client Executer according to the provided AlertR Sensor Client Executer Tutorial and only describes the necessary additions.

Table of Contents

• Description
• Configuration
• Sensor Script
• Further Information
• Troubleshooting

Description

The following gives you a short example on how to configure the AlertR Sensor Client Executer with a script that outputs processable data for AlertR. The script is written in Python, but it can be any programming language you like. I just find Python most convenient to show what has to be done.

Configuration

The corresponding sensor configuration for the AlertR Sensor Client Executer looks like the following:

[...]

<sensors>

    <sensor>

        <general
            id="0"
            description="Developer Sensor"
            alertDelay="0"
            triggerAlert="True"
            triggerAlertNormal="True" />

        <alertLevel>0</alertLevel>

        <executer
            execute="/usr/bin/python3"
            timeout="5"
            intervalToCheck="10"
            parseOutput="True"
            dataType="1">

            <argument>/home/alertr/dev_script.py</argument>

        </executer>

    </sensor>

</sensors>

[...]

This sensor executes the Python interpreter with the script at /home/alertr/dev_script.py as argument every 10 seconds. The output of the script should be parsed, and the data that is provided by the sensor is of the type integer (1 = integer).

Sensor Script

The following shows the script /home/alertr/dev_script.py. This script does not have any purpose at all. It should just demonstrate how to output data that can be processed by AlertR.

#!/usr/bin/python3

import json
import random

# This function creates a Sensor Alert message dictionary.
# It uses the given "value" as data for the sensor alert,
# the "msg" as message for the optional data,
# and the "state" as state for the sensor alert.
def create_sensor_alert(value, msg, state):
    result = dict()
    result["message"] = "sensoralert"

    optionalData = dict()
    optionalData["message"] = msg

    payload = dict()
    payload["state"] = state
    payload["hasOptionalData"] = True
    payload["optionalData"] = optionalData
    payload["dataType"] = 1
    payload["data"] = {"value": value, "unit": ""}
    payload["hasLatestData"] = True
    payload["changeState"] = True

    result["payload"] = payload
    return result

# This function creates a State Change message dictionary.
# It uses the given "value" as data for the state change,
# and the "state" as state for the state change.
def create_state_change(value, state):
    result = dict()
    result["message"] = "statechange"

    payload = dict()
    payload["state"] = state
    payload["dataType"] = 1
    payload["data"] = {"value": value, "unit": ""}

    result["payload"] = payload
    return result

# This actually does nothing. It just creates a
# random number and triggers a sensor alert if
# it is greater than 10. The created number is used
# as data for the message.
def main():
    data = random.randint(0, 20)
    msg = None
    if data > 10:
        msg = create_sensor_alert(data, "Oh no, over 10!", 1)
    else:
        msg = create_state_change(data, 0)
    print(json.dumps(msg))

if __name__ == '__main__':
    main()

Done. This script creates a sensor alert if a random number is greater than 10. Otherwise, a state change message with the state normal is returned. If you want a detailed description of what messages can be passed back to the AlertR system via the output, please take a look at the Protocol of the AlertR Sensor Client Executer.

Further Information

If you want additional examples that have actually any purpose, please take a look into the scripts_example folder in the AlertR Sensor Client Executer installation directory. Or see other tutorials that use the AlertR Sensor Client Executer like the Tutorial for integrating lm-sensors.

Troubleshooting

If you experience problems, please check the log file first. If it is not helpful, change the log level to DEBUG and check again. If no error can be seen, please start the AlertR client manually and check if an error occurs that is not printed into the log file. This can be done by just executing the AlertR client as the user that it normally runs with.

alertr@towel:~/sensorClientExecuter$ ./alertRclient.py

If you still have problems and do not know how to solve them, you can ask on the community page on reddit or you can use the Github Issues.