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.

53748875-d3f54480-3e6b-11e9-916f-6bd1fd2b8d8f

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"}]