Repository files navigation

HAP is a framework for building DIY HomeKit accessories based on Apple'sHomeKit Accessory Protocol specification.You can think of it ashomebridge for Elixir (with a bit more of a focus onbuilding actual accessories via Nerves) in contrast to Homebridge's typical use as a bridge to existing accessories.

As shown in theHAP Demo project, integrating HAP support into an existing Elixirproject is extremely straightforward - all that is required in most cases is to define the services and characteristicsyou wish to expose, and to provide an implementation ofHAP.ValueStore for each non-static characteristic you define.

In many cases, integrating with HAP can be as simple as:

accessory_server=%HAP.AccessoryServer{name:"My HAP Demo Device",model:"HAP Demo Device",identifier:"11:22:33:44:12:66",accessory_type:5,accessories:[%HAP.Accessory{name:"My HAP Lightbulb",services:[%HAP.Services.LightBulb{on:{MyApp.Lightbulb,gpio_pin:23}}]}]}children=[{HAP,accessory_server}]Supervisor.start_link(children,opts)...

As originally developed, HAP included a fairly small set of services & characteristics (mostly due to the author'slaziness & the immediate need for only a handful of the ~45 services & ~128 characteristics defined in thespecification). However, it is quite easy to add definitions for new services & characteristics, and PRs to add suchdefinitions are extremely welcome. Thelightbulb serviceis a complete implementation of a service and serves as an excellent starting point for creating your own. You can consultsections 8 and 9 of theHomeKit Accessory Protocol Specification to determinewhat characteristics are required and optional for a given service. Note that only implementations of public services andcharacteristics as defined in the HomeKit specification will be considered for inclusion in HAP.

HAP supports notifications (as defined in section 6.8 of theHomeKit Accessory ProtocolSpecification). This allows your accessory to notify HomeKit of changes whichhappen asynchronously, such as a user pushing a button on the accessory, or a sensor detecting a water leak. To sendsuch notifications, yourHAP.ValueStore implementation must support thec:HAP.ValueStore.set_change_token/2callback. Consult theHAP.ValueStore documentation for more detail.

• No support for dynamically updating the services advertised by a HAP instance (this is slated for HAP 2.0)
• Incomplete support for tearing down existing sessions on pairing removal (this is slated for HAP 2.0)
• No support for HomeKit Secure Video / RTP (support is not currently planned, but PRs are of course welcome)
• Timed write support is supported, but timeouts are not enforced

In addition, there may well be bugs or gaps in functionality not listed above. If you encounter any, please feel freeto file an issue.

HAP is available in Hex. The package can be installed by adding hap to your list of dependencies in mix.exs:

def deps do  [    {:hap, "~> 0.4"}  ]end

HAP is intended to be used within a host application which provides concrete implementations for various HomeKitcharacteristics. Check out theHAP Demo app for an example of how to use HAP.

Documentation can be found athttps://hexdocs.pm/hap/.

Note that in order to have access to the required crypto methods for HAP to function, OTP 23 or newer is required. Also note that OTP 25.0.x has adefect that breaks HAP (fixed in OTP 25.1 and newer).

MIT