Your Setup Console

BSS (Bluetooth Mesh) Provisionee 2D Barcode Specification

Frustration-Free Setup (FFS) technology used for Bluetooth Simple Setup relies on your device's package bar code. Amazon scans your device's package bar code 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 Bluetooth Mesh Provisioners control over the new device.

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

Specification for Single and Multi Device Pack BLE Mesh devices

OOB Information types (sourced from the BLE Mesh Profile Specification 1.1)

Value OOB Option
0 Other
1 Electronic/URI
2 2D machine-readable code
3 Bar code
4 Near Field Communication (NFC)
5 Number
6 String
7 Reserved for Future Use
8 Reserved for Future Use
9 Reserved for Future Use
10 Reserved for Future Use
11 On Box
12 Inside Box
13 On piece of paper
14 Inside manual
15 On device

Package 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 OB04 for BLE-Mesh-based devices..
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.
UUID Univerally Unique Identifier Manufacturer specifc UUID adhering to the https://tools.ietf.org/html/rfc4122 UUID specification. In a multi-pack, each UUID will be separated by an underscore "_".
OBD OOB Data This field holds the UUID, OOB Type, OOB Data Type and OOB Data used for provisioning of the device. The value is encrypted by the manufacturer. Please see the 'Generation of OBD' section for more details.

Please note the barcode must contain either UPC or EAN field but never both.

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 OBD For the OBD, data is generated as follows:

  • **Step 1: **Convert UUID into its big-endian 16-byte representation
  • **Step 2: **Create a 16-byte array to hold OOB data for a device. If the OOB Data is less than 16 bytes the remaining the remaining bytes will be set to 0.
  • **Step 3: **Create a 34-byte array to hold all the data generated above
16-byte UUID 1-byte OOB Type 1-byte OOB Data Type 16-byte OOB Data
  • For multi-device packages repeat the above formate for each device. Separate the code pairs with a “_” (underscore) character. For example, the barcode for a package contains 2 devices includes a 69-byte array formatted as follows.
34-byte for the 1st device 1-byte separator 34-byte for the 2nd device
  • Step 5: 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.
    • Please reference our provided sample Java library on the downloads page for examples on how to perform this operation
  • **Step 6: **Covert the encrypted payload (in bytes) into a String using Base64 encoding.

Encryption of OBD Encrypt the entire byte-array created in the previous step holding OOB 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 will be shared with our partners.

Assembling Barcode Base64 encode the OBD data and build UUID list and create a string according to the following structure.

ABV:OB04;UPC:<Product UPC>;PID:<Product Index>;
UUID:<UUID(s)>;OBD:<Encrypted OBD Base64 encoded>

Please Note: Sample barcode output may not match your output due a nonce being used as part of the scheme. As long as your data is able to be decrypted successfully it’ll be considered valid.

Sample Code

Please find attached java implementation samples for generating, encrypting and decrypting this barcode data using sample code.

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: OOB Type, OOB Data Type and OOB Data in the below tables are Hex encoded. 1-Pack

Device UUID OOB Type OOB Data Type OOB Data
Device 1 61c80b5a-a095-4af6-a76e-28053f67b069 2 0 4FC9E30BFE5F426044C8356E53F4F484

Expected Barcode:

ABV:OB04;UPC:123456789012;PID:aBCD;UUID:61c80b5a-a095-4af6-a76e-28053f67b069;
OBD:Axi7rpQnTgIair/Kqb+B4B4budbvZ5YayWAYcMl17UZpOre/+A1n/vSJRosGMWT0dsh8WK+Gf
Je62iaZu/fShwLSkWDws/PI9TVeTd+ukru6AumNxpWp1JfWfO+XGPtFoRmsibSyw6yH0VJ7FxSw1d
yvF6CG8dBiaxvocNjXGrkS

2-Pack

Device UUID OOB Type OOB Data Type OOB Data
Device 1 61c80b5a-a095-4af6-a76e-28053f67b069 2 0 19AC629EB5492F6A802FB8E27940F2FA
Device 2 c9b02ac8-4a7c-41e5-9036-ee59a5a95d8b 2 0 A204B061A3D6442B86BCC5644C918957

Expected Barcode:

ABV:OB04;UPC:123456789012;PID:aBCD;
UUID:61c80b5a-a095-4af6-a76e-28053f67b069_c9b02ac8-4a7c-41e5-9036-ee59a5a95d8b;
OBD:AzZy7lQQSUZ3Ay3/v3jODprW3uujCtQKiyabc8PBp8058LS5J1HDdnOp3s2CIUpeosKCloQssPq
AUu2teoOOiIkKKtUWMPidSRyE/WnI1EWgT3n12HeO5UAWxcaGFCUEkAkxI167HHoOX/jLBhIhtLxdHy
WZ16iTHnYXCoXIEfr4MwVqnSNGlVCMgJ2snvUMAA8SJhLxvp8rEnsT6KecLhU=

