Home

Awesome

Homebridge Automation powered by Node-RED

<p align="center"> <img src="docs/Homebridge and Node Red.png"/> </p>

The above Node-RED Flow, turns on my 'Outside Office' light when the powder room is turned on, and turns them both off after 10 seconds. Not practical but a good sample of the power behind Node-RED. Link to exported flow for above.

Table of Contents

<!--ts--> <!-- Created by https://github.com/ekalinin/github-markdown-toc --> <!-- Added by: sgracey, at: Sun 19 Mar 2023 11:30:14 EDT --> <!--te-->

Introduction

This is a release of the ability to integrate Homebridge Accessories into Node-RED so that you can start flows from Homebridge accessory events and control your existing homebridge accessories. ( To create accessories in HomeKit, please use node-red-contrib-homekit-bridged. )

Homebridge Nodes

Four different node types are available, the first node hb event listens for changes to an accessory (ie on/off) and sends a message into Node-Red containing the updated accessory status. The second node hb resume holds the state of an accessory and supports creating a state resume function. The third node hb status allows you to poll an accessory for status. The forth node hb control allows you to control a homebridge accessory. Each node is tied to an individual Home App Tile/Service of an accessory (ie on/off and brightness).

Payload from a dimmable lightbulb.

{ "On":true, "Brightness":100 }

Homebridge Nodes

Caveats

With a plugin, you can see if it supports Real Time events, by opening the Home App, and looking at an accessory. Then trigger a local event outside of homebridge/homekit. If the accessory updates in real time, then it support Real Events. ( An example of a local event can be turning on a Smart Light Switch, by the local switch. Another example would be using the vendor app to control an accessory.)

Changes

Mar 18, 2019 - Version 0.0.39

Mar 19, 2019 - Version 0.0.42

Mar 31, 2019 - Version 0.0.

May 9, 2019 - Version 0.0.43

May 15, 2019 - Version 0.0.44

May 29, 2019 - Version 0.0.45

July 27, 2019 - Version 0.0.50

Feb 24, 2020 - Version 0.0.56

Mar 18, 2020 - Version 0.0.59

Oct 13, 2020 - Version 0.0.71

Oct 24, 2020 - Version 0.0.71

Nov 1, 2020 - Version 0.0.73

Nov 13, 2020 - Version 0.0.76

Feb 2, 2021 - Version 0.0.78

Mar 9, 2021 - Version 0.0.80

April 23, 2021 - Version 0.0.82

Dec 31, 2022 - Version 0.1.3

Jan 6, 2023 - Version 0.1.5

Jan 11, 2023 - Version 0.1.7

Jan 15, 2023 - Version 0.1.8

Backlog / Roadmap

Dropped items

Installation Steps

1 - Install Node-RED and Homebridge

This is covered in alot of other places, so I won't cover it here.

2 - Prepare Homebridge for integration with Homebridge-Automation

Place your homebridge instances into "INSECURE MODE". This is same as my Homebridge Alexa plugin, and you just need to follow the Prepare homebridge for plugin instructions there.

3 - Install Homebridge-Automation into Node-Red

cd ~/.node-red
npm install node-red-contrib-homebridge-automation

4 - Start Node-Red

5 - Initial setup and configuration inside Node-Red

Choose

Pencil

Pin Entered

Done

6 - Configure 'hb event' to receive updates from your Accessories

Populated

Populated

The accessory naming convention is:

Accessory Name and Accessory Service Type

Node-RED Homebridge-Automation Message Structure

hb event

This node generates a message every time an Accessory changes status, and generates a message containing the updated status of all the characteristics.

Output

Message is structured like this

msg = {
  name: Accessory Name,
  payload: { "On":true, "Brightness":100 }
  Homebridge: Homebridge instance name,
  Manufacturer: Plugin Manufacturer,
  Type: Homebridge device type,
  _device: Unique device identifier,
  _confId: node.confId,
  _rawEvent: Raw event message
};

Message payload will vary depending on characteristics support by the device, this example is from a dimmable light.

Please note that multiple event messages may be received from a single device event, this is due to how homebridge controls devices and emits events.

hb resume

This node can be used to create a resume previous state flow. Where you change the state of an accessory, and have it resume the previous state afterwards. I'm using this, in conjunction with Alexa to give the ability to turn on and off the lights in a room, but not turn any lights that were already on. I'm also using it with the HomeKit "I'm home" automation, to turn a group of lights for a few minutes then turn off. But at the same time have any lights you already had on, stay on.

input

Based on the message input payload and state of the accessory the output changes.

For {"On":true}, the node just passes the message to output. For the first {"On":false}, the output is the state of the accessory from prior to the last turn on. For the second {"On":false}, the out is {"On":false}.

msg = {
  payload: { "On":true, "Brightness":100 }
};

output

msg = {
  payload: { "On":true, "Brightness":100 }
};

Message payload will vary depending on characteristics support by the device, this sample is from a dimmable light.

To find supported characteristics for a device, please send an invalid message payload to the node, and it will output the supported characteristics in the debug log.

hb status

This node allows you to poll a Homebridge accessory and collect the current status of all the characteristics.

input

Anything

output

Message is structured like this

msg = {
  name: Accessory Name,
  payload: { "On":true, "Brightness":100 }
  Homebridge: Homebridge instance name,
  Manufacturer: Plugin Manufacturer,
  Type: Homebridge device type,
  _device: Unique device identifier,
  _confId: node.confId,
  _rawEvent: Raw event message
};

Message payload will vary depending on characteristics support by the device, this sample is from a dimmable light.

hb control

This node allows you to control all the characteristics of a Homebridge accessory. The message payload needs to be a JSON object containing the values of all the characteristics you want to change. If you send the node an invalid payload, it will output all the available characteristics of the accessory in the debug tab.

Input

The hb control node only looks at msg.payload value, and ignore's all others.

msg = {
        payload: { "On":true, "Brightness":100 }
      }

Message payload will vary depending on characteristics support by the device, this sample is from a dimmable light.

To find supported characteristics for a device, please send an invalid message payload to the node, and it will output the supported characteristics in the debug log.

Flows Shared from Community

I have started collecting flows for useful functions on the wiki.

https://github.com/NorthernMan54/node-red-contrib-homebridge-automation/wiki

Donations

Donate

Troubleshooting / DEBUG MODE

To start Node-RED in DEBUG mode, and output Homebridge-Automation debug logs start Node-RED like this.

DEBUG=-express*,-send*,-body-parser*,* node-red