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

Update Cloning.md

This commit is contained in:
HomeSpan 2023-04-03 22:13:43 -05:00 committed by GitHub
parent 9dc1ac0b48
commit 71e89605b0
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 9 additions and 5 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

14
docs/Cloning.md
View File

@ -2,7 +2,7 @@
### HomeSpan Pairing Data
Every HomeSpan Accessory has unique 17-character Device ID, a unique 32-byte long-term public key (LTPK), and a unique 64-byte long-term secret key (LTSK). these keys are randomly generated for permanent stoorage in a new HomeSpan device, but can be subsequently erased and randomly re-generated with the 'H' CLI Command.
Every HomeSpan Accessory has unique 17-character Device ID, a unique 32-byte long-term public key (LTPK), and a unique 64-byte long-term secret key (LTSK). These data are randomly generated by every new HomeSpan device. Once generated, HomeSpan permanently saves the data in the device's non-volatile storage partition, but this data can be subsequently erased and randomly re-generated with the 'H' CLI Command.
Similarly, every HomeKit Controller (e.g. the Home App on an iPhone) has unique 36-character Device ID and a unique 32-byte LTPK.
@ -10,7 +10,7 @@ When a HomeSpan Accessory is first paired with a HomeKit Controller (using eithe
Pairing Data is used every time a HomeKit Controller opens up a new secure connection with a HomeKit Accessory. Without this data, the Home App will no longer be able to open a connection to HomeSpan.
Once an Accessory is paired to a Controller, if cannot be paired to a second Controller. But yet you can operate a HomeSpan device from multiple iPhones, HomePods, Macs, etc., as long as they are on the same network. This is because in the background HomeKit shares the Pairing Data of a HomeSpan Accessory with other Controllers. When opening their own connections to HomeSpan, those Controllers use the same Pairing Data. However, sometimes HomeKit decides to create one or more additional sets of Pairing Data for other Controllers to use by sending such new Pairing Data securely to a HomeSpan Accessory. HomeSpan can store up to 16 sets of Pairing Data.
Once an Accessory is paired to a Controller, it cannot be paired to a second Controller. But yet you can operate a HomeSpan device from multiple iPhones, HomePods, Macs, etc., as long as they are on the same network. This is because in the background HomeKit shares the Pairing Data of a HomeSpan Accessory with other Controllers. When opening their own connections to HomeSpan, those Controllers use the same Pairing Data. However, sometimes HomeKit decides to create one or more additional sets of Pairing Data for other Controllers to use by sending such new Pairing Data securely to a HomeSpan Accessory. HomeSpan can store up to 16 sets of Pairing Data.
You can view most of the Pairing Data for any HomeSpan Accessory by typing 'S' into the CLI. Here is an example:
@ -47,11 +47,15 @@ Though you can run the same sketch on two different HomeSpan devices, each devic
However, sometimes you may want to *replace* one HomeSpan device with another running the exact same sketch. Maybe the first device has malfunctioned or was damaged. Typically when this occurs, you unpair the first (broken) device from HomeKit and then pair the new device to HomeKit. Unfortunately, once you unpair the old device, HomeKit forgets any automations, scenes, customizatons, etc., related to this device that you may have made using the Home App. When you pair the new device, even though it is running the same sketch, HomeKit will treat it as a completely new device. It will not apply any name-changes you may have made in the Home App, nor recreate any of the prior device's automations.
To solve this problem, you need to be able to replace the broken device with a new device, but *without* unpairing the old device or re-pairing the new device. This would require the new device to be initialized with the same Pairing Data as the old device, including having the same long-term secret key.
To solve this problem, you need to be able to replace the broken device with a new device, but *without* unpairing the old device or re-pairing the new device. This requires the new device to be initialized not with a new set of randomly-generated Device IDs, LTPKs and LTSKs, but rather with the *same* Pairing Data as the old device.
Fortunately, HomeSpan provides a methods for "cloning" the Pairing Data from one device to another. This means you can swap out a broken device for a new device without HomeKit knowing the difference (provided it is running the same sketch of course). In fact, you can even swap out an ESP32 for an ESP32-S2, or ESP32-C3, etc. As long as the sketch is the same, once you clone the Pairing Data the devices are effectively hot-swappable.
Fortunately, HomeSpan provides a methods for "cloning" the Pairing Data from one device to another. This means you can swap out a broken device for a new device without HomeKit knowing the difference (provided it is running the same sketch of course). In fact, you can even swap out an ESP32 for an ESP32-S2, or ESP32-C3. As long as the sketch is the same, once you clone the Pairing Data the devices are effectively hot-swappable.
Cloning HomeSpan's pairing data is a two-step process. **First, type 'P' into the CLI for the device you wish to clone.** This necessarily means the device must still be working well enough for HomeSpan to run (if the device is completely dead, you will not be able to clone its Pairing Data). HomeSpan will output its Pairing Data in base-64. Here is an example reflecting a system with Pairing Data for two Controllers (similar to above):
Cloning HomeSpan's pairing data is a two-step process.
* **First, type 'P' into the CLI for the device you wish to clone.**
This necessarily means the device must still be working well enough for HomeSpan to run (if the device is completely dead, you will not be able to clone its Pairing Data). HomeSpan will output its Pairing Data in base-64. Here is an example reflecting a system with Pairing Data for two Controllers (similar to above):
```
*** Pairing Data used for Cloning another Device