Examples - NRCHKB/node-red-contrib-homekit-bridged GitHub Wiki
WORK IN PROGRESS
Getting started
This page will be used to share a series of basic examples so that users may see how this plugin functions and get started more easily with copyable flows for each HomeKit service. This page will assume you are familiar with Node-RED basics. For new users, please start with the official Node-RED docs before continuing here.
Nodes
This plugin has two nodes, homekit-bridge and homekit-service.
Bridge
Generally only one bridge is needed. This is the item that will be linked to the Home app on an Apple device. Note that HomeKit allows 99 devices per bridge so if your setup exceeds this number of devices you will need two bridges.
Service
The service is an actual item in the Home app. Currently (version 0.5.1) functional services are:
| Service Name | Required Characteristics | Example Items |
|---|---|---|
| Air purifier | Active, current state, target state | |
| Air quality sensor | Air quality | |
| Carbon dioxide sensor | Carbon dioxide detected | |
| Carbon monoxide sensor | Carbon monoxide detected | |
| Contact sensor | Contact sensor state | Door, window (open/closed) |
| Door | Current position, target position, position state | Motorized door |
| Fan | On | Non oscillating fan |
| Fan V2 | Active | Oscillating fan |
| Faucet | Active | |
| Garage door opener | Current state, target state, obstruction detected | |
| Heater Cooler | Active, current heater cooler state, target heater cooler state, current temperature | Fan with heater |
| Humidifier / dehumidifier | Current relative humidity, current humidifier dehumidifier state, target humidifier dehumidifier state, active | |
| Humidity sensor | Current relative humidity | |
| Leak sensor | Leak detected | |
| Light sensor | Current ambient light level | |
| Light bulb | On | Can be on/off, dimmable, multi color, or adjustable temperature bulb |
| Lock mechanism | Lock current state, lock target state | Door lock |
| Motion sensor | Motion detected | |
| Occupancy sensor | Occupancy detected | |
| Outlet | On | On/off only |
| Security system | Security system current state, security system target state | Used to arm/disarm external security system |
| Slat | Current slat state, slat type | Vents on a fan |
| Smoke sensor | Smoke detected | |
| Stateless programmable switch | Programmable switch event | No output, used to send actionable "button clicks" to HomeKit |
| Switch | On | On/off only |
| Temperature sensor | Current temperature | |
| Thermostat | Current heating cooling state, target heating cooling state, current temperature, target temperature, temperature display units | HVAC control, heater, or AC unit |
| Valve | Active, in use | Faucet, sprinkler, shower |
| Window | Current position, target position, position state | Motorized window |
| Window covering | Target position, current position, position state | Blinds, roller shutters, etc. |
Characteristics
Characteristics are the values sent to the service item. They are generally true/false or number values. Here is a non-comprehensive list of services. Use this table to determine which values and formats may be sent to each service node.
| Characteristic | Format | Accepted Values | Notes |
|---|---|---|---|
| Brightness | int | 0 - 100 | Percentage, step value = 1 |
| Cooling threshold | float | 10 - 35 | Celsius, step value = 0.1 |
| Current door state | uint8 | 0 - 4 | Open=0, closed=1, opening=2, closing=3, stopped=4 |
| Current heating cooling state | uint8 | 0 - 4 | Off=0, heat=1, cool=2 |
| Current relative humidity | float | 0 - 100 | Percentage, step value = 1 |
| Current temperature | float | 0 - 100 | Celsius, step value = 0.1 |
| Heating threshold temperature | float | 0 - 25 | Celsius, step value = 0.1 |
| Hue | float | 0 - 360 | Arcdegrees, step value = 1 |
| Lock current state | uint8 | 0 - 3 | Unsecured=0, secured=1, jammed=2, unknown=3 |
| Lock target state | uint8 | 0, 1 | Unsecured=0, secured=1 |
| Motion detected | bool | true/false | |
| Obstruction detected | bool | true/false | |
| On | bool | true/false | |
| Outlet in use | bool | true/false | |
| Rotation direction | int | 0, 1 | Clockwise=0, counter clockwise=1 |
| Rotation speed | int | 0 - 100 | Percentage, step value = 1 |
| Saturation | float | 0 - 100 | Percentage, step value = 1 |
| Target door state | uint8 | 0, 1 | Open=0, closed=1 |
| Target heating cooling state | uint8 | 0 - 3 | Off=0, heat=1, cool=2, auto=3 |
| Target relative humidity | float | 0 - 100 | Percentage, step value = 1 |
| Target temperature | float | 10 - 38 | Celsius, step value = 0.1 |
| Temperature display units | uint8 | 0, 1 | Celsius=0, Fahrenheit=1 |
| Air particulate density | float | 0 - 1000 | Micrograms/m^3 |
| Security system current state | uint8 | 0 - 4 | Stay armed=0, away armed=1, night armed=2, disarmed=3, alarm triggered=4 |
| Security system target state | uint8 | 0 - 4 | Stay armed=0, away armed=1, night armed=2, disarmed=3 |
| Battery level | uint8 | 0 - 100 | Percentage, step value = 1 |
| Carbon monoxide detected | uint8 | 0, 1 | Normal=0, abnormal (danger)=1 |
| Contact sensor state | uint8 | 0, 1 | Contact detected=0, contact not detected=1 |
| Current ambient light level | float | 0.0001 - 100,000 | Lux (lumens/m^2) |
| Current horizontal tilt angle | int | -90 - 90 | Arcdegrees, step value = 1 |
| Current position | uint8 | 0 - 100 | Percentage, step value = 1 |
| Current vertical tilt angle | int | -90 - 90 | Arcdegrees, step value = 1 |
| Hold position | bool | true/false | Used to stop a door or window immediately |
| Leak detected | uint8 | 0, 1 | No leak=0, leak detected=1 |
| Occupancy detected | uint8 | 0, 1 | Not occupied=0, occupied=1 |
| Position state | uint8 | 0 - 2 | Going to minimum value=0, going to maximum value=1, stopped=2 |
| Programmable switch event | uint8 | 0 - 2 | Single press=0, double press=1, long press=2 |
| Status active | bool | true/false | True indicates the accessory is active and has no errors |
| Smoke detected | uint8 | 0, 1 | Smoke not detected=0, smoke detected=1 |
| Status jammed | uint8 | 0, 1 | Not jammed=0, jammed=1 |
| Status low battery | uint8 | 0, 1 | Normal battery=0, low battery=1 |
| Status tampered | uint8 | 0, 1 | Normal=0, tampered=1 |
| Target horizontal tilt angle | int | -90 - 90 | Arcdegrees, step value = 1 |
| Target position | uint8 | 0 - 100 | Percentage, step value = 1 |
| Target vertical tilt angle | int | -90 - 90 | Arcdegrees, step value = 1 |
| Carbon monoxide level | float | 0 - 100 | Carbon monoxide level in parts per million |
| Carbon monoxide peak level | float | 0 - 100 | Carbon monoxide peak level in parts per million |
| Carbon dioxide detected | uint8 | 0, 1 | Normal=0, abnormal=1 |
| Carbon monoxide level | float | 0 - 100,000 | Carbon dioxide level in parts per million |
| Carbon monoxide peak level | float | 0 - 100,000 | Carbon dioxide peak level in parts per million |
| Air quality | uint8 | 0 - 5 | Unknown=0, excellent=1, good=2, fair=3, inferior=4, poor=5 |
| Current air purifier state | uint8 | 0 - 2 | Inactive=0, idle=1, purifying=2 |
| Current slat state | uint8 | 0 - 2 | Fixed=0, jammed=1, swinging=2 |
| Slat type | uint8 | 0, 1 | |
| Target air purifier state | uint8 | 0, 1 | Manual=0, auto=1 |
| Target fan state | uint8 | 0, 1 | Manual=0, auto=1 |
| Current fan state | uint8 | 0 - 2 | Inactive=0, idle=1, blowing air=2 |
| Active | uint8 | 0, 1 | Inactive=0, active=1 |
| Swing mode | uint8 | 0, 1 | Swing disabled=0, swing enabled=1 |
| Current tilt angle | int | -90 - 90 | Arcdegrees, step value = 1 |
| Target tilt angle | int | -90 - 90 | Arcdegrees, step value = 1 |
| Ozone density | float | 0 - 1,000 | Micrograms/m^3 |
| Nitrogen dioxide density | float | 0 - 1,000 | Micrograms/m^3 |
| Sulphur dioxide density | float | 0 - 1,000 | Micrograms/m^3 |
| PM2.5 density | float | 0 - 1,000 | Micrograms/m^3 |
| PM10 density | float | 0 - 1,000 | Micrograms/m^3 |
| VOC density | float | 0 - 1,000 | Micrograms/m^3 |
| Color temperature | uint32 | 50 - 400 | Reciprocal megakelvin, step value=1 |
Example Items
Below is a collection of example flows that may be copied into your Node-RED deployment. Each will have various inject nodes representing on, off, brightness, status, etc. These are not necessarily fully functioning or comprehensive examples, but are meant to demonstrate how each service accepts data.
Switch
This is an example of a switch item. The input nodes are "On" and "Off". The debug node will return values when the switch is turned on or off via the Home app on an Apple device.
Copyable Node-RED flow:
[{"id":"ed2d8340.e1d5d8","type":"homekit-service","z":"7b43483c.39305","bridge":"d334490b.40dac","name":"Example Switch","serviceName":"Switch","topic":"","manufacturer":"Default Manufacturer","model":"Default Model","serialNo":"Default Serial Number","characteristicProperties":"{}","x":360,"y":160,"wires":["5844674e.178708"](/NRCHKB/node-red-contrib-homekit-bridged/wiki/"5844674e.178708")},{"id":"8db975bc.c2e9d","type":"inject","z":"7b43483c.39305","name":"On","topic":"","payload":"{\"On\":\"true\"}","payloadType":"json","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":130,"y":120,"wires":["ed2d8340.e1d5d8"](/NRCHKB/node-red-contrib-homekit-bridged/wiki/"ed2d8340.e1d5d8")},{"id":"5844674e.178708","type":"debug","z":"7b43483c.39305","name":"HomeKit Out","active":true,"tosidebar":true,"console":false,"tostatus":false,"complete":"payload","x":550,"y":160,"wires":[]},{"id":"629771.da7c409","type":"inject","z":"7b43483c.39305","name":"Off","topic":"","payload":"{\"On\":\"false\"}","payloadType":"json","repeat":"","crontab":"","once":false,"onceDelay":0.1,"x":130,"y":180,"wires":["ed2d8340.e1d5d8"](/NRCHKB/node-red-contrib-homekit-bridged/wiki/"ed2d8340.e1d5d8")},{"id":"d334490b.40dac","type":"homekit-bridge","z":"","bridgeName":"Example Bridge","pinCode":"111-11-111","port":"","allowInsecureRequest":false,"manufacturer":"Default Manufacturer","model":"Default Model","serialNo":"Default Serial Number"}]