Your Setup Console

Zigbee Simple Setup (ZSS) Provisionee 2D Barcode Specification

Overview

Frustration-Free Setup (FFS) technology used for Zigbee Simple Setup relies on your device's package barcode. Amazon scans your device's package barcode during order fulfillment and pre-associates the device with the Amazon customer's account. Pre-association enables FFS to authenticate device ownership and gives the customer's account and Zigbee hubs control over the new device.

Specification

FFS utilizes two-dimensional barcodes in the DataMatrix ECC200 format. The content encoded in the barcodes essentially includes a list of key: value pairs (i.e. key1:value1;key2:value2….).

Key Name Description
ABV Amazon Barcode Version Defined by Amazon. This denotes the current version of the barcode encoding used to contain the data. Its 4 characters in length. The current values are: OB02 - for the barcode on the device package
UPC Universal Product Code 12 digit numeric value assigned for the product by the manufacturer. https://en.wikipedia.org/wiki/Universal_Product_Code
PID Product Identifier Defined by Amazon and assigned to a product during product onboarding. It is unique to every product even for multiple products from the same manufacturer. This is alphanumeric and 4 characters in length. Reach out to your business development / solution architect lead to create an Advertised Product ID (APID)
ZBM Zigbee Mac Zigbee Mac address of the device in plain text. Mac address is encoded as a 16-character Hex String (eg: BF91A2B05327F4D5) In the case of multipacks, Mac addresses are encoded as a list with the character "_" (underscore) used as separator. For eg: the value of ZBM for a 2-pack containing devices with Mac addresses BF91A2B05327F4D5 and A9F4BD83C351D03D will be BF91A2B05327F4D5_A9F4BD83C351D03D.
ZBD Zigbee Data This field holds the Zigbee Mac address and Install Code pair for the Zigbee device contained in the package. For multipacks, <mac adddress, install code> pairs for all units inside the package are encoded in this field. This value is encrypted by the manufacturer.

Generation of the ZBD Field

The value for ZBD field in turn comprises of the following two segments.

  • ZBD version
    • 1-byte version field. This is the version number of the algorithm that generated the value within the ZBD field. This guide describes version 1 of the algorithm.
  • Actual data
    • List of <Mac address, Install code> pairs. Each pair contains the Zigbee radio MAC address and the corresponding install code.

For the ZBD version “1”, data is generated as follows:

  • Step 1: Convert the 1-byte ZBD version number into Hexadecimal value and encode it as a String. This must be formatted as a 2-character string. For example, a value of 1 is represented as “01”.
  • Step 2: Create a 24-byte array to hold Zigbee data for a device. The first 8 bytes of the array contain the Zigbee MAC address and the remaining 16-bytes contain the Zigbee install code.
8-byte Zigbee MAC address | 16-byte Zigbee install code
  • For multi-device packages repeat the above format for each device. Separate the MAC address/install code pairs with a “_” (underscore) character. For example, the barcode for a package contains 2 devices includes a 49-byte array formatted as follows.
24-byte for the 1st device | 1-byte separator | 24-byte for the 2nd device
  • Step 3: Encrypt the entire array using the public key shared by Amazon. The encryption algorithm details follow:
    • Key Algorithm: ECDH
    • Encryption Algorithm: ECIES
    • Curve used: secp384r1
    • The key pair to use in encryption and decryption will be created by Amazon and the public key will be shared securely with you.
  • Step 4: Covert the encrypted payload (in bytes) into a String using Base64 encoding.
  • Step 5: Append the Base64 encoded value to the ZBD version number generated in Step 1 to get the final value for ZBD.
2-char ZBD version | Base64 encoded Zigbee device data

[Single and Multi Device Pack] Zigbee Enabled Devices

Specification

Package Barcode (Outer Barcode)

