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

Update QRCodes.md

This commit is contained in:
HomeSpan 2021-01-29 18:09:57 -06:00 committed by GitHub
parent f6b02a125e
commit f575beeab3
No known key found for this signature in database
GPG Key ID: 4AEE18F83AFDEB23
1 changed files with 12 additions and 11 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

23
docs/QRCodes.md
View File

@ -2,32 +2,33 @@
Pairing a HomeKit device using its 8-digit *Setup Code* requires you to: Pairing a HomeKit device using its 8-digit *Setup Code* requires you to:
* Select the specific HomeKit device you wish to pair from a list of unpaired HomeKit devices the Home App finds on your local network * Select the specific HomeKit device to pair from a list of unpaired HomeKit devices the Home App finds on your local network
* Input the *Setup Code* for that device into the Home App. * Input the *Setup Code* for that device into the Home App.
The order of the steps above depends on whether you input the *Setup Code* by manually typing it, or scan it from a printed tag (see the [HomeSpan User Guide](https://github.com/HomeSpan/HomeSpan/blob/master/docs/UserGuide.md#creating-a-scannable-tag) for details on how to create your own scannable *Setup Code* tags) The order of the steps above depends on whether you manually type the *Setup Code*, or scan it from a printed tag.
On the other hand, pairing a HomeKit device with a **QR Code** requires you only scan the QR Code. You do not need to identify the device you want to pair - the Home App automatically searches for it on your local network and, if found, pairs to it. In contrast, pairing a HomeKit device with a **QR Code** requires you to only scan the QR Code. You do not need to identify the device you want to pair. The Home App will instead search for it on your local network and, if found, pair to it automatically.
This is possible because the QR Code contains within a 4-character *Setup ID* that is unique to the device associated with that QR Code. The QR Code also contains other informattion about the device, such as its type (e.g. Light, Fan, Door) as well as its 8-digit *Setup Code*. This is possible because the QR Code includes a 4-character *Setup ID* that is unique to the device associated with the QR Code. The QR Code also embeds other paring information about the device, such as its Category (e.g. Light, Fan, Door) and its 8-digit *Setup Code*.
HomeSpan supports pairing with QR codes and uses "HSPN" as its default *Setup ID*. If you have more than one device that you intend on pairing with a QR Code, you'll need to change their default *Setup IDs* from "HSPN" to something unique using the method `homeSpan.setQRID(const char *ID)` (see the [HomeSpan API Reference](https://github.com/HomeSpan/HomeSpan/blob/master/docs/Reference.md) for details). If you do not intend on pairing your devices with QR Codes, it is fine for them to all have the same *Setup ID*, as this ID is only used to initiate the pairing process via a QR code and serves no other purpose. HomeSpan supports pairing with QR Codes and uses "HSPN" as its default *Setup ID*. However, if you have more than one device that you intend on pairing with a QR Code, you'll need to change each device's *Setup ID* from "HSPN" to something unique using the method `homeSpan.setQRID(const char *ID)` (see the [HomeSpan API Reference](https://github.com/HomeSpan/HomeSpan/blob/master/docs/Reference.md) for details). If you do not intend on pairing your devices with QR Codes, it is fine for them to all have the same *Setup ID*, as this ID is only used to initiate the pairing process via a QR code and serves no other purpose.
### Creating Scannable QR Codes ### Creating Scannable QR Codes
Just as you can create your own scannable tag based on a device's *Setup Code*, you can also create your own scannable QR Code for that device. One method is to use the QR Code generator provided by Apple in its [HomeKit Accessory Simulator Add-on for Xcode](https://developer.apple.com/documentation/homekit/testing_your_app_with_the_homekit_accessory_simulator). Just as you can create your own scannable tag based on a HomeSpan device's *Setup Code* (see the [HomeSpan User Guide](https://github.com/HomeSpan/HomeSpan/blob/master/docs/UserGuide.md#creating-a-scannable-tag), you can also create your own scannable QR Code for pairing a HomeSpan device. Perhaps the easiest method is to use Apple's HomeKit QR Code generator including with its [HomeKit Accessory Simulator](https://developer.apple.com/documentation/homekit/testing_your_app_with_the_homekit_accessory_simulator) add-on for Xcode.
![QR Code Generator](images/QRCode.png) ![QR Code Generator](images/QRCode.png)
As shown above, the Simulator's QR Code Generator requires the input of the following fields: As shown above, the Simulator's QR Code Generator requires the input of the following fields:
* **Version**. Always set this to zero, else the Home App will not recognize the QR Code. * **Version**. Always set this to zero, else the Home App will not recognize the QR Code.
* **Reserved**. Always set this to zero, else the Home App will not recognize the QR Code. * **Reserved**. Always set this to zero, else the Home App will not recognize the QR Code.
* **Category**. Set this to match the Category of your HomeSpan device (e.g. Lightbulb, Fan, Door Lock). Note the Home App only uses this for display purposes when you first scan the QR Code. The Home App does not actually check to see that the Category listed in the QR Code actually matches the Category of the device you are pairing. * **Category**. Set this to match the Category of your HomeSpan device (e.g. Lightbulb, Fan, Door Lock). Note the Home App only uses this for display purposes when you first scan the QR Code. The Home App does not actually check that the Category listed in the QR Code matches the Category of the device you are pairing.
* **Setup Flags**. These flags provide information on which methods of pairing are supported by the device. HomeSpan only supports IP Pairing, so check that box. However, similar to Category, the Home App does not seem to do anything with these flags, and HomeSpan devices seem to be able to pair with the Home App regardless of which check boxes (if any) are checked. * **Setup Flags**. These flags provide information on which methods of pairing are supported by a HomeKit device. HomeSpan only supports IP Pairing, so you check that box and leave the other two blank. However, it does not seem to matter which boxes (if any) you check since the Home App does not appear to use this information for anything.
* **Setup Code**. This is the 8-digit *Setup Code* you set for your device using either HomeSpan's Command-Line Interface or HomeSpan's Setup Access Point. Note the code shown in the above screenshot is the default HomeSpan uses if you do not set your own. * **Setup Code**. This is the 8-digit *Setup Code* you set for your device using either the [HomeSpan Command-Line Interface (CLI)](https://github.com/HomeSpan/HomeSpan/blob/master/docs/CLI.md) or [HomeSpan's Setup Access Point](https://github.com/HomeSpan/HomeSpan/blob/master/docs/UserGuide.md#setting-homespans-wifi-credentials-and-setup-code). Note the code shown in the above screenshot is the default HomeSpan uses if you do not set your own.
* **Setup ID**. This is the 4-character *Setup ID* you set for your device from within your sketch code using the method `homeSpan.setQRID(const char *ID)`. Note the ID shown in the above screenshot is the default HomeSpan uses if you do not set your own. Also note case matters! HSPN is not the same as "hspn". * **Setup ID**. This is the 4-character *Setup ID* you set for your HomeSpan device from within your sketch using the method `homeSpan.setQRID(const char *id)`. Note the ID shown in the above screenshot is the default HomeSpan uses if you do not set your own. Also note case matters! HSPN is not the same as "hspn".
* **Setup Payload**. This is the output that results from the above inputs, and is the text that is representing by the QR Code shown. If you've not changed HomeSpan's default *Setup Code* or *Setup ID*, you can pair your device by scanning this graphic with the Home App. Even easier is to scan it right from your camera - your iPhone will recognize that this is a HomeKit QR Code and open the Home App for you. * **Setup Payload**. This is the output that results from the above inputs, and is the text that is represented by the QR Code shown. If you've not changed HomeSpan's default *Setup Code* or *Setup ID*, you can pair your device by scanning this graphic with the Home App. Even easier is to scan it right from your camera - your iPhone will recognize that this is a HomeKit QR Code and open the Home App for you.
You probably noticed that this QR Code contains Apple's HomeKit logo in the upper left. This is purely cosmetic and not required by the Home App for pairing. Similarly, the device's 8-digit *Setup Code* shown in big numerals in the upper right is also cosmetic and not needed for pairing, though it may be handy if you have problems scanning the QR Code and need to manually enter the *Setup Code* into the Home App. You probably noticed that this QR Code contains Apple's HomeKit logo in the upper left. This is purely cosmetic and not required by the Home App for pairing. Similarly, the device's 8-digit *Setup Code* shown in big numerals in the upper right is also cosmetic and not needed for pairing, though it may be handy if you have problems scanning the QR Code and need to manually enter the *Setup Code* into the Home App.