mqtt-scripts

mqtt-scripts is a Node.js based script runner for use in mqtt based smart home environments.

It's intentended to be used as the "logic layer" in your smart home, and offers a zero-boilerplate, straight forward scripting environment.

It follows the mqtt-smarthome architecture. Mqtt-scripts could be seen as something like "Node-RED without GUI"

Getting started

Prerequisites: mqtt-scripts needs Node.js >= 6.0.

Install mqtt-scripts globally:

sudo npm install -g mqtt-scripts

Create a folder from where mqtt-scripts will load the scripts:

mkdir -p /opt/mqtt-smarthome/scripts

Create a folder to install node modules that can be used in the scripts:

mkdir /opt/mqtt-smarthome/scripts/node_modules
(You can then just use npm install in the directory /opt/mqtt-smarthome/scripts)

Put some files in you script dir:

echo "log.info('my first script!')" > /opt/mqtt-smarthome/scripts/test1.js
echo "log.info 'get ma a coffee' > /opt/mqtt-smarthome/scripts/test1.coffee

Start mqtt-scripts

mqtt-scripts -d /opt/mqtt-smarthome/scripts

Run with Docker

To run with Docker, use either a pre-build image or build one your own. Either way, just substitude the node-command you would have used by the Docker command, for e.g.:

mqtt-scripts --help

becomes

docker run dersimn/mqtt-scripts:1 --help

An example for a productive configuration would be:

docker run -d --restart=always --name=logic \
    -e "TZ=Europe/Berlin" \
    -v /opt/hma/etc/scripts:/scripts:ro \
    dersimn/mqtt-scripts:1 \
    --url mqtt://10.1.1.50 \
    --dir /scripts

Configure via MQTTSCRIPTS_ env variables when using Docker Compose.

Build

Docker development build:

docker build -t mqtt-scripts .
docker run --rm mqtt-scripts --help

Docker Hub deploy:

docker buildx create --name mybuilder
docker buildx use mybuilder
docker buildx build --platform linux/amd64,linux/arm/v7 -t dersimn/mqtt-scripts:1 -t dersimn/mqtt-scripts:1.x.x --push .

Command Line Options

Usage: mqtt-scripts [options]

Options:
  --version                Show version number                         [boolean]
  -c, --config             Path to JSON config file
  -d, --dir                directory to scan for .js and .coffee files. can be
                           used multiple times.
  -h, --help               Show help                                   [boolean]
  -s, --variable-prefix    topic prefix for $ substitution (shorthand for
                           variables, see docs)                 [default: "var"]
  -t, --disable-variables  disable variable feedback (see docs) [default: false]
  -n, --name               instance name. used as mqtt client id and as prefix
                           for connected topic                [default: "logic"]
  -u, --url                mqtt broker url. See
                           https://github.com/mqttjs/MQTT.js#connect-using-a-url
                                                   [default: "mqtt://127.0.0.1"]
  -v, --verbosity          possible values: "error", "warn", "info", "debug"
                                                               [default: "info"]
  -w, --disable-watch      disable file watching (don't exit process on file
                           changes)                             [default: false]
  -l, --latitude                                              [default: 48.7408]
  -m, --longitude                                              [default: 9.1778]

If you're running multiple instances of mqtt-scripts you have to decide which one should handle variables and disable the variables on all other instances with the --disable-variable option.

Script Examples

Use hm2mqtt and hue2mqtt to control a hue lamp with a homematic remote control

link('hm//RC4:1/PRESS_CONT', 'hue//lights/Hobbyraum/bri_inc', -16);

subscribe('hm//RC4:2/PRESS_CONT', function () {
    if (!getValue('hue//lights/Hobbyraum')) {
        setValue('hue//lights/Hobbyraum', 1);
    } else {
        setValue('hue//lights/Hobbyraum/bri_inc', 16);
    }
});

link('hm//RC4:1/PRESS_SHORT', 'hue//lights/Hobbyraum', 0);
link('hm//RC4:2/PRESS_SHORT', 'hue//lights/Hobbyraum', 254);
link('hm//RC4:3/PRESS_CONT', 'hue//lights/Hobbyraum/ct_inc', -16);
link('hm//RC4:4/PRESS_CONT', 'hue//lights/Hobbyraum/ct_inc', 16);
link('hm//RC4:3/PRESS_SHORT', 'hue//lights/Hobbyraum/ct', 153);
link('hm//RC4:4/PRESS_SHORT', 'hue//lights/Hobbyraum/ct', 500);

retrieve fuel prices from tankerkoenig

var request =   require('request');
var cred =      require('./lib/credentials.js');

var url = 'https://creativecommons.tankerkoenig.de/json/detail.php';

var tankstellen = {
    'OMV': 'cb1f0588-d517-40f0-8ce3-3edadebea40d',
    'Shell': '4267c196-eea1-47be-96b7-d790b2fbd17a'
};

