BSS (Bluetooth Mesh) Provisionee 2D Barcode Specification
- Specification for Single and Multi Device Pack BLE Mesh devices
- General Guidance for Barcode generation
- Sample Code
- Sample Data
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 |