4-pack

Device UUID OOB Type OOB Data Type OOB Data
Device 1 61c80b5a-a095-4af6-a76e-28053f67b069 2 0 56B39AB0A95474941CC9E5E636A2F0DA
Device 2 c9b02ac8-4a7c-41e5-9036-ee59a5a95d8b 2 0 8E95DCB1DF68D3DFB05CA5CB17E5C041
Device 3 a1fc3b2b-23a5-462c-b3de-b8732e816224 2 0 FBB2C78F5C385A472F93D0F7F40A0EB9
Device 4 f01dd2a5-9bdf-45e5-82f3-7372d80f38bf 2 0 09191476CF1FFC979A57DB36C4DC6782

Expected Barcode:

ABV:OB04;UPC:123456789012;PID:aBCD;
UUID:61c80b5a-a095-4af6-a76e-28053f67b069_c9b02ac8-4a7c-41e5-9036-ee59a5a95d8b_
a1fc3b2b-23a5-462c-b3de-b8732e816224_f01dd2a5-9bdf-45e5-82f3-7372d80f38bf;
OBD:A49FcLVlDfndUhZ/OPbngbzeQcj58lK842Ql6hTLMwotATFPc+xaqRLMBeY+ZIdPldcy7JfiVAII
UsJGhI+0q/XNBvu2z103JKm/B7wJVz4LpLSMrUVFHxjhy9aOe0WQceX63QEwQiav5/zn/xR+jOKZFQ7m
Tb1OBmX3M81kOhlawkoT0i15yFaxDpOrN2lYyDDZJ+R2PBOibC5w9sVVyo1hbrU00Suak3ZKE3HjblGa
Pz77NRARpQvpq8bWJbtH66yVpzxjFRje0lsEf4LbmxNKyce8LF3U8fKYnp+TkxMv

6-pack

Device UUID OOB Type OOB Data Type OOB Data
Device 1 61c80b5a-a095-4af6-a76e-28053f67b069 2 0 16420051B05B70BB877247842749C18C
Device 2 c9b02ac8-4a7c-41e5-9036-ee59a5a95d8b 2 0 A259122B7E4CF50D78D8B76039C9AEB0
Device 3 a1fc3b2b-23a5-462c-b3de-b8732e816224 2 0 FAC01D2BFF5B0F1C8097C37D99FA9CC4
Device 4 f01dd2a5-9bdf-45e5-82f3-7372d80f38bf 2 0 D704DD2A062EF678382C7F0C03DB9E06
Device 5 9508fece-0da4-4f4a-a918-def22f292509 2 0 13CA985130EF44D59475AEF0CCB6C16C
Device 6 f4c46beb-1840-4c8d-8072-21f5abfb0cf0 2 0 824DD2C7A9ABF77EAFCC5B0CFAF827D2

Expected Barcode:

ABV:OB04;UPC:123456789012;PID:aBCD;UUID:61c80b5a-a095-4af6-a76e-28053f67b069_c9b0
2ac8-4a7c-41e5-9036-ee59a5a95d8b_a1fc3b2b-23a5-462c-b3de-b8732e816224_f01dd2a5-9
bdf-45e5-82f3-7372d80f38bf_9508fece-0da4-4f4a-a918-def22f292509_f4c46beb-1840-4c
8d-8072-21f5abfb0cf0;OBD:A0kcFoAXJrudMFk0StB5NkD94jg3nhjVAORwt05oTCcn1vsoc53l5uNQ
GC6Zd34KZfHAFqyV4mAlVGsb4vMUwCDcLWbyuCKQVYMyl1N9mEkXu5rwUJg1v2EuenfG1B7yHjMDZ2JgN
k4ATNqapPx0s9V60fGSkI/35oWJD9BydstfClsLRT855AnRtUBA5+WPVgVbHR8jua6nxGLg/jlHLItpP5
bpjjFjDS5bJe/tHq0NFgux2RAkDmNyrLDD3tEJLoQ4G1xcmS7FzI6eet25JLB/NhFVh5FJvpK3bYxyC8a
FCHaEEQjraU/qdDshLF3qO2NAzatAcRk0j4brPZLqdS62kVX4jOeJ++W6VH6WqzRyPJ5rmG5miBc+uFss
lfhyZE6k2sioWKfn8yu4i2FL3KY=

General Guidance for Bar Code Generation


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

Version Date Author Description
1.0 Sept 23, 2020. Amazon. General Availability