Seich
/
HomeSpan
1
0
Fork 0
Code Issues Pull Requests Packages Projects Releases Wiki Activity

Update CLI.md

This commit is contained in:
HomeSpan 2020-11-22 17:41:43 -06:00 committed by GitHub
parent fabce6f308
commit 5422aca18e
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 4 additions and 2 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

6
docs/CLI.md
View File

@ -46,8 +46,10 @@ In addition to listening for incoming HAP requests, HomeSpan also continuously p
* **U** - unpair device by deleting all Controller data * **U** - unpair device by deleting all Controller data
* This deletes all data stored about Controllers that have been paired with the device, which forces HomeSpan to reset its internal state to unpaired. Normally, unpairing is done by HomeKit at the direction of an end-user via the Home App on an iPhone. However, HomeKit requests to unpair a device are not subject to any confirmation from that device. HomeKit simply assumes that once it requests a device to unpair, the device has received the message and has reset its pairing state accordingly. In the event that HomeKit unpairs a HomeSpan device, but the device does not receive or properly process the request, its pairing status will be out of sync with HomeKit. Forcing HomeKit to reset its internal state to unpaired using this command resolves the issue and allows HomeSpan to be re-paired with HomeKit. * This deletes all data stored about Controllers that have been paired with the device, which forces HomeSpan to reset its internal state to unpaired. Normally, unpairing is done by HomeKit at the direction of an end-user via the Home App on an iPhone. However, HomeKit requests to unpair a device are not subject to any confirmation from that device. HomeKit simply assumes that once it requests a device to unpair, the device has received the message and has reset its pairing state accordingly. In the event that HomeKit unpairs a HomeSpan device, but the device does not receive or properly process the request, its pairing status will be out of sync with HomeKit. Forcing HomeKit to reset its internal state to unpaired using this command resolves the issue and allows HomeSpan to be re-paired with HomeKit.
* Note that if you run this command when HomeKit thinks it is still paired to the device, pairing status will be out of sync in the opposite direction. HomeKit Controllers will continue to send HAP requests to the device, thinking it is paired, but HomeSpan ignore all these requests since it no longer recognizes any of the Controllers as being paired. To resolve this issue, you much instruct HomeKit to unpair the device via the Home App, after which you can re-pair the device if needed. * Note that if you run this command when HomeKit thinks it is still paired to the device, pairing status will be out of sync in the opposite direction. HomeKit Controllers will continue to send HAP requests to the device, thinking it is paired, but HomeSpan will ignore all these requests since it no longer recognizes any of the Controllers as being paired. To resolve this issue, you must instruct HomeKit to unpair the device via the Home App, after which you can re-pair the device if needed.
* **H** - delete HomeKit Device ID as well as all Controller data and restart
* In addition to deleting all Controller data (as if the 'U' command was run), this command also deleted the device's HomeKit ID. This unique ID is broadcast to all HomeKit Controllers so the device can be uniquely recognized. When HomeSpan first runs on a new device, it creates this unique ID and stores it permanently in an NVS partition. Normally, this ID should not changed once set. However, if you are actively developing and testing a HomeSpan device, and modify the details of your HAP Database (perhaps by adding a new Service, or changing the name of a Characteristic), you may find that HomeKit is cacheing information about your device and the changes you have made are not reflected in the Home App. Sometimes simply unpairing and re-paring the device solves this HomeKit issue. If not, deleting your device's HomeKit ID with this command forces HomeSpan to generate a new one after restarting, which means HomeKit will think this is a completely different device. Note that since this command also resets the device status to unpair, all the caveats above in the 'U' command hold true for this command as well.
* Developer's Note: HomeSpan properly broadcasts a new configuration number for all HomeKit Controllers to read every time a HomeSpan sketch is changed in a way that results in a modified HAP Accessory Database (such as changing a Characteristic). However, HomeKit Controllers do not always seems to read or respect the configuration number and instead rely on an outdated cached version of the device's HAP Database.
Every HomeSpan device also requires an 8-digit Setup Code to be able to pair to Apple HomeKit. This code is similarly stored in an NVS partition rather than hardcoded into a HomeSpan sketch. When HomeSpan is run for the first time on a new device, it configures itself with a default code of **466-37-72**. This can be changed any time from the HomeSpan CLI. Every HomeSpan device also requires an 8-digit Setup Code to be able to pair to Apple HomeKit. This code is similarly stored in an NVS partition rather than hardcoded into a HomeSpan sketch. When HomeSpan is run for the first time on a new device, it configures itself with a default code of **466-37-72**. This can be changed any time from the HomeSpan CLI.