You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
HomeControl is an implementation of the [HomeKit][homekit] Accessory Protocol (HAP) to create your own HomeKit accessory in [Go](https://golang.org). [HomeKit][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](https://developer.apple.com/homekit/).
5
+
`hc` is a lightweight framework to develop HomeKit accessories in Go.
6
+
It abstracts the **H**omeKit **A**ccessory **P**rotocol (HAP) and makes it easy to work with [services](service/README.md) and [characteristics](characteristic/README.md).
6
7
7
-
You can use this library to make existing Home Automation devices HomeKit compatible. I've already developed the following HomeKit bridges with in:
8
+
`hc` handles the underlying communication between HomeKit accessories and clients.
9
+
You can focus on implementing the business logic for your accessory, without having to worry about the protocol.
[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](https://developer.apple.com/homekit/).
20
+
21
+
HomeKit is fully integrated into iOS since iOS 8. Developers can use [HomeKit.framework](https://developer.apple.com/documentation/homekit) to communicate with accessories using high-level APIs.
HomeKit is fully integrated since iOS 8. Developers can use the HomeKit framework to communicate with HomeKit using high-level APIs.
16
-
I've developed the [Home][home] app (for iPhone, iPad, Apple Watch) to control HomeKit accessories. If you [purchase Home][home-appstore] on the App Store, you not only support my work but also get an awesome iOS app. Thank you.
25
+
I've developed the [Home][home] app to control HomeKit accessories from iPhone, iPad, and Apple Watch.
26
+
If you want to support `hc`, please purchase Home from the [App Store][home-appstore]. That would be awesome. ❤️
17
27
18
-
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*).
2.[Setup Go workspace](http://golang.org/doc/code.html#Organization)
35
-
3. Create your own HomeKit bridge or clone an existing one (e.g. [hklight](https://github.com/brutella/hklight))
47
+
1.[Install](http://golang.org/doc/install) and [set up](http://golang.org/doc/code.html#Organization) Go
48
+
2. Create your own HomeKit accessory or clone an existing one (e.g. [hklight](https://github.com/brutella/hklight))
36
49
37
50
cd $GOPATH/src
38
51
39
52
# Clone project
40
53
git clone https://github.com/brutella/hklight && cd hklight
41
54
42
55
# Run the project
43
-
go run hklightd.go
56
+
make run
57
+
58
+
3. Pair with your HomeKit App of choice (e.g. [Home][home-appstore])
59
+
60
+
**Go Modules**
61
+
62
+
`hc` supports [Go module](https://github.com/golang/go/wiki/Modules) since `v1.0.0`.
63
+
Make sure to set the environment variable `GO111MODULE=on`.
44
64
45
-
4. Pair with your HomeKit App of choice (e.g. [Home][home-appstore])
65
+
## Example
46
66
47
-
## API Example
67
+
See [_example](_example) for a variety of examples.
68
+
69
+
**Basic switch accessory**
48
70
49
71
Create a simple on/off switch, which is accessible via IP and secured using the pin *00102003*.
50
72
@@ -58,88 +80,76 @@ import (
58
80
)
59
81
60
82
funcmain() {
61
-
info:= accessory.Info{
62
-
Name: "Lamp",
63
-
}
64
-
acc:= accessory.NewSwitch(info)
83
+
// create an accessory
84
+
info:= accessory.Info{Name: "Lamp"}
85
+
ac:= accessory.NewSwitch(info)
65
86
87
+
// configure the ip transport
66
88
config:= hc.Config{Pin: "00102003"}
67
-
t, err:= hc.NewIPTransport(config, acc.Accessory)
68
-
if err != nil {
69
-
log.Panic(err)
70
-
}
89
+
t, err:= hc.NewIPTransport(config, ac.Accessory)
90
+
if err != nil {
91
+
log.Panic(err)
92
+
}
71
93
72
94
hc.OnTermination(func(){
73
95
<-t.Stop()
74
96
})
75
97
76
-
t.Start()
98
+
t.Start()
77
99
}
78
100
```
79
101
80
-
You should change some default values for your own needs
102
+
You can define more specific accessory info, if you want.
81
103
82
104
```go
83
105
info:= accessory.Info{
84
-
Name: "Lamp",
85
-
SerialNumber: "051AC-23AAM1",
86
-
Manufacturer: "Apple",
87
-
Model: "AB",
88
-
Firmware: "1.0.1",
106
+
Name: "Lamp",
107
+
SerialNumber: "051AC-23AAM1",
108
+
Manufacturer: "Apple",
109
+
Model: "AB",
110
+
Firmware: "1.0.1",
89
111
}
90
112
```
91
113
92
-
### Callbacks
114
+
### Events
93
115
94
-
You get a callback when the power state of a switch changed by a client.
116
+
The library provides callback functions, which let you know when a clients updates a characteristic value.
117
+
The following example shows how to get notified when the [On](characteristic/on.go) characteristic value changes.
95
118
96
119
```go
97
-
acc.Switch.On.OnValueRemoteUpdate(func(on bool) {
98
-
if on == true {
99
-
log.Println("Client changed switch to on")
100
-
} else {
101
-
log.Println("Client changed switch to off")
102
-
}
120
+
ac.Switch.On.OnValueRemoteUpdate(func(on bool) {
121
+
if on == true {
122
+
log.Println("Switch is on")
123
+
} else {
124
+
log.Println("Switch is off")
125
+
}
103
126
})
104
127
```
105
128
106
129
When the switch is turned on "the analog way", you should set the state of the accessory.
107
130
108
-
acc.Switch.On.SetValue(true)
109
-
110
-
A complete example is available in `_example/example.go`.
111
-
112
-
## Model
113
-
114
-
The HomeKit model hierarchy looks like this:
115
-
116
-
Accessory
117
-
|-- Accessory Info Service
118
-
| |-- Identify Characteristic
119
-
| |-- Manufacturer Characteristic
120
-
| |-- Model Characteristic
121
-
| |-- Name Characteristic
122
-
| |-- Serial Characteristic
123
-
|
124
-
|-- * Service
125
-
| |-- * Characteristic
131
+
```go
132
+
ac.Switch.On.SetValue(true)
133
+
```
126
134
127
-
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.
135
+
## Accessory Architecture
128
136
129
-
## Dependencies
137
+
HomeKit uses a hierarchical architecture for define accessories, services and characeristics.
138
+
At the root level there is an accessory.
139
+
Every accessory contains services.
140
+
And every service contains characteristics.
130
141
131
-
HomeControl uses vendor directories (`vendor/`) to integrate the following libraries
142
+
For example a [lightbulb accessory](accessory/lightbulb.go) contains a [lightbulb service](service/lightbulb.go).
143
+
This service contains characteristics like [on](characteristic/on.go) and [brightness](characteristic/brightness.go).
132
144
133
-
-`github.com/tadglines/go-pkgs/crypto/srp` for *SRP* algorithm
134
-
-`github.com/agl/ed25519` for *ed25519* signature
135
-
-`github.com/gosexy/to` for type conversion
136
-
-`github.com/brutella/dnssd` for DNS service discovery
145
+
There are predefined accessories, services and characteristics available in HomeKit.
146
+
Those types are defined in the packages [accessory](accessory), [service](service), [characteristic](characteristic).
0 commit comments