Key Name Description
ABV Amazon Barcode Version Defined by Amazon. This denotes the current version of the barcode encoding used to contain the data. It is 4 characters in length.Its value is OB02 for 3P Zigbee-based authentication enabled Philips lightbulbs.
UPC Universal Product Code The 12-digit UPC assigned for the package. If you print a product's UPC on the package, include this field in the barcode. Universal Product Code
EAN International Article Number The 8-digit/13-digit EAN assigned for the package. If you print a product's EAN on the package, include this field in the barcode. International Article Number
PID Product Id Defined by Amazon and assigned to a product during product onboarding (this would appear as 'Amazon Id' in Amazon Developer Portal when the product is onboarded). It is unique to every product even for multiple products from the same manufacturer. It is alphanumeric and 4 characters in length. All Philips light bulbs use wXHD.
ZBM Zigbee Mac This field holds the Zigbee MacAddress of the device in plaintext. The MacAddress is encoded as a 16-character Hex String (eg: BF91A2B05327F4D5).
ZBD Zigbee Data This field holds the Zigbee MacAddress and install-code pair for the Zigbee device contained in the package. The value is encrypted by the manufacturer. Please see the 'Generation of ZBD' section for more details.

General Guidance for Barcode generation

Barcode dimensions:

  • 1-pack: 64x64 modules. Fits in 24x24 mm square using a .37 module size.
  • 2-pack: 64x64 modules. Fits in 24x24 mm square using a .37 module size.
  • 4-pack: 72x72 modules. Fits in 27x27 mm square using a .37 module size.
  • 6-pack: 80x80 modules. Fits in 30x30 mm square using a .37 module size.

Generation of ZBD

The value for ZBD field in turn comprises of the following two segments.

  • ZBD Version: 1-byte version field to indicate the algorithm used to generate value for ZBD field. For now the value of this is "1".
  • Actual data: <MacAddress, Install-Code> pair where the entry represents the MacAddress of the Zigbee radio associated with a device in the package and the corresponding install code.

Generation of Barcode

For generating barcode for Zigbee-enabled Philips Lightbulbs, follow the steps below:-

  • Convert the 1-byte ZBD version number into Hexadecimal value and encode it as a String. This must be always formatted as a 2-character string. So, the value of “1” will be encoded as “01”.
  • Create a 24-byte array to hold Zigbee data for a device. The first 8-byte of the array is populated with the Zigbee MacAddress and the remaining 16-byte is filled with Zigbee install code
  • Encrypt the entire byte-array created in the previous step holding Zigbee data for the device in the package using the public key shared by Amazon. See below for more details on the encryption algorithm.

  • Key Algorithm: ECDH
  • Encryption Algorithm: ECIES
  • Curve used: secp384r1
  • The key pair to use in encryption and decryption has been created by Amazon and the public key has been shared securely with Philips.

Sample Data

The sample data for all four types of packs has been generated using the following key pair.

Key File

-----BEGIN EC PARAMETERS-----
BgUrgQQAIg==
-----END EC PARAMETERS-----

-----BEGIN EC PRIVATE KEY-----
MIGkAgEBBDCZZ9rEjHLbFC4WwBaAoPH5H5VQMKuCBqH/7RkFLKghbXeOy617Q
hu+QnG9NCHrKgigBwYFK4EEACKhZANiAASkXfdXEXE8yKHOdtFoCTMn1wsDzn5x
FijRmVVc8h6PwBQw98hfza9BonbA6wd0jWfYr0l/yew0bRjolG9peN/hvasWn6gUEo
pvfRZ8nnmEGT36W618E/5975laE4SQ8EU=
-----END EC PRIVATE KEY-----

Public Key

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEpF33VxFxPMihznbRaAkzJ9cLA85+cRYo
0ZlVXPIej8AUMPfIX82vQaJ2wOsHdI1n2K9Jf8nsNG0Y6JRvaXjf4b2rFp+oFBKKb30
WfJ55hBk9+lutfBP+fe+ZWhOEkPBF
-----END PUBLIC KEY-----

Note: Both Zigbee Mac and Install Code in the below tables are Hex encoded.

1-Pack

