HomeControl

HomeControl is an implementation of the HomeKit Accessory Protocol (HAP) to create your own HomeKit accessory and bridges. HomeKit bridges make non-HomeKit accessories available to HomeKit by acting as a middleman.

Overview

HomeKit is a set of protocols and libraries to access accessories for Home Automation. Unfortunately the protocol is not open source and the official documentation is only available to MFi members. HomeControl is a complete implementation of the protocol in Go and does not depend on any OS.

HomeKit Client

I've made an app for iPhone, iPad and Apple Watch called Home to control any HomeKit accessory. If you purchase Home on the App Store, you not only support my work but also get an awesome iOS app. Thank you.

Features

• Full implementation of the HomeKit Accessory Protocol in pure Go
  • Support for switch, outlet, light bulb, thermostat accessory
• Built-in service announcement via mDNS using bonjour
• Optional logging with https://github.com/brutella/log
• 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
    
    # Install dependencies
    go get
    
    # 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/hap"
    "github.com/brutella/hc/model"
    "github.com/brutella/hc/model/accessory"
)

func main() {
	info := model.Info{
		Name: "Lamp",
	}
	sw := accessory.NewSwitch(info)
    
	t, err := hap.NewIPTransport("00102003", sw.Accessory)
	if err != nil {
		log.Fatal(err)
	}
    
    hap.OnTermination(func(){
        t.Stop()
    })
    
	t.Start()
}

You should change some default values for your own needs

info := model.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.

sw.OnStateChanged(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.

sw.SetOn(true)

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

Dependencies

HomeControl depends on the following libraries

• github.com/tadglines/go-pkgs/crypto/srp for SRP algorithm
• github.com/codahale/chacha20 for chacha20 poly1305 algorithm
• github.com/golang/cryptofor chacha20 poly1305 algorithm and curve25519 key generation
• github.com/agl/ed25519 for ed25519 signature
• github.com/gosexy/to for type conversion
• github.com/oleksandr/bonjour for mDNS

HomeKit Accessories

HomeControl currently supports the following accessory types

• Switch
• Outlet
• Light Bulb
• Thermostat
• Thermometer (same as the Thermostat accessory which just readonly services)

The metdata dump in iOS 8.3 (found by @KhaosT) includes a list of required and optional characteristics.

Service	Required	Optional
Accessory Information	name, manufacturer, model, serial-number, identify	firmware.revision, hardware.revision, software.revision
Switch	on	name
Outlet	on, outlet-in-use	name
Fan	on	name, rotation.direction, rotation.speed
Thermostat	heating-cooling.current, heating-cooling.target, temperature.current, temperature.target, temperature.units	name, relative-humidity.current, relative-humidity.target, temperature.cooling-threshold, temperature.heating-threshold
Garage Door Opener	door-state.current, door-state.target, obstruction-detected	lock-mechanism.current-state, lock-mechanism.target-state, name
Light Bulb	on	name, brightness, hue, saturation
Lock Management	version, lock-management.control-point	administrator-only-access, audio-feedback, door-state.current, lock-management.auto-secure-timeout, lock-mechanism.last-known-action, logs, motion-detected
Lock Mechanism	lock-mechanism.current-state, lock-mechanism.target-state	name

The HomeKit framework on iOS uses the same order as in the json. I assume that clients displays them in the same order to the user.

iOS 9

iOS 9 supports new type of accessories and includes new service and characteristic types. The new types are already available in model/service/constants.go and model/characteristic/constants.go.

Contact

Matthias Hochgatterer

Github: https://github.com/brutella

Twitter: https://twitter.com/brutella

License

HomeControl is available under a non-commercial license. See the LICENSE file for more info.