Your Setup Console

Provisionee 2D Barcode Specification

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

A trailing semi-colon to terminate the content string is considered Optional.

FFS technology utilizes two different barcodes -

Product Barcode (Inner Barcode) - This is included inside the packaging of the device (ideally on the device surface). Package Barcode (Outer Barcode) - This is printed on the outside of the packaging of the device. The 'inner' barcode is scanned by the customer using a mobile app to claim ownership of the device so that FFS technology can automatically set up the device (i.e. vend it wi-fi creds and register) with the customer's account. The 'outer' barcode is scanned at the fulfillment center by the associates while shipping the device.

[Single Device Pack] DHA-Enabled Devices

Specification

The following is the full schema for the barcode

'inner' barcode: (ABV, PID, PUK, PIN, FSNHEX )

'outer' barcode: (ABV, UPC/EAN, FSNHEX, PID, PUK)

A package will have either an EAN or a UPC, not both.

Product Barcode (Inner 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. For product barcode (inner barcode) its value is always IB01
FSNHEX Device Serial Number Uniquely identifies the device which is assigned during the time of manufacturing. Amazon DSNs are 16 Alphanumeric digits long. The FSNHEX in the product barcode (inner barcode) is optional
PID Product Id 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. It is alphanumeric and 4 characters in length. Reach out to your business development / solution architect lead to create a Product ID.
PUK Compressed Public Key Public Key of the device that was generated during device manufacturing. This needs to adhere to the following representation - Base64.encode( compressed ECC public Key) and is unique to every device. Typically, we would use ECC 256-bit keys.
PIN Secret Pin A random secret PIN for the device generated at the time of device manufacturing. This is AlphaNumeric (Base64 = 27 x 2 + 10) and 9 characters in length. The PIN should also be stored on the device during the time of manufacturing and once stored should only be accessible by the FFS and/or the OOBE Application. PIN must be random. PIN must not use other barcode information (private or public key) as a seed

Package Barcode (Inner 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. For product barcode (inner barcode) its value is always OB01.
UPC Universal Product Code 12 digit numeric value assigned for the product by the manufacturer. 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
FSNHEX Device Serial Number Uniquely identifies the device which is assigned during the time of manufacturing. Amazon DSNs are 16 Alphanumeric digits long. The FSNHEX in the product barcode (inner barcode) is optional
PID Product ID 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. It is alphanumeric and 4 characters in length. Reach out to your business development / solution architect lead to create a Product ID.
PUK Compressed Public Key Public Key of the device that was generated during device manufacturing. This needs to adhere to the following representation - Base64.encode( compressed ECC public Key) and is unique to every device. Typically, we would use ECC 256-bit keys.

General Guidance for Barcode Generation

Below is the list of common settings that products should utilize to guide the printing of the FFS barcodes. The actual barcodes should, however, be tested to validate they are able to be effectively scanned.

Common Settings for Printing FFS Barcode

Key Inner Barcode Outer Barcode
Dimensions 10 mm x 10 mm (minimum) 15 mm x 15 mm (minimum) Typically 20 mm x 20 mm white label
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 Shipping Label

Sample Data

ABV OB02
ABV IB01 (Inner Barcode) OR OB01 (Outer Barcode)
UPC 841667145075
DSN/FSNHEX G3A0PA01802300PE
PID ebK3
PUK MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADLZXG+MzHkCUT1F88yQpaiDW7vu8XDSIhJwsVr2bmmag=
PIN 957AD9640
Inner Barcode with FSNHEX ABV:IB01;PID:ebK3;PUK:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADLZXG+MzHkCUT1F88yQpaiDW7vu8XDSIhJwsVr2bmmag=;PIN:957AD9640;FSNHEX:G3A0PA01802300PE;
Inner Barcode without FSNHEX ABV:IB01;PID:ebK3;PUK:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADLZXG+MzHkCUT1F88yQpaiDW7vu8XDSIhJwsVr2bmmag=;PIN:957AD9640; Sample Barcode Image
Outer Barcode with FSNHEX ABV:OB01;UPC:841667145075;FSNHEX:G3A0PA01802300PE;PID:ebK3;PUK:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADLZXG+MzHkCUT1F88yQpaiDW7vu8XDSIhJwsVr2bmmag=;
Outer Barcode without FSNHEX ABV:OB01;UPC:841667145075;PID:ebK3;PUK:MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADLZXG+MzHkCUT1F88yQpaiDW7vu8XDSIhJwsVr2bmmag=; Sample Barcode Image

[Multi-Device Pack] DHA-Enabled Devices

Specification

Note: Since multi-device barcodes will only be printed on the outside of the packaging there is no concept of multi-device 'product' barcodes.

A package will have either an EAN or a UPC, not both.

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 OB03 for 3P DHAv2-based authentication enabled devices multi-pack.
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.
PUK Compressed public key Public Key of the device that was generated during device manufacturing.This has to adhere to the following format: Base64.encode(PUK1)_Base64.encode(PUK2) where PUK1, PUK2 are compressed public keys. The underscore '_' is a delimiter between encoded PUKs of individual devices in the pack. It is recommended to use ECC 256-bit keys with prime256v1 curve.

General Guidance for Barcode Generation

Below is the list of common settings that products should utilize to guide the printing of the FFS barcodes. The actual barcodes should, however, be tested to validate they are able to be effectively scanned.

No of Devices Size of Barcode (mmXmm)
1 22 mm x 22 mm
2 40 mm x 40 mm
3 50 mm x 50 mm
4 54 mm x 54 mm
5 60 mm x 60 mm
6 64 mm x 64 mm

Sample Data

PUK generation logic for 2-device pack

  1. Generate 2 ECC Public Keys
  2. Concatenate their Base64.encoded() content with an underscore '_' separating the two. This will be the value of the PUK field

ECCPub1

-----BEGIN PUBLIC KEY-----

MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqdr7Kk24tVzAWFR7xjH+yueoGU3H
AEtMfxWebg/sUXIfmewn1VpNHL7ShZ3MRmcOzxcyZXkm1mje2RSok9aXHA==

-----END PUBLIC KEY-----

ECCPub2

-----BEGIN PUBLIC KEY-----

MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn8s5ws59qfIMjQaM8qnmSUonI8Se
pdxz5vnpJUEt73smTVuNmd6lIExG7H0dOGhJ96ho+S0/RKnmj7Cjme0ZUg==

-----END PUBLIC KEY-----

For packages with UPC

ABV:OB03;UPC:841667145075;PID:Abv3;PUK:MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqdr7Kk24tVzAWFR7xjH+yueoGU3HAEtMfxWebg/sUXIfmewn1VpNHL7ShZ3MRmcOzxcyZXkm1mje2RSok9aXHA==_MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn8s5ws59qfIMjQaM8qnmSUonI8Sepdxz5vnpJUEt73smTVuNmd6lIExG7H0dOGhJ96ho+S0/RKnmj7Cjme0ZUg==;

For packages with EAN

ABV:OB03;EAN:9002236311037;PID:Abv3;PUK:MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEqdr7Kk24tVzAWFR7xjH+yueoGU3HAEtMfxWebg/sUXIfmewn1VpNHL7ShZ3MRmcOzxcyZXkm1mje2RSok9aXHA==_MFkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDQgAEn8s5ws59qfIMjQaM8qnmSUonI8Sepdxz5vnpJUEt73smTVuNmd6lIExG7H0dOGhJ96ho+S0/RKnmj7Cjme0ZUg==;

[Single and Multi Device Pack] Zigbee Enabled Philips Lightbulbs

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 lightbulbs 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 for Barcode Placement

Placement of the barcode should follow the guidelines from the GS1 US barcode placement specification.

In particular, the following rules should be followed:

  • General placement - Back of the box, Lower right quadrant
  • Edge rule - No less than 8mm from the edge, no more than 102mm from the edge of the package
  • Quiet Zone sizing - The Quiet Zone (blank space around the barcode) should follow a 2x module size rule.
  • For a .37mm module size, the QZ should be .74mm