Device Zigbee Mac Install Code
Device 1 FA1FFC0CA5FCD16A D262A1E1FDCFF25E436E8AF5C7A623C3

Expected Barcode:

ABV:OB02;UPC:123456789012;PID:wHXD;ZBM:FA1FFC0CA5FCD16A;ZBD:01BOqDGkvjgOr/zBj/
sxPYkB45+IhTjY9V1iE OdkSBzwegw2T8FOrEqQW2o//
38xKe8+WjKmMYB8RcTdo4e1u2APd4Ws+gCbi5CUxZBoeLsrjSODSHROc99tUvKt067lDHEH+EmGO//
m04mlmE9pUs+GZsrwp6e/glPocnHA4mcgFBtYxtMrwfZH1lCAO

2-Pack

Device Zigbee Mac Install Code
Device 1 AF3830D96D17D4EE 19AC629EB5492F6A802FB8E27940F2FA
Device 2 2A2F808DD2F621CD A204B061A3D6442B86BCC5644C918957

Expected Barcode:

ABV:OB02;UPC:123456789012;PID:wHXD;ZBM:AF3830D96D17D4EE_2A2F808DD2F621CD;ZBD:01BEvTiv/
0aIX9JZTqV
xTyt0C3JEop7M4kTjR8Waapl6aSPx1M2HK7csJhXKH6Vzyld1UgG3gc8bwEub7AGqrrCWiA8zJ3QD3UAtz2XHVmJXTx0D
AwM931gq9IAUyrhXjh7+k8mtrzoN5eUZYYxp0/4YehwnLKUbiUUx6fxAMSsq13cHDr4YLxmU0dJyWlKc72FqU1+QuCUl7M
dkzEmFBqVZsTol4gqQ==

4-pack

Device Zigbee Mac Install Code
Device 1 8F94E50BFA6F32B3 56B39AB0A95474941CC9E5E636A2F0DA
Device 2 405463060C19480A 8E95DCB1DF68D3DFB05CA5CB17E5C041
Device 3 422CE58BA8409A19 FBB2C78F5C385A472F93D0F7F40A0EB9
Device 4 996F98F1AA69A63A 09191476CF1FFC979A57DB36C4DC6782

Expected Barcode:

ABV:OB02;UPC:123456789012;PID:wHXD;ZBM:8F94E50BFA6F32B3_405463060C19480A_422CE58BA8409A19_996F
98F1AA69A63A;ZBD:01BAl7XSbghdBSbXFyY5CKSYagtw34Y5JL/J7zv/5/
au5ihFkmJvaLviaoHGXvNm8PdyDaX40Fczely9Y
RRwT1mjN0tyzDZrCoHvHmd8DF4aaXGYizJti21CKNgDJBQe1gkhvvS8GZkW3rKWC2R5jWAFDnZ/9cxijXf6FBXnLei/
SYQQ bCkgJ7pmf0kIeh7G8CJkf9hs5kWa2Mtp6l1oIKeYcVpGHKwiM3j1tK9i99J97yceJ+efbvPO/
KKtqGp1gDQOw1PfnxWlG6Pav5xtzSs7tlJ7HDUEoc

6-pack

Device Zigbee Mac Install Code
Device 1 C9D73720E870FCC3 16420051B05B70BB877247842749C18C
Device 2 820A1CFA052662E8 A259122B7E4CF50D78D8B76039C9AEB0
Device 3 4C0681E49723C12C FAC01D2BFF5B0F1C8097C37D99FA9CC4
Device 4 7CC49AB68192AE33 D704DD2A062EF678382C7F0C03DB9E06
Device 4 993FCF006993DDFE 13CA985130EF44D59475AEF0CCB6C16C
Device 4 6EEAE31A699EF645 824DD2C7A9ABF77EAFCC5B0CFAF827D2

Expected Barcode:

