node-red-contrib-homekit-bridged 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 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.
If you have Node-RED already installed the recommended install method is to use the editor. To do this, select Manage Pallette from the Node-RED menu (top right), and then select install tab in the pallette. Search for and install this node (node-red-contrib-homekit-bridged).
If you have not yet installed Node-RED then run following command or go to Node-RED Installation Guide.
npm install -g --unsafe-perm node-red
Next, to install node-red-contrib-homekit-bridged node run the following command in your Node-RED user directory - typically ~/.node-red
npm install node-red-contrib-homekit-bridged
You can also pull a docker image containing everything needed to get started, thanks to Raymond Mouthaan.
Please see instructions on Docker Hub.
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 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.
Configuration fields:
- 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.
- Allow Insecure Request: Should we allow insecure request? Default false.
- Manufacturer, Model, Serial Number: Can be anything you want.
- Name: Can be anything you want.
- Allow Message Passthrough: If you allow then message from node input will be send to node output.
- Custom MDNS Configuration: Check if you would like to use custom MDNS configuration.
- Multicast: Use udp multicasting. Optional. Default true.
- Multicast Interface IP: Explicitly specify a network interface. Optional. Defaults to all.
- Port: Set the udp port. Optional. Default 5353.
- Multicast Address IP: Set the udp ip. Optional.
- TTL: Set the multicast ttl. Optional.
- Loopback: Receive your own packets. Optional. Default true.
- Reuse Address: Set the reuseAddr option when creating the socket. Optional. Default true.
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.
Configuration fields:
- Service Hierarchy: Whether the service is Parent or Linked.
- Bridge: On what bridge to host this Service and its Accessory. (Available only for Parent Service)
- Accessory Category: What kind of category is this Accessory. (Available only for Parent Service)
- Parent Service: Which Parent service the Linked service will be connected to. (Available only for Linked Service)
- Service: Choose the type of Service from the list. Services wiki
- Topic: An optional property that can be configured in the node or, if left blank, can be set by msg.topic.
- Manufacturer, Model, Serial Number: Can be anything you want.
- Name: If you intend to simulate a rocket, then why don't you call it Rocket.
- Camera Configuration: Additional configuration for CameraControl service.
- Video Processor: Video processor used for Camera. Default is ffmpeg.
- Source: Camera source used for video processor. Example for ffmpeg -re -i rtsp://192.168.0.227:8554/unicast
- Still Image Source: Camera snapshot source used for video processor. Example for ffmpeg -i http://faster_still_image_grab_url/this_is_optional.jpg
- Max Streams: Maximum number of streams that will be generated for this camera, default 2.
- Max Width: Maximum width reported to HomeKit, default 1280.
- Max Height: Maximum height reported to HomeKit, default 720.
- Max FPS: Maximum frame rate of the stream, default 10.
- Max Bitrate: Maximum bit rate of the stream in kbit/s, default 300.
- Video Codec: If you're running on a RPi with the omx version of ffmpeg installed, you can change to the hardware accelerated video codec with this option, default libx264.
- Audio Codec: If you're running on a RPi with the omx version of ffmpeg installed, you can change to the hardware accelerated audio codec with this option, default libfdk_aac.
- Audio: Can be set to true to enable audio streaming from camera. To use audio ffmpeg must be compiled with --enable-libfdk-aac, default false.
- Packet Size: If audio or video is choppy try a smaller value, set to a multiple of 188, default 1316.
- Vertical Flip: Flips the stream vertically, default false.
- Horizontal Flip: Flips the stream horizontally, default false.
- Map Video: Select the stream used for video, default 0:0.
- Map Audio: Select the stream used for audio, default 0:1.
- Video Filter: Allows a custom video filter to be passed to FFmpeg via -vf, defaults to scale=1280:720.
- Additional Command Line: Allows additional of extra command line options to FFmpeg, default -tune zerolatency.
- Debug: Show the output of ffmpeg in the log, default false.
- Characteristic Properties: Customise the properties of characteristics. Characteristics wiki
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 are in the same format as input messages. They are emitted from the node when it receives Characteristics updates from a paired iOS device.
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.
- AccessoryInformation
- AirPurifier
- AirQualitySensor
- BatteryService
- BridgeConfiguration
- BridgingState
- CameraControl
- CameraRTPStreamManagement
- CarbonDioxideSensor
- CarbonMonoxideSensor
- ContactSensor
- Door
- Doorbell
- Fan
- Fanv2
- Faucet
- FilterMaintenance
- GarageDoorOpener
- HeaterCooler
- HumidifierDehumidifier
- HumiditySensor
- InputSource
- IrrigationSystem
- LeakSensor
- LightSensor
- Lightbulb
- LockManagement
- LockMechanism
- Microphone
- MotionSensor
- OccupancySensor
- Outlet
- Pairing
- ProtocolInformation
- Relay
- SecuritySystem
- ServiceLabel
- Slat
- SmokeSensor
- Speaker
- StatefulProgrammableSwitch
- StatelessProgrammableSwitch
- Switch
- Television
- TelevisionSpeaker
- TemperatureSensor
- Thermostat
- TimeInformation
- TunneledBTLEAccessoryService
- Valve
- Window
- WindowCovering
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"
}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.
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.
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 to upgrade from node-red-homekit
Stop your node-red instance and start it again using the following command:
DEBUG=NRCHKB,Accessory,HAPServer,EventedHTTPServer node-red
This should output detailed information regarding everything in the homekit context.
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.
Big thanks to all who have contributed to the project.
Shaq - leading the current efforts to fix bugs and add features
crxporter - a lot of work on documentation and new features design
Oliver Rahner - reworked the code to add bridged mode - read his story
Marius Schmeding - original implementation of HAP-NodeJS into Node-RED
HAP-NodeJS - NodeJS implementation of Apple's HomeKit Accessory Server