schedule('0/12 * * * *', function () {
    for (var topic in tankstellen) {
        getData(topic, tankstellen[topic]);
    }
});

function getData(topic, id) {
    request.get(url + '?id=' + id + '&apikey=' + cred.tankerkoenig.apikey, function (err, res) {
        if (err) {
            log.error(err);
            return;
        }
        var data = JSON.parse(res.body).station;
        setValue('$Tankstelle/' + topic + '/Diesel',    data.diesel);
        setValue('$Tankstelle/' + topic + '/E5',        data.e5);
        setValue('$Tankstelle/' + topic + '/Offen',     data.isOpen);
    });
}

Send a variables state changes to Pushover

var cred = require('./lib/credentials.js');

var pushoverNotifications = require('pushover-notifications');

var push = new pushoverNotifications( {
    user: cred.pushover.user,
    token: cred.pushover.token,
    onerror: function (error) {
        log.error(error);
    }
});

function pushover(msg) {
    if (typeof msg !== 'object' || typeof msg.message !== 'string') msg = {message: '' + msg};
    msg.title = msg.title || "Smart Home";
    msg.priority = msg.priority || 0;
    msg.device = msg.device || 'iphone5';
    push.send(msg, function(err, result) {
        if (err) {
            log.error(err);
        }
    });
}

subscribe('$Anwesenheit', {change: true}, function () {
    pushover({
        title:'Anwesenheit',
        message: getProp($Anwesenheit, 'logic_textual'),
        priority: -1
    });
});

API

Classes

log: Log to stdout/stderr. Messages are prefixed with a timestamp and the calling scripts path.

Functions

subscribe(topic, [options], callback): Subscribe to MQTT topic(s)
schedule(pattern, [options], callback): Schedule recurring and one-shot events
sunSchedule(pattern, [options], callback): Schedule a recurring event based on sun position
publish(topic, payload, [options]): Publish a MQTT message
setValue(topic, val): Set a value on one or more topics
getValue(topic) ⇒ mixed
getProp(topic, [...property]) ⇒ mixed: Get a specific property of a topic
now() ⇒ number
age(topic) ⇒ number
link(source, target, [value]): Link topic(s) to other topic(s)
combineBool(srcs, targets): Combine topics through boolean or
combineMax(srcs, targets): Publish maximum of combined topics
timer(src, target, time): Publishes 1 on target for specific time after src changed to true

Typedefs

subscribeCallback : function

log

Log to stdout/stderr. Messages are prefixed with a timestamp and the calling scripts path.

Kind: global class

log
- .debug()
- .info()
- .warn()
- .error()

log.debug()

Log a debug message

Kind: static method of log

Type
`*`

log.info()

Log an info message

Kind: static method of log

Type
`*`

log.warn()

Log a warning message

Kind: static method of log

Type
`*`

log.error()

Log an error message

Kind: static method of log

Type
`*`

subscribe(topic, [options], callback)

Subscribe to MQTT topic(s)

Kind: global function

Param	Type	Description
topic	`string` \| `Array.<string>`	topic or array of topics to subscribe
[options]	`Object` \| `string` \| `function`	Options object or as shorthand to options.condition a function or string
[options.shift]	`number`	delay execution in seconds. Has to be positive
[options.random]	`number`	random delay execution in seconds. Has to be positive
[options.change]	`boolean`	if set to true callback is only called if val changed
[options.retain]	`boolean`	if set to true callback is also called on retained messages
[options.condition]	`string` \| `function`	conditional function or condition string
callback	`subscribeCallback`

schedule(pattern, [options], callback)

Schedule recurring and one-shot events

Kind: global function
See: sunSchedule for scheduling based on sun position.

Param	Type	Description
pattern	`string` \| `Date` \| `Object` \| `Array.<mixed>`	pattern or array of patterns. May be cron style string, Date object or node-schedule object literal. See https://github.com/tejasmanohar/node-schedule/wiki
[options]	`Object`
[options.random]	`number`	random delay execution in seconds. Has to be positive
callback	`function`	is called with no arguments

Example

// every full Hour.
schedule('0 * * * *', callback);

// Monday till friday, random between 7:30am an 8:00am
schedule('30 7 * * 1-5', {random: 30 * 60}, callback);

// once on 21. December 2018 at 5:30am
schedule(new Date(2018, 12, 21, 5, 30, 0), callback);

// every Sunday at 2:30pm
schedule({hour: 14, minute: 30, dayOfWeek: 0}, callback);

sunSchedule(pattern, [options], callback)

Schedule a recurring event based on sun position

Kind: global function
See: schedule for time based scheduling.

Param	Type	Description
pattern	`string` \| `Array.<string>`	a suncalc event or an array of suncalc events. See https://github.com/mourner/suncalc
[options]	`Object`
[options.shift]	`number`	delay execution in seconds. Allowed Range: -86400...86400 (+/- 24h)
[options.random]	`number`	random delay execution in seconds.
callback	`function`	is called with no arguments

