Important: This documentation covers Yarn 1 (Classic).
For Yarn 2+ docs and migration guide, see yarnpkg.com.

Package detail

hap-nodejs

homebridge48.3kApache-2.01.1.1TypeScript support: included

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

hap-nodejs, hap, homekit, homekit-accessory-protocol, homekit-server, homekit-protocol, homekit-device, homekit-accessory, hap-server, homekit-support, siri

readme

HAP-NodeJS


Coverage Status

HAP-NodeJS is an implementation of the HomeKit Accessory Server as specified in the HomeKit Accessory Protocol (HAP), which is defined by Apple as part of the HomeKit Framework.

HAP-NodeJS is intended to be used as a library to easily create your own HomeKit Accessory on a Raspberry Pi, Intel Edison, or any other platform that can run Node.js :)
If you are searching for a pluggable HomeKit bridge with over a thousand community driven plugins to bring HomeKit support to devices which do not support HomeKit out of the box, you may want to look at the homebridge project (which also uses HAP-NodeJS internally).

The implementation tries to follow the HAP specification as close as it can, but may differ in some cases. HAP-NodeJS is not an Apple certified HAP implementation, as this is only available to members of the MFi program.

Getting started

You may start by having a look at our Wiki, especially have a look at the Important HomeKit Terminology used in this project.

There is also a pretty detailed guide on how to start developing with HAP-NodeJS. Or you may just have a look at our examples repository (or some of the old accessory examples).

The documentation (WIP) can be found here.

See the FAQ on how to enable debug output for HAP-NodeJS.

If you wish to do a contribution please read through our CONTRIBUTING guide.

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 more.
  • OpenHAB-HomeKit-Bridge - OpenHAB HomeKit Bridge bridges openHAB items to Apples 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

Notes

Special thanks to Alex Skalozub, who reverse-engineered the server side HAP. You can find his research here. (Sadly, on Nov 4 2014, 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.

changelog

Change Log

All notable changes to hap-nodejs will be documented in this file. This project tries to adhere to Semantic Versioning.

v1.1.0 (2025-02-11)

Changes

  • Update name checking (#1083)

Other Changes

  • Update docs
  • support node 22 + dependency updates (#1075)

v1.1.0 (2024-07-21)

Changes

  • Set Ciao as the default Advertiser

Other Changes

  • Update docs
  • Updated dependencies

v1.0.0 (2024-07-10)

Breaking Changes

  • The minimum Node.js version required is now v18.
  • Important notice: Because of the cleanup of the Deprecated code, you will need to migrate you code base.
    • Remove the long-deprecated init().
    • Deprecate Core, BridgedCore, legacy Camera characteristics. (#1058) (@hjdhjd)
    • Legacy code deprecation cleanup. (#1059) (@hjdhjd)
      • For deprecated storagePath switch to HAPStorage.setCustomStoragePath, AudioCodec switch to AudioStreamingCodec, VideoCodec switch to H264CodecParameters,StreamAudioParams switch to AudioStreamingOptions, StreamVideoParams switch to VideoStreamingOptions,cameraSource switch to CameraController.
    • Others deprecated code to highlight removed: useLegacyAdvertiser, AccessoryLoader.
  • Fix: Naming for Characteristic.ProgramMode has been corrected from PROGRAM_SCHEDULED_MANUAL_MODE_ to PROGRAM_SCHEDULED_MANUAL_MODE

Fixed

  • Fix: Build Issues (#1041) (@NorthernMan54)
  • Fix: Ensure data is only transmitted on open and ready connections. (#1051) (@hjdhjd)
  • Fix: Ensure we check names using the full UTF-8 character set. (#1052) (@hjdhjd)
  • Fix: ConfiguredName (#1049) (@donavanbecker)
  • Fix: Manufacturer looking at checkName but should look at checkValue. (#1053) (@donavanbecker)

Other Changes

  • Implement warning messages for invalid characters in names (#1009) (@NorthernMan54)
  • Mitigate event emitter "memory leak" warnings when a significant number of camera streaming events occur simultaneously (#1037) (@hjdhjd)
  • AdaptiveLightingController fix & improvement (#1038) (@Shaquu)
  • Minor fixes to recording logging and one change in logging. (#1040) (@hjdhjd)
  • Bridged core and core cleanup (#1048) (@Shaquu)
  • Increase snapshot handler warning timeout to 8000ms. (#1055) (@hjdhjd)
  • Cleanup and refactor getLocalNetworkInterface and address a potential edge case. (#1056) (@hjdhjd)
  • Correct log spacing
  • Updated and fixed typedoc config file
  • Updated dependencies

Homebridge Dependencies

  • @homebridge/ciao @ v1.3.0
  • bonjour-hap @ v3.8.0

v0.12.3 (2024-10-25)

Changed

  • minor dependency update
  • mark compatible with node v22
  • fix initWithServices reference in typedoc

Homebridge Dependencies

  • @homebridge/ciao @ v1.3.0
  • bonjour-hap @ v3.8.0

v0.12.2 (2024-05-31)

Changed

  • Updated dependencies (rimraf and @types/node)
  • Updated dependencies (simple-plist)
  • Updated dependencies (typescript)

Homebridge Dependencies

  • @homebridge/ciao @ v1.2.0
  • @homebridge/dbus-native @ v0.6.0

v0.12.1 (2024-05-11)

Changed

  • Updated dependencies (axios and commander)

Fixed

  • Mitigate event emitter "memory leak" warnings when a significant number of HSV events occur simultaneously (#1029) (@hjdhjd)

Other Changes

  • Update Discord Webhooks to trigger only after published to npm

Homebridge Dependencies

  • @homebridge/ciao @ v1.2.0
  • @homebridge/dbus-native @ v0.6.0

v0.12.0 (2024-04-19)

Changed

  • Create CHANGELOG.md file
  • Fix: typos + add logo to README.md
  • Refresh package-lock.json (no major changes to dep versions)
  • general repo updates
  • add alpha releases
  • dependency updates
  • Fix: typedoc generation
  • update homebridge dependencies
  • regenerate docs

Homebridge Dependencies

  • @homebridge/ciao @ v1.2.0
  • @homebridge/dbus-native @ v0.6.0