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.

Getting started

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

Install mqtt-scripts globally:

sudo npm install -g https://github.com/spraot/mqtt-scripts.git

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

Start mqtt-scripts

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

Run with Docker

To run with Docker, build an image with docker build -t mqtt-scripts:1 .. Then substitute 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 files. can be used multiple
                           times.
  -h, --help               Show help                                   [boolean]
  -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 (!getPayload('hue//lights/Hobbyraum')) {
        publish('hue//lights/Hobbyraum', 1);
    } else {
        publish('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 ta
8000
nkstellen = {
    '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;
        publish('$Tankstelle/' + topic + '/Diesel',    data.diesel);
        publish('$Tankstelle/' + topic + '/E5',        data.e5);
        publish('$Tankstelle/' + topic + '/Offen',     data.isOpen);
    });
}

Send payload 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: getPayload($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
getPayload(topic) ⇒ mixed
now() ⇒ number
link(source, target, [value], [options]): Link topic(s) to other topic(s)
combineArray(srcs, target, method, callbackFn, ...args): Combine topics using arbitrary array method, ie. combineArray(srcs, target, 'some', x => x>10)
combineAny(srcs, target, callbackFn): Combine topics using Array.prototype.some()
combineAll(srcs, target, callbackFn): Combine topics using Array.prototype.every()
combineMax(srcs, target): Publish maximum of combined topics
timer(src, target, time): Publishes true on target for specific time after any src changed to true, then reverts target to false

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 8000 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

getPayload(topic) ⇒ `mixed`

Kind: global function
Returns: mixed - the topics value

Param	Type
topic	`string`

now() ⇒ `number`

Kind: global function
Returns: number - ms since epoch

link(source, target, [value], [options])

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.
[options]	`Object`	Options object that will be passed to nested subscribe and publish calls

combineArray(srcs, target, method, callbackFn, ...args)

Combine topics using arbitrary array method, ie. combineArray(srcs, target, 'some', x => x>10)

Kind: global function

Param	Type	Description
srcs	`Array.<string>`	array of topics to subscribe
target	`string`	topic to publish
method	`string`	method in Array.prototype to call
callbackFn	`string`	a function to execute for each src's payload
...args	`any`	args to provide to the prototype method

combineAny(srcs, target, callbackFn)

Combine topics using Array.prototype.some()

Kind: global function

Param	Type	Description
srcs	`Array.<string>`	array of topics to subscribe
target	`string`	topic to publish
callbackFn	`string`	a function to execute for each element in the array

combineAll(srcs, target, callbackFn)

Combine topics using Array.prototype.every()

Kind: global function

Param	Type	Description
srcs	`Array.<string>`	array of topics to subscribe
target	`string`	topic to publish
callbackFn	`string`	a function to execute for each element in the array

combineMax(srcs, target)

Publish maximum of combined topics

Kind: global function

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

timer(src, target, time)

Publishes true on target for specific time after any src changed to true, then reverts target to false

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 +//#
payload	`object`	new payload - the whole payload object (e.g. {"val": true, "ts": 12346345, "lc": 12346345} )
payloadPrev	`object`	previous payload - the whole payload object
msg	`object`	the mqtt message as received from MQTT.js

Name		Name	Last commit message	Last commit date
Latest commit History 165 Commits
doc		doc
lib		lib
sandbox		sandbox
test		test
.dockerignore		.dockerignore
.gitignore		.gitignore
.npmignore		.npmignore
.travis.yml		.travis.yml
Dockerfile		Dockerfile
Gulpfile.js		Gulpfile.js
LICENSE		LICENSE
README.md		README.md
config.example.yml		config.example.yml
docker-compose.yml		docker-compose.yml
index.js		index.js
package-lock.json		package-lock.json
package.json		package.json

License

spraot/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 payload 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])

getPayload(topic) ⇒ mixed

now() ⇒ number

link(source, target, [value], [options])

combineArray(srcs, target, method, callbackFn, ...args)

combineAny(srcs, target, callbackFn)

combineAll(srcs, target, callbackFn)

combineMax(srcs, target)

timer(src, target, time)

subscribeCallback : function

License

About

Resources

License

Uh oh!

Stars

Watchers

Forks

Releases

Packages 0

Languages

getPayload(topic) ⇒ `mixed`

now() ⇒ `number`

subscribeCallback : `function`

Packages