Example

// Call callback 15 minutes before sunrise
sunSchedule('sunrise', {shift: -900}, callback);

// Call callback random 0-15 minutes after sunset
sunSchedule('sunset', {random: 900}, callback);

publish(topic, payload, [options])

Publish a MQTT message

Kind: global function

Param	Type	Default	Description
topic	`string` \| `Array.<string>`		topic or array of topics to publish to
payload	`string` \| `Object`		the payload string. If an object is given it will be JSON.stringified
[options]	`Object`		the options to publish with
[options.qos]	`number`	`0`	QoS Level
[options.retain]	`boolean`	`false`	retain flag

setValue(topic, val)

Set a value on one or more topics

Kind: global function

Param	Type	Description
topic	`string` \| `Array.<string>`	topic or array of topics to set value on
val	`mixed`

getValue(topic) ⇒ `mixed`

Kind: global function
Returns: mixed - the topics value

Param	Type
topic	`string`

getProp(topic, [...property]) ⇒ `mixed`

Get a specific property of a topic

Kind: global function
Returns: mixed - the topics properties value

Param	Type	Description
topic	`string`
[...property]	`string`	the property to retrieve. May be repeated for nested properties. If omitted the whole topic object is returned.

Example

// returns the timestamp of a given topic
getProp('hm//Bewegungsmelder Keller/MOTION', 'ts');

now() ⇒ `number`

Kind: global function
Returns: number - ms since epoch

age(topic) ⇒ `number`

Kind: global function
Returns: number - seconds since last change

Param	Type
topic	`string`

link(source, target, [value])

Link topic(s) to other topic(s)

Kind: global function

Param	Type	Description
source	`string` \| `Array.<string>`	topic or array of topics to subscribe
target	`string` \| `Array.<string>`	topic or array of topics to publish
[value]	`mixed`	value to publish. If omitted the sources value is published. A function can be used to transform the value.

combineBool(srcs, targets)

Combine topics through boolean or

Kind: global function

Param	Type	Description
srcs	`Array.<string>`	array of topics to subscribe
targets	`string`	topic to publish

combineMax(srcs, targets)

Publish maximum of combined topics

Kind: global function

Param	Type	Description
srcs	`Array.<string>`	array of topics to subscribe
targets	`string`	topic to publish

timer(src, target, time)

Publishes 1 on target for specific time after src changed to true

Kind: global function

Param	Type	Description
src	`string` \| `Array.<string>`	topic or array of topics to subscribe
target	`string`	topic to publish
time	`number`	timeout in milliseconds

subscribeCallback : `function`

Kind: global typedef

Param	Type	Description
topic	`string`	the topic that triggered this callback. +/status/# will be replaced by +//#
val	`mixed`	the val property of the new state
obj	`object`	new state - the whole state object (e.g. {"val": true, "ts": 12346345, "lc": 12346345} )
objPrev	`object`	previous state - the whole state object
msg	`object`	the mqtt message as received from MQTT.js

Name		Name	Last commit message	Last commit date
Latest commit History 103 Commits
doc		doc
sandbox		sandbox
testscripts		testscripts
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmignore		.npmignore
.travis.yml		.travis.yml
Dockerfile		Dockerfile
Gulpfile.js		Gulpfile.js
LICENSE		LICENSE
README.md		README.md
config.js		config.js
index.js		index.js
mockdate.js		mockdate.js
package-lock.json		package-lock.json
package.json		package.json
test.js		test.js

License

hobbyquaker/mqtt-scripts

Folders and files

Latest commit

History

Repository files navigation

mqtt-scripts

Getting started

Run with Docker

Build

Command Line Options

Script Examples

Use hm2mqtt and hue2mqtt to control a hue lamp with a homematic remote control

retrieve fuel prices from tankerkoenig

Send a variables state changes to Pushover

API

Classes

Functions

Typedefs

log

log.debug()

log.info()

log.warn()

log.error()

subscribe(topic, [options], callback)

schedule(pattern, [options], callback)

sunSchedule(pattern, [options], callback)

publish(topic, payload, [options])

setValue(topic, val)

getValue(topic) ⇒ mixed

getProp(topic, [...property]) ⇒ mixed

now() ⇒ number

age(topic) ⇒ number

link(source, target, [value])

combineBool(srcs, targets)

combineMax(srcs, targets)

timer(src, target, time)

subscribeCallback : function

License

About

Topics

Resources

License

Stars

Watchers

Forks

Releases

Packages 0

Contributors 2

Languages

getValue(topic) ⇒ `mixed`

getProp(topic, [...property]) ⇒ `mixed`

now() ⇒ `number`

age(topic) ⇒ `number`

subscribeCallback : `function`

Packages