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
Copy file name to clipboardExpand all lines: CHANGELOG.md
+74Lines changed: 74 additions & 0 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -2,6 +2,80 @@
2
2
3
3
All notable changes to this project will be documented in this file. This project uses [Semantic Versioning](https://semver.org/).
4
4
5
+
## v1.3.0 (2021-02-20)
6
+
7
+
### Adaptive Lighting
8
+
9
+
The new Adaptive Lightning feature introduced with iOS 14 can now be used by plugin developers. Most of the actively maintained plugins already secretly added support for it.
10
+
11
+
### Child Bridges
12
+
13
+
Child bridges allow any Homebridge platform or accessory to optionally run as its own independent accessory, separate from the main bridge, and in an isolated process. Running certain accessories in a child bridge can improve the general responsiveness and reliability of Homebridge.
14
+
15
+
Why you might run a child bridge:
16
+
17
+
* To isolate plugin code from the main bridge - in this mode the plugin will run in its own child process, preventing it from ever crashing the main bridge if a fatal exception occurs.
18
+
* If the child bridge process does crash, Homebridge will automatically restart it, without impacting the main bridge or other plugins.
19
+
* To isolate slow plugins, preventing them from slowing down the main bridge or other plugins.
20
+
* To gain the ability to restart individual accessories after a config change or plugin update without having to restart the main bridge or other plugins.
21
+
* To gain all the benefits of running multiple instances of Homebridge without the management overhead.
22
+
23
+
Child bridge support is available for all existing plugins. You can enable it via the Homebridge UI on a acessory/platform basis from the "Bridge Settings" menu item:
* The `"mdns"."interface"` option has been removed, please use `"bridge"."bind"` instead. This new option takes an array of interface names or IP addresses. You can also configure this option using the "Network Interfaces" option under the Homebridge Settings section of the UI.
47
+
48
+
### Other Notable Changes
49
+
50
+
* Added the ability to disable individual plugins without having to remove their config from the `config.json` file.
51
+
* Homebridge will no longer crash if a plugin cannot be found for a certain accessory / platform config block.
52
+
* Improved stability with malfunctioning plugins or plugins which read/write handlers take too long to respond. You may have been there, where you whole Homebridge instance went down only because one plugin or accessory didn't behave properly. We have invested some time to reduce the possibility of such scenarios; or at least give hints where we can reliably detect that something gone wrong.
53
+
* Plugin characteristics are now strictly validated, if an invalid value is passed in the bridge will now force it to a known good value and show a warning in the logs, this should prevent some of the "Not Responding" issues users have faced in the past.
54
+
55
+
### Changes For Developers
56
+
57
+
* Added the ability to use promise-based characteristic getters and setters. Have a look at [characteristic.onGet](https://developers.homebridge.io/HAP-NodeJS/classes/characteristic.html#onget) and [characteristic.onSet](https://developers.homebridge.io/HAP-NodeJS/classes/characteristic.html#onset).
58
+
* Added support for Characteristics with Additional Authorization, by using [characteristic.setupAdditionalAuthorization](https://developers.homebridge.io/HAP-NodeJS/classes/characteristic.html#setupadditionalauthorization).
59
+
* For a more detailed list, have a look at the release notes of `HAP-NodeJS`[v0.9.0](https://github.com/homebridge/HAP-NodeJS/releases/tag/v0.9.0).
60
+
* Added a [API.versionGreaterOrEqual](https://developers.homebridge.io/homebridge/interfaces/api.html#versiongreaterorequal)
61
+
call to the homebridge API object.
62
+
This will from now on replace the float based API `version` number property.
63
+
64
+
### Compatibility
65
+
66
+
Homebridge v1.3.0 does not introduce breaking changes for the majority of existing plugins, while you may see [Characteristic Warnings](https://github.com/homebridge/homebridge/wiki/Characteristic-Warnings) in the logs, these are just issues that were already present prior to v1.3.0 - just hidden from view. You should update your plugins before updating Homebridge.
67
+
68
+
A large number of plugins have been tested during an extensive beta period, the results can be [viewed here](https://github.com/homebridge/homebridge/wiki/Homebridge-1.3.0-Release-Plugin-Testing-Status).
69
+
70
+
### Rolling Back
71
+
72
+
If for any reason Homebridge v1.3.0 is not working for you, you can rollback to a previous version of Homebridge easily using the Homebridge UI:
@@ -39,79 +40,39 @@ HomeKit communities can also be found on both [Discord](https://discord.gg/RcV7f
39
40
40
41
## Installation
41
42
42
-
The [Homebridge Wiki](https://github.com/homebridge/homebridge/wiki) contains step-by-step instruction on how to install Node.js and setup Homebridge as a service so it automatically starts on boot:
43
+
The [Homebridge Wiki](https://github.com/homebridge/homebridge/wiki) contains step-by-step instruction on how to install Node.js and setup Homebridge and the [Homebridge UI](https://github.com/oznu/homebridge-config-ui-x)as a service so it automatically starts on boot:
43
44
44
45
*[Official Homebridge Raspberry Pi Image](https://github.com/homebridge/homebridge-raspbian-image/wiki/Getting-Started)
45
46
*[Setup Homebridge on a Raspberry Pi (Raspbian)](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Raspbian)
46
47
*[Setup Homebridge on Debian or Ubuntu Linux](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Debian-or-Ubuntu-Linux)
48
+
*[Setup Homebridge on Red Hat, CentOS or Fedora Linux](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Red-Hat%2C-CentOS-or-Fedora-Linux)
47
49
*[Setup Homebridge on macOS](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-macOS)
48
50
*[Setup Homebridge on Windows 10](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Windows-10)
49
51
*[Setup Homebridge on Docker (Linux)](https://github.com/homebridge/homebridge/wiki/Install-Homebridge-on-Docker)
3. Install the plugins using: `npm install -g <plugin-name>`
57
-
4. Create the `config.json` file.
58
-
59
-
#### Installation Details
60
-
61
-
Homebridge is published through [NPM](https://www.npmjs.com/package/homebridge) and should be installed "globally" by typing:
62
-
63
-
```console
56
+
```shell
64
57
sudo npm install -g --unsafe-perm homebridge
65
58
```
66
59
67
-
Now you should be able to run Homebridge:
60
+
Then start Homebridge in your terminal window by running:
68
61
69
-
```console
70
-
$ homebridge
71
-
No plugins found. See the README for information on installing plugins.
72
-
```
73
-
74
-
Homebridge will complain if you don't have any Plugins installed, since it will essentially be useless, although you can still "pair" with it. See the next section "Installing Plugins" for more info.
75
-
76
-
Once you've installed a Plugin or two, you can run Homebridge again:
77
-
78
-
```console
79
-
$ homebridge
80
-
Couldn't find a config.json file [snip]
81
-
```
82
-
83
-
However, Homebridge won't do anything until you've created a `config.json` file containing your accessories and/or platforms. You can start by copying and modifying the included `config-sample.json` file which includes declarations for some example accessories and platforms. Each Plugin will have its own expected configuration; the documentation for Plugins should give you some real-world examples for that plugin.
84
-
85
-
**NOTE**: Your `config.json` file MUST be inside of `.homebridge`, which is inside of your home folder. On macOS and Linux, the full path for your `config.json` would be `~/.homebridge/config.json`. Any error messages will contain the exact path where your config is expected to be found.
86
-
87
-
**REALLY IMPORTANT**: You must use a "plain text" editor to create or modify `config.json`. Do NOT use apps like TextEdit on macOS or Wordpad on Windows. Apps like these will corrupt the formatting of the file in hard-to-debug ways, making improper `"` signs is an example. I suggest using the free [Atom text editor](http://atom.io).
88
-
89
-
Once you've added your config file, you should be able to run Homebridge again:
90
-
91
-
```console
92
-
$ homebridge
93
-
Loaded plugin: homebridge-lockitron
94
-
Registering accessory 'Lockitron'
95
-
---
96
-
Loaded config.json with 1 accessories and 0 platforms.
97
-
---
98
-
Loading 0 platforms...
99
-
Loading 1 accessories...
100
-
[Back Door] Initializing Lockitron accessory...
62
+
```shell
63
+
homebridge
101
64
```
102
65
103
-
Homebridge is now ready to receive commands from iOS.
104
-
105
66
## Installing Plugins
106
67
107
68
Plugins are Node.js modules published through NPM and tagged with the keyword `homebridge-plugin`. They must have a name with the prefix `homebridge-`, like **homebridge-mysmartlock**.
108
69
109
70
Plugins can publish Accessories and/or Platforms. Accessories are individual devices, like a smart switch or a garage door. Platforms act like a single device but can expose a set of devices, like a house full of smart lightbulbs.
110
71
111
-
You install Plugins the same way you installed Homebridge - as a global NPM module. For example:
72
+
You install Plugins using the [Homebridge UI](https://github.com/oznu/homebridge-config-ui-x), or the same way you installed Homebridge - as a global NPM module. For example:
112
73
113
-
```console
114
-
sudo npm install -g homebridge-lockitron
74
+
```shell
75
+
sudo npm install -g homebridge-dummy
115
76
```
116
77
117
78
You can explore all available plugins at the NPM website by [searching for the keyword `homebridge-plugin`](https://www.npmjs.com/search?q=homebridge-plugin).
@@ -136,9 +97,9 @@ One final thing to remember is that Siri will almost always prefer its default p
136
97
137
98
The https://developers.homebridge.io website contains the Homebridge API reference, available service and characteristic types, and plugin examples.
138
99
139
-
For a great introduction to writing plugins with some example code, check out [Frédéric Barthelet's excellent blog post](https://blog.theodo.com/2017/08/make-siri-perfect-home-companion-devices-not-supported-apple-homekit/).
100
+
The [Homebridge Plugin Template](https://github.com/homebridge/homebridge-plugin-template) project provides a base you can use to create your own *platform* plugin.
140
101
141
-
There are many existing plugins you can study; you might start with the [Homebridge Example Plugins](https://github.com/homebridge/homebridge-examples). The [Homebridge Plugin Template](https://github.com/homebridge/homebridge-plugin-template) project also provides a base you can use to create your own *platform* plugin.
102
+
There are many existing plugins you can study; you might start with the [Homebridge Example Plugins](https://github.com/homebridge/homebridge-examples) or a plugin that already implements the device type you need.
142
103
143
104
When writing your plugin, you'll want Homebridge to load it from your development directory instead of publishing it to `npm` each time. Run this command inside your plugin project folder so your global install of Homebridge can discover it:
144
105
@@ -167,17 +128,17 @@ This is very useful when you are already using your development machine to host
167
128
168
129
### My iOS App Can't Find Homebridge
169
130
170
-
Two reasons why Homebridge may not be discoverable:
131
+
Three reasons why Homebridge may not be discoverable:
171
132
172
-
1. Homebridge server thinks it's been paired with, but iOS thinks otherwise. Fix: deleted `persist/` directory which is next to your `config.json`.
133
+
1. Homebridge server thinks it's been paired with, but iOS thinks otherwise. To fix this, [Reset Homebridge](https://github.com/homebridge/homebridge/wiki/Connecting-Homebridge-To-HomeKit#how-to-reset-homebridge).
173
134
174
-
2. iOS device has gotten your Homebridge `username` (looks like a MAC address) "stuck" somehow, where it's in the database but inactive. Fix: change your `username` in the "bridge" section of `config.json` to be some new value.
135
+
2. iOS device has gotten your Homebridge `username` (looks like a MAC address) "stuck" somehow, where it's in the database but inactive. To fix this, change your `username` in the "bridge" section of `config.json` to be some new value, or [Reset Homebridge](https://github.com/homebridge/homebridge/wiki/Connecting-Homebridge-To-HomeKit#how-to-reset-homebridge) using the [Homebridge UI](https://github.com/oznu/homebridge-config-ui-x).
175
136
176
-
3. iOS DNS cache has gone stale or gotten misconfigured. Fix: Turn airplane mode on and back off to flush the DNS cache. (This is a temporary fix, but can be repeated when the problem recurs. No permanent fix is as yet known/confirmed. If you're experiencing this as a recurrent issue, it likely affects other bonjour and .local DNS resolution services, for which cycling airplane mode will also temporarily resolve.)
137
+
3. iOS DNS cache has gone stale or gotten misconfigured. To fix this, turn airplane mode on and back off to flush the DNS cache. This is a temporary fix, but can be repeated when the problem recurs. No permanent fix is as yet known/confirmed. If you're experiencing this as a recurrent issue, it likely affects other bonjour and .local DNS resolution services, for which cycling airplane mode will also temporarily resolve.
177
138
178
139
### Limitations
179
140
180
-
* One installation of Homebridge can only expose 150 accessories due to a HomeKit limit. You can however run multiple Homebridge instances by pointing them to different config and persistence paths (see issue [#827](https://github.com/homebridge/homebridge/issues/827)).
141
+
* One installation of Homebridge can only expose 150 accessories due to a HomeKit limit. You can however run [Multiple Homebridge Instances](https://github.com/oznu/homebridge-config-ui-x/wiki/Homebridge-Service-Command#multiple-instances) to get around this limitation.
181
142
* Once an accessory has been added to the Home app, changing its name via Homebridge won't be automatically reflected in iOS. You must change it via the Home app as well.
182
143
183
144
## Why Homebridge?
@@ -188,4 +149,4 @@ Technically, the device manufacturers should be the ones implementing the HomeKi
188
149
189
150
Homebridge was originally created by [Nick Farina](https://twitter.com/nfarina).
190
151
191
-
The original HomeKit API work was done by [Khaos Tian](https://twitter.com/khaost) in his [HAP-NodeJS](https://github.com/KhaosT/HAP-NodeJS) project.
152
+
The original HomeKit API work was done by [Khaos Tian](https://twitter.com/khaost) in his [HAP-NodeJS](https://github.com/homebridge/HAP-NodeJS) project.
0 commit comments