Examples

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