ABV:OB02;UPC:123456789012;PID:wHXD;ZBM:C9D73720E870FCC3_820A1CFA052662E8_4C0681E49723C12C_7CC4
9AB68192AE33_993FCF006993DDFE_6EEAE31A699EF645;ZBD:01BC2xBxFopz1X/uXccTysb4aWMPEJx3Z13rYwQfNm
NZbWLQZShwAyOoGycg7aoHSYd3ozusGPG30+cyuAeQ6d7fF38Hn4nYL/DSbIJBg71nBZrjzXn/25bFwri2/XT7FQ/NbwiCj
GJo0y18giBLVgJS/c8MJKdVfHTY8EnwsxDrNkwgl7IQSOVQrupsMPMgU2VfLadIhQ75mYo5ky6inlmchLhTelKFqWrohT4i
VF5z0eTb2F8gXP2nz75GXaS0aTb6aLQVkuLX+U2jtgsmOszgVN5qDtzxcOQW2d2rFUzkvzN0us9KT5oNJm0NQzV36uZh8q
4DOnXZSaCPpoWxzKqG9ABPPnngjskg=

General Guidance on Barcode Printing

The following table list common settings used in printing FFS barcodes. You should always test barcodes for validation.

  "Product" barcode "Package" barcode
Dimensions 10 mm x 10 mm (minimum) 15 mm x 15 mm (minimum) Typically 20 mm x 20 mm white labe
Cell Size 36 x 36 36 x 36
Grade Level Grade B or Higher Grade B or Higher
Power Level depends on print method depends on print method
Print Method Laser Etching on Device Print on Label on Device Print on Quick Start Guide Print on Package

FFS Icon Image Guidance Next to Barcode

An FFS key icon image helps customers find the Frustration-Free Setup barcode. Please add the following image to the left of the FFS barcode on your packaging.

Sample Data

Sample Private Key:

-----BEGIN EC PARAMETERS-----
 BgUrgQQAIg==
 -----END EC PARAMETERS-----
 -----BEGIN EC PRIVATE KEY-----
MIGkAgEBBDCZZ9rEjHLbFC4WwBaAoPH5H5VQMKuCBqH/7RkFLKghbXeOy617Qhu+
QnG9NCHrKgigBwYFK4EEACKhZANiAASkXfdXEXE8yKHOdtFoCTMn1wsDzn5xFijR
Vc8h6PwBQw98hfza9BonbA6wd0jWfYr0l/yew0bRjolG9peN/hvasWn6gUEopv
fRZ8nnmEGT36W618E/5975laE4SQ8EU=
-----END EC PRIVATE KEY-----

Sample Public Key:

-----BEGIN PUBLIC KEY-----
MHYwEAYHKoZIzj0CAQYFK4EEACIDYgAEpF33VxFxPMihznbRaAkzJ9cLA85+cRYo
0ZlVXPIej8AUMPfIX82vQaJ2wOsHdI1n2K9Jf8nsNG0Y6JRvaXjf4b2rFp+oFBKK
b30WfJ55hBk9+lutfBP+fe+ZWhOEkPBF
 -----END PUBLIC KEY-----
ABV OB02
UPC 123456789012
PID wHXD
Zigbee Mac (Hex encoded) FA1FFC0CA5FCD16A
Zigbee Install Code (Hex encoded) D262A1E1FDCFF25E436E8AF5C7A623C3
Package Barcode ABV:OB02;UPC:123456789012;PID:wHXD;ZBM:FA1FFC0CA5FCD16A;ZBD:01BOqDGkvjgOr/zBj/sxPYkB45+IhTjY9V1iE OdkSBzwegw2T8FOrEqQW2o//38xKe8+WjKmMYB8RcTdo4e1u2APd4Ws+gCbi5CUxZBoeLsrjSODSHROc99tUvKt067lD HEH+EmGO//m04mlmE9pUs+GZsrwp6e/glPocnHA4mcgFBtYxtMrwfZH1lCAOQ 1;PID:ebK3;PUK:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADLZXG+MzHkCUT1F88yQpaiDW7vu8XDSIhJwsVr2bmmag=;PIN:957AD9640
Version Date Author Description
1.0 Sept 25, 2019. Amazon. General Availability