Home

Awesome

logic4mqtt

Written and (C) 2015-16 Oliver Wagner owagner@tellerulam.com

Provided under the terms of the MIT license.

Overview

logic4mqtt is a logic and scripting engine for SmartHome automation, based around MQTT as a central message bus.

It uses Java's generalized scripting interface (JSR-223) so scripts can be implemented in any script language supported by this interface. By default, the JVM ships with a Javascript scripting engine (Rhino with Java 7, Nashorn with Java 8), but a variety of other interfaces is available for languages like Groovy, Jython and others.

Dependencies

Build Status Automatically built jars can be downloaded from the release page on GitHub at https://github.com/owagner/logic4mqtt/releases

API

logic4mqtt provides a scripting host and a support API which provides

The API is organized in classes. Documentation for the classes is available at http://owagner.github.io/logic4mqtt/apidocs/

Topic notation

Various logic4mqtt functions deal with MQTT topics. To simplify topic usage in accordance with the MQTT-smarthome specification, there are some special constructs which are replaced depending on contexts:

Example:

Events.setValue("knx//Floor/Livingroom/Light One",true)

publishes the value "1" to knx/set/Floor/Livingroom/Light One whereas

Events.getValue("knx//Floor/Livingroom/Light One")

returns the value of the topic knx/status/Floor/Livingroom/Light One

Events.storeValue("$Status Lighting",1)

and

Events.getValue("$Status Lighting")

however both reference logic/status/Stauts Lighting

Events

Everything in logic4mqtt revolves around the core concept of an Event

Timers

logic4mqtt timers can be specified in one of two ways:

  1. cron-alike syntax
  2. natural language

Cron-alike syntax

Cron syntax is parsed using the Quartz Scheduler CronExpression handling, which is described in detail at http://quartz-scheduler.org/api/2.2.0/org/quartz/CronExpression.html

Two important differences to UNIX-like cron specifications:

Examples:

Timers.addTimer("every_5_minutes","0 */5 * * * ?",callback);

Natural language syntax

The natural language syntax utilizies the Natty library http://natty.joestelmach.com/ for parsing time specifications, with additional support for specifying sunset/sundown as a reference point, and randomization.

Examples:

Timers.addTimer("test1","in 5 minutes",callback);
Timers.addTimer("test2","10 minutes before sunset",callback);
Timers.addTimer("test3","1 hour after civil sunrise",callback);

Repeating timers are also specified using this syntax:

Timers.addTimer("test4","every 10 minutes before sunset",callback);

The natty homepage has a test functionality at http://natty.joestelmach.com/try.jsp where you can try possible specifications. The sunset/sundown keywords are simply replaced with the currently calculated times before the string is passed to natty for parsing. For example,

1 hour after civil sunrise

becomes

1 hour after 08:40

before it's passed to natty. The specifications are reparsed everytime the timer is run, to make sure relative specifications always refer to the current time. This also applies to the sunset/sundown replacement keywords. The sunset/sundown keywords may optionally be prefixed with the keywords "civil", "nautical", "astronomical" or "official", to refer to variants of the sunset/sundown times. The latitude and longitude of the currently location need to be set with a call to

Time.setLocation(latitude,longitude)

prior to use.

Additionally, a randomization amount can be specified:

every 11:00 randomize by 30 minutes

The unit specification is optional and can be any of "second(s)", "minute(s)" or "hour(s)". If it is missing, minutes are assumed. The "by" keyword is entirely optional.

Changelog