hc

package module
Version: v1.2.4 Latest Latest
Warning

This package is not in the latest version of its module.

Go to latest
Published: Feb 18, 2021 License: Apache-2.0 Imports: 26 Imported by: 66

README

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.

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",
    FirmwareRevision: "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)

Multiple Accessories

When you create an IP transport, you can specify more than one accessory like this

bridge := accessory.NewBridge(...)
outlet := accessory.NewOutlet(...)
lightbulb := accessory.NewColoredLightbulb(...)

hc.NewIPTransport(config, bridge.Accessory, outlet.Accessory, lightbulb.Accessory)

By doing so, the bridge accessory will become a HomeKit bridge. The outlet and lightbulb are the bridged accessories.

When adding the accessories to HomeKit, iOS only shows the bridge accessory. Once the bridge was added, the other accessories appear automatically.

HomeKit requires that every accessory has a unique id, which must not change between system restarts. hc automatically assigns the ids for you based on the order in which the accessories are added to the bridge.

But I recommend that you specify the accessory id yourself, via the accessory.Config.ID field, like this.

bridge := accessory.NewBridge(accessory.Info{Name: "Bridge", ID: 1})
outlet := accessory.NewOutlet(accessory.Info{Name: "Outlet", ID: 2})
lightbulb := accessory.NewColoredLightbulb(accessory.Info{Name: "Light", ID: 3})

Accessory Architecture

HomeKit uses a hierarchical architecture to 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.

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

Constants

This section is empty.

Variables

This section is empty.

Functions

func NewIPTransport

func NewIPTransport(config Config, a *accessory.Accessory, as ...*accessory.Accessory) (*ipTransport, 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.

func OnTermination

func OnTermination(fn TermFunc)

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

func ValidatePin added in v1.2.3

func ValidatePin(pin string) (string, error)

ValidatePin validates a HomeKit pin.

Types

type Config

type Config struct {
	// 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

	// Deprecated: Specifying a static IP is discouraged.
	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

	// SetupId used for setup code should be 4 uppercase letters
	SetupId string
	// contains filtered or unexported fields
}

Config holds configuration options.

func (*Config) XHMURI added in v1.2.2

func (cfg *Config) XHMURI(flag util.SetupFlag) (string, error)

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.

Directories

Path Synopsis
tv
THIS FILE IS AUTO-GENERATED Package accessory implements the HomeKit accessories.
THIS FILE IS AUTO-GENERATED Package accessory implements the HomeKit accessories.
THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED Package characteristic implements the HomeKit characteristics.
THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED Package characteristic implements the HomeKit characteristics.
Package crypto provides the crypthographic algorithm used in the HAP protocol.
Package crypto provides the crypthographic algorithm used in the HAP protocol.
Package db implements persistent storage.
Package db implements persistent storage.
gen
hap
Package hap implements the HomeKit Accessory Protocol to pair and securily communicate with a HomeKit client.
Package hap implements the HomeKit Accessory Protocol to pair and securily communicate with a HomeKit client.
data
Package data provides structs to map json to objects.
Package data provides structs to map json to objects.
endpoint
Package endpoint implements the HAP endpoints.
Package endpoint implements the HAP endpoints.
http
Package http implements a http-like hap server to handle requests and responses.
Package http implements a http-like hap server to handle requests and responses.
pair
Package pair implements the pairing and verification protocol.
Package pair implements the pairing and verification protocol.
THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED Package service implements the HomeKit services.
THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED THIS FILE IS AUTO-GENERATED Package service implements the HomeKit services.
Package util provides utilities.
Package util provides utilities.

Jump to

Keyboard shortcuts

? : This menu
/ : Search site
f or F : Jump to
t or T : Toggle theme light dark auto
y or Y : Canonical URL