@oznu/hap-nodejs

HAP-NodeJS is a Node.js implementation of HomeKit Accessory Server.

Usage no npm install needed!

<script type="module">
  import oznuHapNodejs from 'https://cdn.skypack.dev/@oznu/hap-nodejs';
</script>

README

HAP-NodeJS

NPM version

HAP-NodeJS is a Node.js implementation of the HomeKit Accessory Server.

With this project, you should be able to create your own HomeKit Accessory on a Raspberry Pi, Intel Edison, or any other platform that can run Node.js :)

The implementation may not 100% follow the HAP MFi Specification since the MFi program doesn't allow individual developers to join.

Remember to run npm install before actually running the server.

Users can define their own accessories in: accessories/[name]_accessory.js files, where [name] is a short description of the accessory. All defined accessories get loaded on server start. You can define accessories using an object literal notation (see Fan_accessory.js for an example) or you can use the API (see below).

You can use the following command to start the HAP Server in Bridged mode:

node BridgedCore.js

Or, if you wish to host each Accessory as an independent HomeKit device:

node Core.js

The HAP-NodeJS library uses the debug library for log output. You can print some or all of the logs by setting the DEBUG environment variable. For instance, to see all debug logs while running the server:

DEBUG=* node BridgedCore.js

HOMEKIT PROTOCOL

Hint: the Homekit Application Protocol (HAP) allows that you can pair a Homekit device with one device. As soon as the Homekit device is paired, its not possible to pair with another iOS device anymore.

API

HAP-NodeJS provides a set of classes you can use to construct Accessories programatically. For an example implementation, see Lock_accessory.js.

The key classes intended for use by API consumers are:

  • Accessory: Represents a HomeKit device that can be published on your local network.
  • Bridge: A kind of Accessory that can host other Accessories "behind" it while only publishing a single device.
  • Service: Represents a set of grouped values necessary to provide a logical function. Most of the time, when you think of a supported HomeKit device like "Thermostat" or "Door Lock", you're actualy thinking of a Service. Accessories can expose multiple services.
  • Characteristic: Represents a particular typed variable assigned to a Service, for instance the LockMechanism Service contains a CurrentDoorState Characteristic describing whether the door is currently locked.

All known built-in Service and Characteristic types that HomeKit supports are exposed as a separate subclass in HomeKitTypes.

See each of the corresponding class files for more explanation and notes.

Notes

Special thanks to Alex Skalozub, who reverse engineered the server side HAP. You can find his research at here. (Sadly, on Nov 4, Apple sent the DMCA request to Github to remove the research.)

There is a video demo running this project on Intel Edison.

If you are interested in HAP over BTLE, you might want to check this.

Projects based on HAP-NodeJS

  • Homebridge - HomeKit support for the impatient - Pluggable HomeKit Bridge. Plugins available for e.g. Pilight, Telldus TDtool, Savant, Netatmo, Open Pixel Control, HomeWizard, Fritz!Box, LG WebOS TV, Home Assistant, HomeMatic and many many more.
  • OpenHAB-HomeKit-Bridge - OpenHAB HomeKit Bridge bridges openHAB items to AppleĀ“s HomeKit Accessory Protocol.
  • homekit2mqtt - HomeKit to MQTT bridge.
  • pimatic-hap - Pimatic homekit bridge.
  • node-red-contrib-homekit - Node-RED nodes to simulate Apple HomeKit devices.
  • ioBroker.homekit - connect ioBroker to HomeKit.
  • AccessoryServer - HomeKit integration for IR/RF/IP-devices