# HomeKit Setup Code > Source: https://docs.barcoder.ai/docs/standards/homekit-setup-code > research date 2026-10-30 · extracted at 2026-10-30 > Publisher: Barcoder — encyclopedia of QR, barcode and payment-code standards Specifications: - [HomeKit Accessory Protocol Specification, Non-Commercial Version, Release R2 (third-party copy of Apple's document)](https://github.com/nVuln/homebridge-lg-thinq/files/6400345/HAP-Specification-Non-Commercial-Version.pdf) - [HomeKit ADK, Apple's open-source reference code](https://github.com/apple/HomeKitADK) - [HomeKit, Apple Developer](https://developer.apple.com/homekit/) - [HMAccessorySetupPayload, Apple Developer Documentation](https://developer.apple.com/documentation/homekit/hmaccessorysetuppayload) ## Overview A **HomeKit setup code** is the eight-digit secret that a person gives an Apple device to pair it with a HomeKit accessory. It is printed on a label or shown on the accessory's display, and it authenticates the first pairing under the HomeKit Accessory Protocol (HAP) [1][1]. The same code can be delivered by machine as a **setup payload**, a 20-character `X-HM://` string carried in a [QR Code](https://docs.barcoder.ai/docs/standards/qr-code) or an NFC tag, which also holds the accessory category, transport flags and a four-character setup ID [3][3] [5][5]. Apple publishes the setup code rules, but says the content of the payload is available only through its MFi Program [1][1] [8][8]. The public description of the `X-HM://` layout comes from Apple's open-source ADK code and from third-party implementations [3][3] [21][21]. ## History Apple announced HomeKit in the iOS 8 SDK on 2 June 2014, as a shared protocol with secure device pairing [14][14]. iOS 8 became available on 17 September 2014 [15][15]. Building an accessory at first required an MFi licence, Apple testing and a dedicated authentication chip [17][17]. Around WWDC in June 2017, Apple released a non-commercial version of the HAP specification, after login and acceptance of a licence [17][17] [18][18]. Companies that sell or distribute accessories must still enrol in MFi [1][1] [17][17]. From iOS 11.3, accessories without an MFi chip can use software authentication [9][9], and `HMAccessorySetupPayload`, the app API that accepts a setup URL, has the same minimum version [8][8]. The non-commercial Release R2 is dated 26 July 2019 [1][1]. On 18 December 2019, Apple, Amazon, Google and the Zigbee Alliance announced the Connected Home over IP working group [16][16]. The next day iMore reported that Apple had open-sourced parts of its ADK for prototyping non-commercial accessories, and would contribute HAP to the group while continuing to support it [19][19]. Apple's platforms now support the Matter standard, from iOS 16.1 [7][7]. The open-source ADK repository was archived on 28 October 2025, and its last commit dates from October 2021 [2][2]. None of the sources fetched names the individuals who designed the code format. ## Technical specification **Carriers.** The eight digits can be read by a person, or the payload can be scanned from a QR code [1][1] [3][3]. Programmable NFC tags can also advertise the payload: the ADK requires an NDEF-capable tag of Type 2 or greater that supports a 30-byte payload [5][5]. ### Setup code - **Format.** Eight digits shown as `XXXXXXXX`; Apple's example is `10148005`. SRP verifier generation must use the dashed form, here `101-48-005` [1][1]. - **Dynamic codes.** An accessory that generates codes must make a new one each time, from a cryptographically secure random number generator [1][1]. The ADK refreshes a displayed code every 5 minutes [6][6]. - **Static codes.** An accessory that cannot generate codes needs a random code per unit, generated securely at manufacture. It stores an SRP verifier rather than the raw code [1][1]. In the ADK, the raw code is deployed only for a programmable NFC tag [5][5]. - **Not derived from public data.** Codes must not come from a serial number, date, MAC address or similar information [1][1]. - **Forbidden values.** All-identical digits, `12345678` and `87654321` must not be used [1][1]. The ADK's validator enforces these same three rules [3][3]. ### Pairing The setup code drives Pair Setup, which uses Stanford's Secure Remote Password protocol with SHA-512 and the 3072-bit group of RFC 5054 [1][1]. Apple's platform security guide confirms 3072-bit SRP, then ChaCha20-Poly1305 with HKDF-SHA-512 derived keys, and adds that MFi certification is verified during setup [9][9]. After more than 100 unsuccessful authentication attempts, an accessory must refuse with a `MaxTries` error [1][1]. This limits online guessing of a code space of about 100 million values. ### The `X-HM://` setup payload Apple's ADK builds the payload in three parts [3][3]: | Part | Length | Content | |---|---|---| | Prefix | 7 | `X-HM://` | | Packed value | 9 | Base-36, alphabet `0`-`9` then `A`-`Z`, filled from the end | | Setup ID | 4 | `0`-`9` and uppercase `A`-`Z`; `0000` when no ID is given | The packed value holds these fields [3][3]: | Bits | Field | Value | |---|---|---| | 45-43 | Version | 0 | | 42-39 | Reserved | 0 | | 38-31 | Accessory category | 8 bits | | 30 | Not set by the ADK | 0 | | 29 | BLE supported | flag | | 28 | IP supported | flag | | 27 | Paired | flag | | 26-0 | Setup code | digits read as a decimal number | Independent implementations agree on these positions: esp-homekit [24][24], HAP-python [25][25], HAP-NodeJS [28][28] and hkuri [31][31]. - **Paired state.** The paired flag applies only to programmable NFC tags. A paired payload must carry no setup code or setup ID [4][4], and the ADK then always builds a non-pairable form [6][6]. - **Flag names disagree.** Third-party tools call bit 30 `WAC` or `IP_WAC` [24][24] [31][31]. HomeSpan's documentation calls bit 27 NFC rather than paired, and says the Home app does not appear to use the flags [21][21]. Apple's ADK is the better source here, but it does not define bit 30. - **Word size.** HomeSpan calls this a 45-bit word, although its own bit numbering spans 46 bits [21][21]. esp-homekit counts 46 [24][24]. - **Version and reserved.** According to HomeSpan, the Home app does not recognise a code unless these are zero, and uses the category only for display [21][21]. This comes from hobbyist testing, not from Apple. - **Longer strings.** A commenter on a 2018 reverse-engineering gist reported in August 2023 that a new accessory's URI was longer than this layout, and speculated the extra characters were vendor parameters [32][32]. A parser should allow for this. **Structurally illustrative example.** The packed value below uses Apple's example code `10148005` with category 5 (Lighting) [1][1] and the IP flag, and was computed for this page. The setup ID `ABCD` is a placeholder. This does not identify any device: ```text value = (5 << 31) | (1 << 28) | 10148005 payload = X-HM://00526N5B9ABCD | | | | | +-- setup ID (placeholder) | +----------- 9 base-36 characters +------------------ prefix ``` ### Setup ID and setup hash The setup ID is a random four-character value from a secure generator, and is required for QR displays and programmable NFC [5][5]. The ADK derives a **setup hash** from it: SHA-512 over the setup ID followed by the device ID, truncated to 4 bytes [3][3] [4][4]. The spec lists a matching `sh` Bonjour TXT key, and a 4-byte `SH` field in Bluetooth LE advertising data, for "enhanced setup payload information" [1][1]. HomeSpan says the Home app uses the setup ID to find the device on the local network after a scan [21][21]. That the hash is the matching mechanism is an inference from these sources. ### Category The payload's category is an 8-bit value from a table in the HAP specification, including 2 Bridges, 5 Lighting, 6 Locks and 17 IP Cameras [1][1]. Categories flagged in that table, such as locks, doors and cameras, must use programmable tags if they support NFC [1][1]. ### QR symbol parameters Neither the public specification nor the ADK sets the QR version or error-correction level. Details of label size and placement are said to be in an MFi-only guideline titled "Setup Code Sizing and Placement" [12][12]. The 20-character payload uses only characters in QR's alphanumeric mode, which includes `:` and `/` [39][39]. That mode holds 20 characters at version 1-M and 29 at version 2-Q [38][38]. The esp-homekit tool renders version 2 at level Q, and prints the eight digits beside the code in two rows of four [24][24]. This is one implementation's choice, not a documented Apple rule. ## Use cases - **Consumer accessories.** Codes appear on the product, on labels hidden under removable parts, on packaging and in manuals. Some labels print the digits without hyphens [20][20]. - **Devices with screens.** The accessory generates a code and shows it on its display [1][1]. Home Assistant describes devices that show a new code on each pairing attempt [33][33]. - **Tap-to-pair.** Apple's instructions tell users to scan a code or hold the device near the accessory [13][13]. The ADK updates a programmable tag with a pairable payload only during a time-limited NFC pairing mode [6][6]. - **Multipacks.** Apple Home can pair every accessory in a pack from one multi-device QR code [13][13]. The format of that code was not found in any public source. - **Software bridges.** Home Assistant's HomeKit Bridge shows a pairing QR code and PIN in its web interface [34][34]. - **Hobbyist hardware.** HomeSpan targets the Arduino-ESP32 platform [22][22], and Espressif's SDK shows a HomeKit QR code on the device at boot [29][29]. - **Third-party apps.** An app can pass a setup URL through `HMAccessorySetupPayload`, for already-deployed devices or with an ownership token [8][8]. An Apple engineer has said that for HAP accessories the only way around normal pairing is an MFi-managed entitlement [10][10]. ## Implementations | Project | Lang | Stars | Last active | Notes | |---|---|---|---|---| | [apple/HomeKitADK](https://github.com/apple/HomeKitADK) | C | ~2.6k | 2021-10 | Apple's non-commercial reference; archived 2025-10-28 [2][2] [3][3] | | [homebridge/HAP-NodeJS](https://github.com/homebridge/HAP-NodeJS) | TypeScript | ~2.7k | 2026-10 | `setupURI()` sets only the IP flag [27][27] [28][28] | | [HomeSpan/HomeSpan](https://github.com/HomeSpan/HomeSpan) | Arduino | ~2.2k | 2026-04 (release 2.1.8) | ESP32 library; default setup ID `HSPN` [21][21] [22][22] | | [maximkulkin/esp-homekit](https://github.com/maximkulkin/esp-homekit) | C library, Python tool | ~1.2k | 2023-10 | `tools/gen_qrcode` renders a label [23][23] [24][24] | | [ikalchev/HAP-python](https://github.com/ikalchev/HAP-python) | Python | ~0.7k | 2025-08 | `xhm_uri()` with fixed flags value 2 [25][25] [26][26] | | [espressif/esp-homekit-sdk](https://github.com/espressif/esp-homekit-sdk) | C | ~0.7k | 2026-02 | Open-source SDK; commercial products need the MFi variant [29][29] | | [SimonGolms/homekit-code](https://github.com/SimonGolms/homekit-code) | TypeScript | 94 | not shown | CLI for QR labels and scannable tags [30][30] | | [hkuri.py gist](https://gist.github.com/wizardofozzie/a5f07db5b0862ed3a3898ca4f613641f) | Python | 0 | 2025-11 | Encoder and decoder [31][31] | Language entries are read from file types or project descriptions, because GitHub's language bar was not available. The hkuri gist has no stars but is listed because no dedicated decoder library was found: any QR reader recovers the string, and parsing it is a short bit-unpacking step. Home Assistant's HomeKit Device integration, built on [aiohomekit](https://github.com/Jc2k/aiohomekit), is described in terms of numeric pairing codes rather than QR codes [33][33] [35][35]. ## Comparison - **HomeKit setup payload vs [Matter QR](https://docs.barcoder.ai/docs/standards/matter-qr).** Matter QR strings start with the constant `MT:` and use a base-38 suffix of at least 19 characters from `[A-Z0-9.-]` [36][36], with 11- or 21-digit manual codes [37][37], where HomeKit has a fixed 20-character string and eight digits. Matter pairs with SPAKE2+ and device attestation, and HomeKit with SRP and an MFi check [9][9]. Distribution of HomeKit accessories requires MFi enrolment, and of Matter accessories requires Connectivity Standards Alliance certification [7][7]. An Apple engineer has described the two as having a similar proof-of-physical-access model, with Matter's specification being more open and Apple not enforcing it in the same way [10][10]. Choose Matter for an accessory that must work across ecosystems, and HAP where an Apple-only design already exists. - **Setup payload vs [URL QR](https://docs.barcoder.ai/docs/standards/url-qr).** A URL code is an ordinary link whose scheme decides how it is handled [[url-ref]]. `X-HM://` looks like a URI, but its "host" is packed binary data, and it is meant for Apple's HomeKit setup path [3][3] [8][8]. - **Dynamic vs static code.** A dynamic code changes each time and leaves no permanent secret on the label, but needs a display. A static code suits cheap devices, but can be lost: Home Assistant warns there is no way to recover a missing code [1][1] [33][33]. ## Security notes Possession of the code is meant to show physical access. An Apple engineer has said the setup code should require some physical access to the accessory, and that the specification requires it not to be stored, accessible or derivable by the accessory itself [10][10]. ADK's static-code flow matches this, apart from its programmable-NFC exception [5][5]. Compliance varies in practice. Home Assistant's documentation says some manufacturers ignore the specification and use a fixed or guessable code such as `123-45-678`, and it warns and asks for consent before pairing with them [33][33]. ## Fun facts - The public R2 specification never contains the string `X-HM`. Its references to the setup hash resolve to the unfilled placeholder `?? ??` (page ??), which suggests a section was cut from the non-commercial edition [1][1]. A community developer reported in 2021 that the QR format is in section 4.3 of MFi-only Release R15 [11][11]. - The forbidden code `123-45-678` is the one Home Assistant uses as its example of an insecure real-world code [1][1] [33][33]. ## Status **Active, but maintained as a private Apple specification.** Apple's current developer page still offers the HAP specification, ADK and certification tools to MFi licensees [7][7], and Apple's accessory page lists products that must be "HomeKit- or Matter-enabled" [40][40]. Apple's support page, published 3 March 2026, still mentions HomeKit and Matter accessories [13][13]. That developer page does not link a public HAP specification [7][7], and the open-source ADK is archived [2][2]. For Matter, Apple ships a certified SDK in Xcode and encourages developers to use it [7][7]. Current Apple documentation for the payload is not public: the fetched non-commercial text is a third-party copy of a 2019 release, and later revisions were not available to this research [1][1] [11][11]. ## Sources [1]: https://github.com/nVuln/homebridge-lg-thinq/files/6400345/HAP-Specification-Non-Commercial-Version.pdf [2]: https://github.com/apple/HomeKitADK [3]: https://raw.githubusercontent.com/apple/HomeKitADK/master/HAP/HAPAccessorySetup.c [4]: https://raw.githubusercontent.com/apple/HomeKitADK/master/HAP/HAPAccessorySetup.h [5]: https://raw.githubusercontent.com/apple/HomeKitADK/master/PAL/HAPPlatformAccessorySetup.h [6]: https://raw.githubusercontent.com/apple/HomeKitADK/master/HAP/HAPAccessorySetupInfo.c [7]: https://developer.apple.com/homekit/ [8]: https://developer.apple.com/documentation/homekit/hmaccessorysetuppayload [9]: https://support.apple.com/guide/security/communication-security-sec3a881ccb1/web [10]: https://developer.apple.com/forums/thread/781687 [11]: https://developer.apple.com/forums/thread/100734 [12]: https://developer.apple.com/forums/thread/772123 [13]: https://support.apple.com/en-us/104998 [14]: https://www.apple.com/newsroom/2014/06/02Apple-Releases-iOS-8-SDK-With-Over-4-000-New-APIs/ [15]: https://www.apple.com/newsroom/2014/09/09Apple-Announces-iOS-8-Available-September-17/ [16]: https://www.apple.com/newsroom/2019/12/amazon-apple-google-and-the-zigbee-alliance-to-develop-connectivity-standard/ [17]: https://cnx-software.com/?p=46132 [18]: https://www.ifun.de/homekit-ohne-lizenz-apple-gibt-spezifikationen-fuer-alle-frei-108443/ [19]: https://www.imore.com/apple-publishes-open-source-version-its-homekit-accessory-development-kit [20]: https://www.imore.com/lost-your-homekit-code-heres-what-do [21]: https://github.com/stockhuman/HomeSpan/blob/master/docs/QRCodes.md [22]: https://github.com/HomeSpan/HomeSpan [23]: https://github.com/maximkulkin/esp-homekit [24]: https://raw.githubusercontent.com/maximkulkin/esp-homekit/master/tools/gen_qrcode [25]: https://hap-python.readthedocs.io/en/latest/_modules/pyhap/accessory.html [26]: https://github.com/ikalchev/HAP-python [27]: https://github.com/homebridge/HAP-NodeJS [28]: https://raw.githubusercontent.com/homebridge/HAP-NodeJS/latest/src/lib/Accessory.ts [29]: https://github.com/espressif/esp-homekit-sdk [30]: https://github.com/SimonGolms/homekit-code [31]: https://gist.github.com/wizardofozzie/a5f07db5b0862ed3a3898ca4f613641f [32]: https://gist.github.com/Marcocanc/adbcc240bfbf7f34e804b55b2ee86f56 [33]: https://www.home-assistant.io/integrations/homekit_controller/ [34]: https://www.home-assistant.io/integrations/homekit/ [35]: https://github.com/Jc2k/aiohomekit [36]: https://developers.home.google.com/samples/intent-based-commissioning [37]: https://github.com/antoineraulin/matter-setup-code [38]: https://www.thonky.com/qr-code-tutorial/character-capacities [39]: https://www.thonky.com/qr-code-tutorial/alphanumeric-table [40]: https://www.apple.com/home-app/accessories/ [url-ref]: https://docs.barcoder.ai/source/standards/url-qr [1] [HomeKit Accessory Protocol Specification, Non-Commercial Version, Release R2](https://github.com/nVuln/homebridge-lg-thinq/files/6400345/HAP-Specification-Non-Commercial-Version.pdf) — Apple Inc., 2019; third-party hosted copy, accessed 2026 [2] [apple/HomeKitADK](https://github.com/apple/HomeKitADK) — Apple, GitHub, accessed 2026 [3] [HAPAccessorySetup.c](https://raw.githubusercontent.com/apple/HomeKitADK/master/HAP/HAPAccessorySetup.c) — Apple HomeKit ADK, accessed 2026 [4] [HAPAccessorySetup.h](https://raw.githubusercontent.com/apple/HomeKitADK/master/HAP/HAPAccessorySetup.h) — Apple HomeKit ADK, accessed 2026 [5] [HAPPlatformAccessorySetup.h](https://raw.githubusercontent.com/apple/HomeKitADK/master/PAL/HAPPlatformAccessorySetup.h) — Apple HomeKit ADK, accessed 2026 [6] [HAPAccessorySetupInfo.c](https://raw.githubusercontent.com/apple/HomeKitADK/master/HAP/HAPAccessorySetupInfo.c) — Apple HomeKit ADK, accessed 2026 [7] [HomeKit](https://developer.apple.com/homekit/) — Apple Developer, accessed 2026 [8] [HMAccessorySetupPayload](https://developer.apple.com/documentation/homekit/hmaccessorysetuppayload) — Apple Developer Documentation, accessed 2026 [9] [HomeKit communication security](https://support.apple.com/guide/security/communication-security-sec3a881ccb1/web) — Apple Platform Security, 2024 [10] [Best way to pass a HomeKit or Matter setup code to the Home App Programatically](https://developer.apple.com/forums/thread/781687) — Apple Developer Forums, 2025 [11] [Homekit QR code](https://developer.apple.com/forums/thread/100734) — Apple Developer Forums (community replies), 2018–2021 [12] [Homekit QR Artwork tool](https://developer.apple.com/forums/thread/772123) — Apple Developer Forums (community post), 2025 [13] [Add a smart home accessory to the Home app](https://support.apple.com/en-us/104998) — Apple Support, 2026 [14] [Apple Releases iOS 8 SDK With Over 4,000 New APIs](https://www.apple.com/newsroom/2014/06/02Apple-Releases-iOS-8-SDK-With-Over-4-000-New-APIs/) — Apple Newsroom, 2014 [15] [Apple Announces iOS 8 Available September 17](https://www.apple.com/newsroom/2014/09/09Apple-Announces-iOS-8-Available-September-17/) — Apple Newsroom, 2014 [16] [Amazon, Apple, Google and the Zigbee Alliance to develop connectivity standard](https://www.apple.com/newsroom/2019/12/amazon-apple-google-and-the-zigbee-alliance-to-develop-connectivity-standard/) — Apple Newsroom, 2019 [17] [Apple Opens HomeKit Accessory Protocol Specification to Non-Commercial Projects](https://cnx-software.com/?p=46132) — CNX Software, 2017 [18] [HomeKit ohne Lizenz: Apple gibt Spezifikationen für alle frei](https://www.ifun.de/homekit-ohne-lizenz-apple-gibt-spezifikationen-fuer-alle-frei-108443/) — ifun.de, 2017 [19] [Apple publishes open-source version of its HomeKit Accessory Development Kit](https://www.imore.com/apple-publishes-open-source-version-its-homekit-accessory-development-kit) — iMore, 2019 [20] [Lost your HomeKit code? Here's what to do](https://www.imore.com/lost-your-homekit-code-heres-what-do) — iMore, 2020 [21] [HomeSpan QR Codes documentation](https://github.com/stockhuman/HomeSpan/blob/master/docs/QRCodes.md) — HomeSpan project (fork copy), accessed 2026 [22] [HomeSpan/HomeSpan](https://github.com/HomeSpan/HomeSpan) — GitHub, accessed 2026 [23] [maximkulkin/esp-homekit](https://github.com/maximkulkin/esp-homekit) — GitHub, accessed 2026 [24] [gen_qrcode](https://raw.githubusercontent.com/maximkulkin/esp-homekit/master/tools/gen_qrcode) — esp-homekit, accessed 2026 [25] [pyhap.accessory source](https://hap-python.readthedocs.io/en/latest/_modules/pyhap/accessory.html) — HAP-python documentation, accessed 2026 [26] [ikalchev/HAP-python](https://github.com/ikalchev/HAP-python) — GitHub, accessed 2026 [27] [homebridge/HAP-NodeJS](https://github.com/homebridge/HAP-NodeJS) — GitHub, accessed 2026 [28] [Accessory.ts](https://raw.githubusercontent.com/homebridge/HAP-NodeJS/latest/src/lib/Accessory.ts) — HAP-NodeJS, accessed 2026 [29] [espressif/esp-homekit-sdk](https://github.com/espressif/esp-homekit-sdk) — Espressif, GitHub, accessed 2026 [30] [SimonGolms/homekit-code](https://github.com/SimonGolms/homekit-code) — GitHub, accessed 2026 [31] [hkuri.py](https://gist.github.com/wizardofozzie/a5f07db5b0862ed3a3898ca4f613641f) — GitHub Gist, 2025 [32] [Reverse engineering HomeKit QR Code decoding/encoding](https://gist.github.com/Marcocanc/adbcc240bfbf7f34e804b55b2ee86f56) — GitHub Gist, 2018 [33] [HomeKit Device integration](https://www.home-assistant.io/integrations/homekit_controller/) — Home Assistant, accessed 2026 [34] [HomeKit Bridge integration](https://www.home-assistant.io/integrations/homekit/) — Home Assistant, accessed 2026 [35] [Jc2k/aiohomekit](https://github.com/Jc2k/aiohomekit) — GitHub, accessed 2026 [36] [Intent-based Commissioning for Matter](https://developers.home.google.com/samples/intent-based-commissioning) — Google Home Developers, accessed 2026 [37] [antoineraulin/matter-setup-code](https://github.com/antoineraulin/matter-setup-code) — GitHub, accessed 2026 [38] [Character Capacities by Version and Error Correction Level](https://www.thonky.com/qr-code-tutorial/character-capacities) — Thonky.com, accessed 2026 [39] [Alphanumeric Mode Table](https://www.thonky.com/qr-code-tutorial/alphanumeric-table) — Thonky.com, accessed 2026 [40] [Accessories, Apple Home](https://www.apple.com/home-app/accessories/) — Apple, accessed 2026 ## Deployments _No country reports mention this standard by name._ ## Regions / aggregations not mapped to a single country - Universal