homebridge-automation
Control your homebridge instance with Javascript.
[!WARNING] This plugin is very new, but since it's so useful and unique (no simpler homebridge automation approaches exist) I'm releasing it for constributors, testers, and as a request for feedback.
Examples
(sorry this is so gnarly, we can improve the interface in PLATFORM_SCRIPT
)
automation.listen(function (event) {
if (event.type === "Lightbulb") {
// do stuff
}
if (event.name === "Book Globe") {
// do stuff
}
});
When Dummy Switch is turned on, wait 5 seconds, then turn it Off.
automation.listen(function (event) {
if (event.name === "Dummy Switch") {
const On = event.serviceCharacteristics.find((c) => c.name === "On");
if (On && On.value === 1) {
setTimeout(function () {
automation.set(event.uniqueId, On.iid, 0);
}, 5_000);
return true;
}
return false;
}
return null;
});
On Motion Sensed (Active), set Globe light to On
automation.listen(function (event) {
if (event.name === "Motion Sensor") {
if (
event.serviceCharacteristics.find(
(c) => c.name === "Active" && c.value === true,
)
) {
const light = automation.services.find((s) => s.name === "Globe");
if (light) {
const on = light.serviceCharacteristics.find((s) => s.type === "On");
if (on) {
automation.set(light.uniqueId, on.iid, 1);
}
}
}
}
});
API
The automation
object is available in your function module scope and defined in platformApi.ts
.
See schemas/Service.ts
and schemas/Characteristic.ts
.
Your function module scope is preserved between invocations, but is lost on Homebridge restart.
Development
Local testing
Simply run npm run watch
to start. By default it uses the config at ~/.homebridge/config.json
, so if you want to discover local network instance add the correct PIN for your Homebridge instance there.
Local testing (in docker)
This runs segregated from your local network for more specific testing scenarios.
docker run --name=homebridge-automation -p 18581:8581 -v $(pwd)/homebridge:/homebridge -v $(pwd):/var/lib/homebridge-plugin-automation homebridge/homebridge:latest; docker rm homebridge-automation
Then open homebridge UI: http://localhost:18581/
Note: because of our use of isolated-vm
, linking your host node_modules/dist into a docker container of a different arch (e.g. arm64 or x86) won't work, with error "invalid ELF header"
Link To Homebridge
Run this command so your global install of Homebridge can discover the plugin in your development environment:
npm link
You can now start Homebridge, use the -D
flag so you can see debug log messages in your plugin:
homebridge -D
Installing Beta Versions
You can install beta versions of this plugin by appending @beta
to the install command, for example:
sudo npm install -g homebridge-example-plugin@beta
Beta versions may break functionality, but