mqttrules

mqttrules

mqttrules executes rules that operate on MQTT messages.

Usage

Command-line

go get mqttrules
# without configuration file
mqttrules --broker tcp://localhost:1883 --username user --password pass
# with configuration file
mqttrules --config test/testConfig.json

Docker image

docker run -v /var/mqttrules:/var/mqttrules crenz/mqttrules

Rule definition

Each rule belongs to a ruleset, has a name, is either triggered through an incoming MQTT message with a certain topic or run according to a cron-like schedule. If an (optional) condition evaluates to true, one or several actions are performed. The only kind of action currently available is sending out an MQTT message.

Here is an example. It refers to a parameter called lights_kitchen_state.` This will be explained later.

{
        "trigger": "home/buttons/kitchen/status",
        "condition": "payload() > 0",
        "actions": [
          {
            "topic": "home/lights/kitchen/set",
            "payload": "{ \"on\" : ${!lights_kitchen_state}}",
            "qos": 2,
            "retain": false
          }
        ]
}

See testConfig.json for more examples, and for how to specify rules within the configuration file.

Defining rules via MQTT messages

To define a rule using MQTT messages, send a message using the topic rule/$RULESET/$RULENAME. As payload, send a JSON string in the format of the example above. In the configuration file, you can also specify a prefix. With a prefix of mqttrules/, the topic could be e.g. `mqttrules/rule/lights/kitchen_switch.

Parameters

Parameters are values that can be used both as part of condition expressions as well as payload expressions. Parameters can have an initial value, but they also can be defined based upon receiving messages with a certain topic and evaluating an expression that defines the parameter value.

The following example defines a parameter that extracts the on value out of MQTT messages with a JSON payload and the topic home/lights/kitchen/status.

{
      "value": "",
      "topic": "home/lights/kitchen/status",
      "expression": "payload(\"$.on\")"
}

Defining parameters via MQTT messages

To define a parameter using MQTT messages, send a message using the topic param/$PARAMNAME. As payload, send a JSON string in the format of the example above. In the configuration file, you can also specify a prefix. With a prefix of mqttrules/, the topic could be e.g. mqttrules/param/lights_kitchen_state.

Note: It is highly recommended to only use the characters [A-Za-z0-9_] for the rule names, and to avoid especially the minus sign.

Expressions

In mqttrules, expressions can make use of standard arithmetic expressions, parameters and the special payload() function. Without a parameter, payload() returns the complete payload of the incoming MQTT message (that triggered the rule execution or parameter update). Alternatively, you can specify a JSON path as parameter, e.g. payload("$.state.on").

Condition expressions (used in rules) need to evaluate to a boolean value. Parameter expressions (used to determine the value of a parameter) can evaluate to any kind of value.

Expressions are evaluated using the govaluate package. For more information, refer to that package's documentation.

Kudos

mqttrules is made possible by leveraging some awesome Go packages:

• cron - A cron spec parser and runner
• govaluate - Arbitrary expression evaluation for golang
• jsonpath - A golang implementation of JsonPath syntax.
• gosweep - A shell script to do various checks on Go code.

License

Copyright (C) 2016-2017 Christian Renz. Licensed under the MIT License (see LICENSE).