mqtt-bridge-scenes v1.1.1
mqtt-bridge-scenes
This is an MQTT Bridge that outputs simple strings; changing them when it receives commands to change them.
This bridge can be used to create "scenes" for home automation software, where a change to a scene can trigger a change in behavior of other devices.
It can also be used as part of a Finite State Machine, as essentially it stores a state which can be retrieved and changed with commands. FSM might be useful for such devices as house alarms, moving between the "unarmed", "pending", and "alarmed" states.
This bridge does not require registering with any third party services.
Setup
You MUST set the environment variable SCENE_FILE
to a path on the file system
that exists. The bridge will attempt to read from this file to use as scene
information. The file should be a JSON Object consisting of "scenes", each of
which should have an array of unique modes; for example:
{
"scene1": ["mode1", "mode2", "mode3"]
}
A more realistic example might be:
{
"away": ["away", "home"],
"alarm": ["disarmed", "pending", "armed", "triggered"]
}
You MAY set the environment variable MQTT_ROOT
. If not set it will default to
scenes
. The below documentation is written as if this is set to the default.
Messages Published
Every "scene" inside of the JSON file will be published under scenes/_SCENE_
where _SCENE_
is the name of the scene. The payload will be the first "mode"
(the first string in the array). So for example the above file will generate
these two messages:
scenes/away (QOS 0 Retained)
away
scenes/alarm (QOS 0 Retained)
disarmed
Messages Accepted
This bridge will subscribe to scenes/#
. It will respond to messages of the
format scenes/_SCENE_/_COMMAND_
where _SCENE_
is the name of a scene, and
_COMMAND_
is one of the following commands:
set
- Change the scene to the contents of the payload (provided the payload matches the name of one of the "modes").cycle
- Sets the scene to the next mode in the list.
When one of these commands is run, the scene will change to the desired mode,
the bridge will publish a new message under scenes/_SCENE_ (QOS 0 Retained)
with the payload set to the new mode, and the scenes file is re-written to
reflect this change. The order of the array is kept so that cycle
will always
change to the "next mode", based on the JSON as was originally authored.
As an example:
scenes/alarm/set (QOS 0)
armed
Will publish scenes/alarm (QOS 0 Retained)
with a payload of armed
and the
scenes file will now contain:
{
"away": ["away", "home"],
"alarm": ["armed", "triggered", "disarmed", "pending"]
}
Publishing scenes/alarm/cycle
with an empty payload will now cycle the mode, so
that scenes/alarm (QOS 0 Retained)
is published again but with a payload of
triggered
, and the scenes file now contains:
{
"away": ["away", "home"],
"alarm": ["triggered", "disarmed", "pending", "armed"]
}
It is important that the scene file is written to, as this allows the bridge to survive crashes and restarts. It would be very unfortunate if the bridge crashing would reset any scenes.