README.md

node-red-contrib-homekit-bridged

Intro

Node-RED nodes 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 Apple's Home app on iOS, Watch OS, and Mac OS. 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

For Debian / Ubuntu you need to install the following in order to support Bonjour / Avahi

sudo apt-get install libavahi-compat-libdnssd-dev

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

npm install node-red-contrib-homekit-bridged

Docker

Nodes

Bridge

The Bridge node is a configuration node which will be added from within the service node. It creates the bridge that iOS sees, i.e. the device that is added to the Apple Home app by the user.
All accessories behind a bridge noded are then automatically added by iOS.

Pin Code: Specify the Pin for the pairing process.

Port: If you are behind a Firewall, you may want to specify a port. Otherwise leave empty.

Reuse Address: Set the reuseAddr option when creating the socket. Optional. Default true.

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.

Service Hierarchy: Whether the service is Parent or Linked.

Bridge: On what bridge to host this Service and its Accessory.

Parent Service: Which Parent service the Linked service will be connected to.

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 the debug tab ;)

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.

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 file an Issue.

Air Quality Sensor

Battery Service

Camera Control

Camera RTP Stream Management

Carbon Dioxide Sensor

Carbon Monoxide Sensor

Contact Sensor

Door

Doorbell

Fan

Garage Door Opener

Humidity Sensor

Leak Sensor

Light Sensor

Lightbulb

Lock Management

Lock Mechanism

Microphone

Motion Sensor

Occupancy Sensor

Outlet

Relay

Security System

Smoke Sensor

Speaker

Stateful Programmable Switch

Stateless Programmable Switch

Switch

Temperature Sensor

Thermostat

Time Information

Window

Window Covering

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.

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.