From f8f692cc1fca0ad745b20cd95605de53130d3d9f Mon Sep 17 00:00:00 2001 From: HomeSpan Date: Thu, 28 Jan 2021 21:58:57 -0600 Subject: [PATCH] Update QRCodes.md --- docs/QRCodes.md | 31 ++++++++++++++++++++++++++----- 1 file changed, 26 insertions(+), 5 deletions(-) diff --git a/docs/QRCodes.md b/docs/QRCodes.md index b42846c..b4f668d 100644 --- a/docs/QRCodes.md +++ b/docs/QRCodes.md @@ -17,15 +17,15 @@ HomeSpan supports pairing with QR codes and uses "HSPN" as its default *Setup ID 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): +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) ![QR Code Generator](images/QRCode.png) 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. -* **Reserved**. Always set this to zero, else the Home App will not recognize the QR code. -* **Category**. Set this to match the catgory 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. +* **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. +* **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. * **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 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 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". @@ -35,6 +35,27 @@ You probably noticed that this QR Code contains Apple's HomeKit logo in the uppe The only portion of the graphic actually scanned by the Home App is the QR Code itself, which means that you can use any generic QR Code generator instead of Apple's version, provided the generator allows you to create a QR Code from arbitrary text (most do). -The text input you'll need to provide to a generic QR Code generator is the Setup Payload. There is a relatively straightfoward algorithm yuo can follow to determine the Setup Payload for your device based on all the inputs (see below), but its even easier to let HomeSpan do it for you. +The text input you'll need to provide to a generic QR Code generator is of course the Setup Payload. There is a relatively straightfoward algorithm you can follow to determine the Setup Payload for your device based on all the inputs (see below), but its even easier to let HomeSpan do it for you. HomeSpan outputs its Setup Payload to the Arduino Serial Monitor whenever it generates a *Setup Code* or you set/change the *Setup Code*. Simply copy the *Setup Payload* from the Serial Monitor into a generic QR Code generator, and viola, you have a scannable QR Code you can use to pair your HomeSpan device. + +### Setup Payload (optional reading) + +The format of the Setup Payload is the URL "X-HM://" followed by 9 data characters, followed by the device's 4-character *Setup ID*. + +The data characters are a simple base-36 representation (using the characters 0-9 and A-Z) of a 45-bit word formed from the following fields— + +* Bits 0-26: The device's 8-digit *Setup Code* (from 0-99999999) +* Bit 27: Set to 1 if the device supports NFC pairing, else set to 0 +* Bit 28: Set to 1 if the device supports IP pairing, else set to 0 +* Bit 29: Set to 1 if the device supports BLTE pairing, else set to 0 +* Bit 30: Always set to 0 +* Bits 31-38: The device's Accessory Category (0-255) +* Bits 39-42: The "Reserved" field. Always set to 0. +* Bits 43-45; The "Version" field. Always set to 0. + + + + + +