hc

README

HomeControl

HomeControl is an implementation of the HomeKit Accessory Protocol (HAP) to create your own HomeKit accessory in Go. HomeKit is a set of protocols and libraries to access devices for Home Automation. The actual protocol documentation is only available to MFi members. A non-commercial version of the documentation is now available on the HomeKit developer website.

You can use this library to make existing Home Automation devices HomeKit compatible. I've already developed the following HomeKit bridges with in:

• LIFX
• UVR1611
• Fronius Symo

HomeKit on iOS

HomeKit is fully integrated since iOS 8. Developers can use the HomeKit framework to communicate with HomeKit using high-level APIs. I've developed the Home app (for iPhone, iPad, Apple Watch) to control HomeKit accessories. If you purchase Home on the App Store, you not only support my work but also get an awesome iOS app. Thank you.

Once you've setup HomeKit, you can use Siri to interact with your accessories using voice command (Hey Siri, turn off the lights in the living room).

Features

• Full implementation of the HAP in Go
• Built-in service announcement via DNS-SD using dnssd
• Runs on multiple platforms (already in use on Linux and OS X)
• Documentation: http://godoc.org/github.com/brutella/hc

Getting Started

1. Install Go

2. Setup Go workspace

3. Create your own HomeKit bridge 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
    go run hklightd.go
   

4. Pair with your HomeKit App of choice (e.g. Home)

API Example

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() {
	info := accessory.Info{
		Name: "Lamp",
	}
	acc := accessory.NewSwitch(info)
    
    config := hc.Config{Pin: "00102003"}
	t, err := hc.NewIPTransport(config, acc.Accessory)
	if err != nil {
		log.Panic(err)
	}
    
    hc.OnTermination(func(){
        <-t.Stop()
    })
    
	t.Start()
}

You should change some default values for your own needs

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

Callbacks

You get a callback when the power state of a switch changed by a client.

acc.Switch.On.OnValueRemoteUpdate(func(on bool) {
	if on == true {
		log.Println("Client changed switch to on")
	} else {
		log.Println("Client changed switch to off")
	}
})

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

acc.Switch.On.SetValue(true)

A complete example is available in _example/example.go.

Model

The HomeKit model hierarchy looks like this:

Accessory
|-- Accessory Info Service
|   |-- Identify Characteristic
|   |-- Manufacturer Characteristic
|   |-- Model Characteristic
|   |-- Name Characteristic
|   |-- Serial Characteristic
|   
|-- * Service
|   |-- * Characteristic

HomeKit accessories are container for services. Every accessory must provide the Accessory Information Service. Every service provides one or more characteristics (a characteristic might be the power state of an outlet). HomeKit has predefined service and characteristic types, which are supported by iOS. You can define your own service and characteristic types, but it's recommended to use predefined ones.

This library provides all HomeKit characteristics (see characteristic package) and services (see service package). You can also find common accessory types like lightbulbs, outlets, thermostats in the accessory package.

Dependencies

HomeControl uses vendor directories (vendor/) to integrate the following libraries

• github.com/tadglines/go-pkgs/crypto/srp for SRP algorithm
• github.com/agl/ed25519 for ed25519 signature
• github.com/gosexy/to for type conversion
• github.com/brutella/dnssd for DNS service discovery

Contact

Matthias Hochgatterer

Website: http://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.

Documentation

Overview

Package hc provides implementation of an IP transport for HomeKit accessories.

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

acc := accessory.NewSwitch(...)
config := hc.Config{Pin: "00102003"}
t, err := hc.NewIPTransport(config, acc.Accessory)
...
t.Start()

Index

• func NewPin(pin string) (string, error)
• func OnTermination(fn TermFunc)
• type Config
• type MDNSService
  • func NewMDNSService(config *Config) *MDNSService
  • func (s *MDNSService) Publish(ctx context.Context) error
  • func (s *MDNSService) Stop()
  • func (s *MDNSService) Update()
• type TermFunc
• type Transport
  • func NewIPTransport(config Config, a *accessory.Accessory, as ...*accessory.Accessory) (Transport, error)

Functions

func NewPin

func NewPin(pin string) (string, error)

NewPin returns a HomeKit compatible pin string from a 8-numbers strings e.g. '01020304'.

func OnTermination

func OnTermination(fn TermFunc)

OnTermination calls a function when the app receives an interrupt of kill signal.

Types

type Config

type Config struct {
	// An object that stores persistent data for hc
	// When nil, the transport will fallback to using file storage with the StoragePath directory
	Storage util.Storage

	// Path to the storage
	// When empty, the tranport stores the data inside a folder named exactly like the accessory
	StoragePath string

	// Port on which transport is reachable e.g. 12345
	// When empty, the transport uses a random port
	Port string

	// IP on which clients can connect.
	IP string

	// Pin with has to be entered on iOS client to pair with the accessory
	// When empty, the pin 00102003 is used
	Pin string
	// contains filtered or unexported fields
}

Config provides basic cfguration for an IP transport

type MDNSService

type MDNSService struct {
	// contains filtered or unexported fields
}

MDNSService represents a mDNS service.

func NewMDNSService

func NewMDNSService(config *Config) *MDNSService

NewMDNSService returns a new service based for the bridge name, id and port.

func (*MDNSService) Publish

func (s *MDNSService) Publish(ctx context.Context) error

Publish announces the service for the machine's ip address on a random port using mDNS.

func (*MDNSService) Stop

func (s *MDNSService) Stop()

Stop stops the running mDNS service.

func (*MDNSService) Update

func (s *MDNSService) Update()

Update updates the mDNS txt records.

type TermFunc

type TermFunc func()

TermFunc defines the function which is executed on termination.

type Transport

type Transport interface {
	// Start starts the transport
	Start()

	// Stop stops the transport
	// Use the returned channel to wait until the transport is fully stopped.
	Stop() <-chan struct{}
}

Transport provides accessories over a network.

func NewIPTransport

func NewIPTransport(config Config, a *accessory.Accessory, as ...*accessory.Accessory) (Transport, error)

NewIPTransport creates a transport to provide accessories over IP.

The IP transports stores the crypto keys inside a database, which is by default inside a folder at the current working directory. The folder is named exactly as the accessory name.

The transports can contain more than one accessory. If this is the case, the first accessory acts as the HomeKit bridge.

*Important:* Changing the name of the accessory, or letting multiple transports store the data inside the same database lead to unexpected behavior – don't do that.

The transport is secured with an 8-digit pin, which must be entered by an iOS client to successfully pair with the accessory. If the provided transport config does not specify any pin, 00102003 is used.