Zigbee Simple Setup (ZSS) Provisionee 2D Barcode Specification

• Overview
• Specification
• Generation of the ZBD Field
• [Single and Multi Device Pack] Zigbee Enabled Devices
  • Specification
  • General Guidance for Barcode generation
  • Sample Data
• General Guidance on Barcode Printing

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….).

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)

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 products, 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.

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-----
<256-bit private EC key>
-----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

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

Expected Barcode:

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

4-pack

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

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.

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-----
<256-bit private EC key>
-----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