README
Homekit Device Stack
A Middleware Server, for bringing HomeKit functionality to your Home Automation.
Say What!?
HomeKit Device Stack is a NodeJS server with a fully graphical web frontend, if you're a Home Automation Enthusiast, wanting to explore and learn HomeKit, HomeKit Device Stack can do that. If you're a serious Home Automation User, then HomeKit Device Stack plays nice with other automation platforms by using common transport mechanisms.
OK, but what does it actually do?
In essance, you create devices via the web frontend, be it a Smart TV, Intruder Alarm, A Door Sensor, a Thermostat, a Party Switch and many many more. You then have fun with it on your iDevice.
If however, you actually want to gain some usefulness from it, keep reading.
The Keep Reading Part.
After you have created a device, you then wire it to a route which states where the change event should be directed. (Unless you just want to show your geeky mates that you have HomeKit devices)
- HTTP
- UDP Broadcast
- File
- MQTT
In HomeKit Device Stack, The above outputs are refered to as a 'route' you can create any number of routes, and any number of accessories can use a single route. as an example: if you wanted an accessory to forward its state changes to Node-Red, then you can create a UDP route, then have Node-Red listen on the UDP port for the Broadcast. if you have an MQTT broker then you can achieve the same thing or you can simply post the event to a web server.
The payload that is sent via your configured route is below
{
"accessory": {
"type": "SWITCH",
"name": "Switch Accessory Demo",
"accessoryID": "CD2947583B71"
},
"type": "change",
"change": {
"characteristic": "On",
"value": true
},
"source": "iOS_DEVICE",
"route_type": "FILE",
"route_name": "File Output"
}
There are 3 possible event types:
- change | One of the characteristics has changed.
- identify | The device has been identified (clicking identify in iOS)
- pair | The pairing state of the non bridged device has changed.
The source object in the change payload above, identfies where the change occurred iOS_DEVICE or API
This Sounds Familiar
This is not HomeBridge, HomeBridge is designed to bridge the gap between HomeKit and non compatible devices. HomeKit Device Stack is quite different. HomeKit Device Stack has been designed to act as a sink. that is - you wire up the events from your devices into other automations, such as NodeRed, Home Assistant or any other system that can make use of the output mechanisms above.
It's been designed as a universal middleware server - that is, it is capable of working along side other automation platforms.
The devices Homekit Device Stack can create are as follows (more will become available as development progresses)
- Switch
- Outlet
- Television
- CCTV Camera
- Intruder Alarm
- Contact Sensor
- Motion Sensor
- Lock Mechanism
- Garage Door Opener
- Thermostat
- Light Bulb
- Fan
So, it only reports changes?
Nope!
HomeKit Device Stack has 2 network based inputs.
- A REST based HTTP API
- MQTT Topic Subscription
Both these inputs allow manipulation of the accessory states. These altered states are then reflected in HomeApp, or any other Homekit based application.
Changes originating from these inputs will cause routes to trigger, making use of the source object can be used to filter these out.
The URL for the REST API is http://IP-ADDRESS:7989/{password}/
- GET /accessories | Lists all accessories and there current characteristics
- GET /accessories/accessoryID | Same as above but for the identified accessory
- PUT /accessories/accessoryID | Sets characteristics for the identified accessory
The body in your HTTP PUT command, should be nothing more than a JSON object representing the characteristics to set
{
"On": false,
"OutletInUse": true
}
The same format should be used for MQTT messages.
The topic should end with the accessory ID Ex: HKDS/IN/HDSH389HJS.
You can change the leading topic name in the UI. by default its HKDS/IN/.
Does It Run On My Microwave?
Not yet, it theoretically should run on any platform that can run NodeJS (OSX, Windows, Linux, Raspberry Pi etc etc)
Installing
Ensure you have NodeJS and NPM installed. Then install Homekit Device Stack
npm install homekit-device-stack
Running
Within the directory that HomeKit Device Stack is installed.
node App.js
If creating an auto start script - ensure the script is set to run under the installed directory
Command line arguments
reset - Completely Resets HomeKit Device Stack (inits a default configuration)
passwd mypassword - set the admin password
Credits
HomeKit Device Stack is based on the awesome HAP-NodeJS library, without it, projects like this one are not possible.
Version History
3.0.3
Fixed 'Accessory Not Responding' after editing a non bridged device.
Fixed potential crash where a no longer existing route is to trigger.
Added pairing events to out going routes for non-bridged devices
Added pairing pin code to UI for non-bridged devices.3.0.2
House keeping
Further Camera improvements3.0.1
Added delete option when editing routes
Fixed crash on attempting to update an unknown Device ID3.0.0
New User Interface (+ Added route configuration to UI)
Optimisations/Improvements/Bug Fixes to the core code
Optimisations/Improvements/Bug Fixes to the camera implementation
description property of accessories no longer in use.
Added Fan Accessory
Enhanced MQTT Route to allow Accessory ID in the topic name
Enhanced FILE Route to allow Accessory ID in the folder path
Enhanced HTTP Route to allow Accessory ID in the URI
Added ability to publish your accessories attached or detached from a HomeKit 'Bridge'
Added the ability to backup/restore your configuration.
Added the (optional) motion sensor and door bell services to camera accessories
(to support rich notifications in iOS 13+)2.1.0
Bump all dependencies to latest stable releases
Migrated Camera object to latest CameraController API
Added light bulb device.2.0.1
Fixed inability to hide TV inputs from view.
Fixed security issue allowing access without logging in.
Fixed potential ffmpeg process freeze.
Fixed disconnected web client exception.
Added Route type icon to accessory panel2.0.0
BREAKING CHANGES!Bump all dependencies to latest stable releases
Relocated HKDS and HomeKit configuration (config now survives updates)
Make a copy of your config.json file and any files inside the HomeKit dir, then...
config.json should be moved to %Home%/HomeKitDeviceStack
HomeKit/.json* should be moved to %Home%/HomeKitDeviceStack/HomeKitPersistThe directory value for File routes should now only contain a name of a folder
that is relative to %Home%/HomeKitDeviceStack/1.1.3
Update Read Me1.1.2
Improved layout for acessories UI.
Outgoing route performance improvements
Fixed null reference for accessories without a defined route (i.e. camera)1.1.1
Removed unused parameter from Server constructor.1.1.0
Added ability to manipulate devices via MQTT
Improved error handling
Fixed showing loopback address in console.
Switched to using axios for the HTTP route type
Switched to internal NodeJS crypto library1.0.1
Fixed typo in read me1.0.0
Initial Release
To Do
- Continue to add more accessory types