diff --git a/README.md b/README.md index 3e4b787..ab63ca2 100644 --- a/README.md +++ b/README.md @@ -14,6 +14,10 @@ Since Siri supports devices added through HomeKit, this means that with HomeBrid If you would like to support any other devices, please write a shim and create a pull request and I'd be happy to add it to this official list. +# Why? + +Technically, the device manufacturers should be the ones implementing the HomeKit API. And I'm sure they will - eventually. When they do, these shims will be obsolete, and I hope that happens soon. In the meantime, this server is a fun way to get a taste of the future, for those who just can't bear to wait until "real" HomeKit devices are on the market. + # Credit HomeBridge itself is basically just a set of shims and a README. The actual HomeKit API work was done by [KhaosT](http://twitter.com/khaost) in his [HAP-NodeJS](https://github.com/KhaosT/HAP-NodeJS) project. Additionally, many of the shims benefit from amazing NodeJS projects out there like `sonos` and `wemo` that implement basically all the interesting functionality. @@ -26,9 +30,9 @@ I would call this project a "novelty" in its current form, and is for **experien * An always-running server (like a Raspberry Pi) on which you can install NodeJS. * Knowledge of Git submodules and npm. -You'll also need a lot of patience, as the iOS HomeKit system does not appear to be fully baked yet. For me, it works "most of the time", but often I'll tell Siri to do something like open the front door and she'll act like she's forgotten everything, saying things like "Change what?" over and over again while I freeze to death outside. +You'll also need a lot of patience, as the iOS HomeKit service does not appear to be fully baked yet. For me, it works "most of the time", but often I'll tell Siri to do something like open the front door and she'll act like she's forgotten everything, saying things like "Change what?" over and over again while I freeze to death outside. -It's not surprising that HomeKit isn't rock solid, since almost no one can actually use it today besides developers who are actually creating hardware accessories for it. There are, to my knowledge, exactly zero HomeKit devices on the market right now, so Apple can easily get away with this all being a work in progress. +It's not surprising that HomeKit isn't rock solid, since almost no one can actually use it today besides developers who are creating hardware accessories for it. There are, to my knowledge, exactly zero HomeKit devices on the market right now, so Apple can easily get away with this all being a work in progress. Additionally, the shims I've created implement the bare minimum of HomeKit needed to provide basic functionality like turning things off and on. I haven't written any kind of good feedback or error handling, and although they support changing state, they don't support reading the current state, so if you ask questions like "Is my door unlocked?" Siri will respond with the default of "Nope!" no matter what. @@ -48,15 +52,18 @@ Now you should be able to run the homebridge server: $ cd homebridge $ npm run start - "Couldn't find a config.json file..." + Starting HomeBridge server... + Couldn't find a config.json file [snip] The server won't do anything until you've created a `config.json` file containing your home devices (or _accessories_ in HomeKit parlance) you wish to make available to iOS. One you've added your devices, you should be able to run the server again and see them initialize: $ npm run start - "[SONOS] Initialize 'Speakers'" - "[WEMO] Initialize 'Coffee Maker'" + Starting HomeBridge server... + Loading 6 accessories... + [Speakers] Initializing 'Sonos' accessory... + [Coffee Maker] Initializing 'WeMo' accessory... Your server is now ready to receive commands from iOS. @@ -64,7 +71,7 @@ Your server is now ready to receive commands from iOS. This part is a bit painful. HomeKit is actually not an app; it's a "database" similar to HealthKit and PassKit. But where HealthKit has the companion "Health" app and PassKit has "Passbook", Apple has supplied no app for managing your HomeKit database (yet). The HomeKit API is open for developers to write their own apps for adding devices to HomeKit, but there are no apps like that in the App Store (probably not an accident). -That means you'll need to build and run your own HomeKit iOS app, meaning you'll need an Apple Developer account. +That means you'll need to build and run your own HomeKit iOS app using your Apple Developer account. There are a few apps out there that let you manage your HomeKit database, but the best one I've found is [BetterHomeKit](https://github.com/KhaosT/HomeKit-Demo), also made by [KhaosT](http://twitter.com/khaost). @@ -80,7 +87,7 @@ Once your device has been added to HomeKit, it should appear in the Accessories At this point, you should be able to tell Siri to control your devices. However, realize that Siri is a cloud service, and iOS may need some time to synchronize your device information with iCloud. -Also, remember that HomeKit is not very robust yet, and it is common for it to fail intermittently ("Sorry, I wasn't able to control your devices" kind of thing) then start working again for no reason. Also I've noticed that it will get cranky and stop working altogether sometimes. The usual voodoo applies here: reboot your device, or run the BetterHomeKit app and poke around, etc. +Also, keep in mind HomeKit is not very robust yet, and it is common for it to fail intermittently ("Sorry, I wasn't able to control your devices" etc.) then start working again for no reason. Also I've noticed that it will get cranky and stop working altogether sometimes. The usual voodoo applies here: reboot your device, or run the BetterHomeKit app and poke around, etc. One final thing to remember is that Siri will almost always prefer its default phrase handling over HomeKit devices. For instance, if you name your Sonos device "Radio" and try saying "Siri, turn on the Radio" then Siri will probably start playing an iTunes Radio station on your phone. Even if you name it "Sonos" and say "Siri, turn on the Sonos", Siri will probably just launch the Sonos app instead. This is why, for instance, the suggested `name` for the Sonos shim in `config-samples.json` is "Speakers".