Skip to content
hc is a lightweight framework to develop HomeKit accessories in Go.
Go
Branch: master
Clone or download
Permalink
Type Name Latest commit message Commit time
Failed to load latest commit information.
_example
_img Update readme Nov 25, 2019
accessory
characteristic
cmd Generate markdown tables to summarize HomeKit services and characteri… Feb 9, 2018
crypto
db Add method to get all entities from the database Oct 12, 2015
event
gen
hap
log
rtp
service
tlv8
util
.gitignore
.travis.yml
CREDITS
LICENSE
README.md
config.go Support creating X-HM URIs based on config Dec 9, 2019
config_test.go Fix unit test Dec 9, 2019
doc.go Update go doc Apr 28, 2016
go.mod
go.sum Switch github.com/gosexy/to to github.com/xiam/to Nov 23, 2019
ip_transport.go Document method which returns X-HM styled uri Dec 9, 2019
password.go
password_test.go
termination.go
transport.go

README.md

hc

GoDoc Widget Travis Widget

hc is a lightweight framework to develop HomeKit accessories in Go. It abstracts the HomeKit Accessory Protocol (HAP) and makes it easy to work with services and characteristics.

hc handles the underlying communication between HomeKit accessories and clients. You can focus on implementing the business logic for your accessory, without having to worry about the protocol.

Here are some projects which use hc.

What is HomeKit?

HomeKit is a set of protocols and libraries from Apple. It is used by Apple's platforms to communicate with smart home appliances. A non-commercial version of the documentation is now available on the HomeKit developer website.

HomeKit is fully integrated into iOS since iOS 8. Developers can use HomeKit.framework to communicate with accessories using high-level APIs.

Home+.app

I've developed the Home+ app to control HomeKit accessories from iPhone, iPad, and Apple Watch. If you want to support hc, please purchase Home from the App Store. That would be awesome. ❤️

Checkout the official website.

Features

Getting Started

  1. Install and set up Go

  2. Create your own HomeKit accessory or clone an existing one (e.g. hklight)

     cd $GOPATH/src
     
     # Clone project
     git clone https://github.com/brutella/hklight && cd hklight
     
     # Run the project
     make run
    
  3. Pair with your HomeKit App of choice (e.g. Home)

Go Modules

hc supports Go module since v1.0.0. Make sure to set the environment variable GO111MODULE=on.

Example

See _example for a variety of examples.

Basic switch accessory

Create a simple on/off switch, which is accessible via IP and secured using the pin 00102003.

package main

import (
    "log"
    "github.com/brutella/hc"
    "github.com/brutella/hc/accessory"
)

func main() {
    // create an accessory
    info := accessory.Info{Name: "Lamp"}
    ac := accessory.NewSwitch(info)
    
    // configure the ip transport
    config := hc.Config{Pin: "00102003"}
    t, err := hc.NewIPTransport(config, ac.Accessory)
    if err != nil {
        log.Panic(err)
    }
    
    hc.OnTermination(func(){
        <-t.Stop()
    })
    
    t.Start()
}

You can define more specific accessory info, if you want.

info := accessory.Info{
    Name: "Lamp",
    SerialNumber: "051AC-23AAM1",
    Manufacturer: "Apple",
    Model: "AB",
    Firmware: "1.0.1",
}

Events

The library provides callback functions, which let you know when a clients updates a characteristic value. The following example shows how to get notified when the On characteristic value changes.

ac.Switch.On.OnValueRemoteUpdate(func(on bool) {
    if on == true {
        log.Println("Switch is on")
    } else {
        log.Println("Switch is off")
    }
})

When the switch is turned on "the analog way", you should set the state of the accessory.

ac.Switch.On.SetValue(true)

Accessory Architecture

HomeKit uses a hierarchical architecture for define accessories, services and characeristics. At the root level there is an accessory. Every accessory contains services. And every service contains characteristics.

For example a lightbulb accessory contains a lightbulb service. This service contains characteristics like on and brightness.

There are predefined accessories, services and characteristics available in HomeKit. Those types are defined in the packages accessory, service, characteristic.

Contact

Matthias Hochgatterer

Website: https://hochgatterer.me

Github: https://github.com/brutella

Twitter: https://twitter.com/brutella

License

hc is available under the Apache License 2.0 license. See the LICENSE file for more info.

You can’t perform that action at this time.