node-red-contrib-homekit-bridged

Do you need help with your setup?

Join us on our Discord server (click on the logo below)!

⚠️ CAUTION ⚠️

Before upgrading make sure that you are using latest version of Node-RED and latest LTS version of Node.js

Upgrading from versions 0.X to 1.X is a breaking change, all devices will be reset in the Home app. Please review the release notes thoroughly before updating!

Intro

node-red-contrib-homekit-bridged (aka NRCHKB) is a Node-RED nodes pack to simulate Apple HomeKit devices. The goal is to emulate native HomeKit devices as closely as possible. We rely on community support - please read throught the README for the basics then head over to the wiki page for details and examples. If you're still stuck please open an issue, we are glad to help.

These nodes allow the creation of fully customizable accessories for use in devices supporting HomeKit which are iPhone, iPad, iPod touch, Apple Watch or Mac. If you can get it in Node-RED, you can get it in HomeKit. The goal of the project is to create a platform where official HomeKit hardware can be emulated as closely as possible through node red.

Install

In favour to use NRCHKB which is Node-RED node (plugin) you need Node.js and Node-RED itself installed. The recommended version of Node.js is 10.x (or higher) and for Node-RED you should use the latest version.

For instructions how to install Node-RED go here. Node.js will be installed together with Node-RED.

Easy Install

If you have Node-RED already installed the recommended install method is to use the editor. To do this, select Manage palette from the Node-RED menu (top right). Then select Install tab in the palette. Search for and install this node (node-red-contrib-homekit-bridged).

Using NPM

To install NRCHKB node run the following command in your Node-RED user directory - typically ~/.node-red

npm i node-red-contrib-homekit-bridged

Docker

You can also pull a docker image containing everything needed to get started, thanks to Raymond Mouthaan.

Nodes

Bridge

The Bridge node is a configuration node (means it will be not visible in a flow like other nodes) which will be added from within the service node. It creates the bridge that HomeKit application sees, i.e. the device that is added to the Apple Home app by the user. All accessories behind a bridge node will be added automatically.

Service

The Service node represents the single device you want to control or query. Every service node can be Parent or Linked. Each Parent service creates an individual accessory in the Home app. Linked services add additional features to their Parent service - for example adding battery status to a motion detector. See examples in the wiki for details.

Input Messages

Input messages can be used to update any Characteristic that the selected Service provides. Simply pass the values-to-update as msg.payload object.

Example: to signal that an Outlet is turned on and in use, send the following payload

{
    "On": 1,
    "OutletInUse": 1
}

Hint: to find out what Characteristics you can address, just send {"foo":"bar"} and watch debug tab in node-red ;)

Output Messages

Output messages are in the same format as input messages. They are emitted from the node when it receives Characteristics updates from a paired iOS device.

Currently, there are two main and one conditional output port for homekit-service in node-red.

1. onChange, is fired when a value has been changed, this is the most recommended to use for most cases.
2. onSet, is fired every time a value has been set (even to the same value as before), it is used to capture repeated input like Television remote buttons.
3. camera snapshot, is enabled only for CameraController Service and is used to retrieve camera snapshot data

Supported Types

The following is a list of Services that are currently supported. Check for more details on the wiki.

If you encounter problems with any of them please create new Issue.

If you need help with the setup itself then please write on our Discord.

Context

Context info can be provided as part of the input message and will be available in the output message as hap.context.

Example:

{
    "On": 1,
    "Context": "set_from_mqtt_topic"
}

No Response

You can set accessory "No Response" status by sending "NO_RESPONSE" as a value for any available characteristic.

Example:

{
    "On": "NO_RESPONSE"
}

After "No Response" status was triggered, the accessory is marked accordingly when you try to control it or reopen Home.app. Any subsequent update of any characteristic value will reset this status. However, the NO_RESPONSE status won't be visible until you exit and reopen the app. This is how the NO_RESPONSE status works in HomeKit and this behaviour can't be changed. Subsequent updates after NO_RESPONSE may also need an app restart to pick up the new state

Topic

An optional property that can be configured in the node or, if left blank, can be set by msg.topic.

If Filter on Topic is selected msg.topic of incoming messages must match the configured value for the message to be accepted. If Filter on Topic is selected and no Topic is set on the node, then msg.topic must match the node's Name.

The Topic parameter can be used to filter incoming messages, making it possible to connect multiple HomeKit services to, for example, one MQTT-in node and filter directly on the MQTT Topic. It can also be used to add additional metadata to the outgoing msg, making it possible to connect multiple HomeKit services directly to an MQTT-out node or filter the flow in another way.

FAQ

How can I get started?

Our wiki page has a growing list of examples and explanations of how to use many features of these nodes. After you've gone through the wiki page and you are still having questions, please open an issue.

How can I upgrade from the non-bridged node-red-contrib-homekit?

How to upgrade from node-red-homekit

How can I generate Debug logs?

Stop your node-red instance and start it again using the following command: DEBUG=NRCHKB*,HAP-NodeJS*,Accessory,HAPServer,EventedHTTPServer node-red

This should output detailed information regarding everything in the homekit context.

The same command gets sent over and over. How do I stop that?

The built in rbe node may be placed as needed to only pass on messages if they are different from previous messages.

I only want to get messages when something has been changed in the Home app, but also all messages I send into the homekit node get forwarded, too. How do I stop that?

Set Allow Message Passthrough to false in the Bridge configuration or...

Insert this node right after your homekit node:

[{"id":"","type":"switch","z":"","name":"check hap.context","property":"hap.context","propertyType":"msg","rules":[{"t":"nnull"}],"checkall":"true","repair":false,"outputs":1,"x":0,"y":0,"wires":[]}]

This will filter out all messages with their payload property hap.context not set, which means they are events that have been sent to homekit via node-red, not via the Home app.

Contributors

Big thanks to all who have contributed to the project.

• Shaquu - leading the current efforts to fix bugs and add features
• crxporter - a lot of work on the documentation and new features design
• Oliver Rahner - reworked the code to add a bridged mode - read his story
• Marius Schmeding - original implementation of HAP-NodeJS into Node-RED

Also, thanks to creators of HAP-NodeJS - NodeJS implementation of Apple's HomeKit Accessory Server

Contact us

• Our Discord server
• Mail directly to Shaquu