Control Log Specification

This guide describes the format and use of Control Logs.

Control Logs Overview
- Device Control Logs
- Bundle Control Logs
Device Control Log File Format
Bundle Control Log File Format
- The bundleSerialNumber Property
- The devices Object
Device Control Log Schema Definition
Bundle Control Log Schema Definition

Control Logs Overview

In order to enable automated simple setup, devices should be pre-registered to a customer who purchased these devices from Amazon. This operation needs access to authentication material of the devices. In order to enable usage of 1D barcode with an encoded identifier of a device or device bundle to perform this pre-registration a mapping of this identifier to corresponding authentication material is required.

Control Logs is a mechanism that provides this mapping by uploading control log files to Amazon.

Learn more about 1D barcode requirements in 1D barcode specification.

There are two types of control log files:

Device Control log files
Bundle Control log files

The contents of Device Control log files and Bundle Control Log files are formatted as JSON.

Device Control Logs

Device Control Log files define individual devices. They should be generated and uploaded to Amazon during manufacturing.

Each Device Control Log entry must contain unique identifiers of a specific manufactured device including:

At least one device identification value.
Product identification
Authentication material for this device depending on the protocol.

The following elements can be used as a device identification value:

serialNumber property of the device object.
Any MAC or UUID item listed in the radios object.

A 1D barcode encoded with a device identification value of the purchased device is scanned in a fulfillment center and it is used to search for a control log entry, extract the authentication material of the device and perform this pre-registration.

Note: If a serial number is used as device identification value to pre-register a device to a customer you need to make sure that the same serial number is used across different Amazon services to avoid potential mismatch issues.

Bundle Control Logs

Bundle Control Log files define package groupings of devices sold as a single unit as a multi-device package (bundle). Devices sold within a bundle must first be defined and uploaded within a Device Control Log file, and then within a Bundle Control Log file.

Each Device Bundle Control Log entry must contain unique identifiers of a bundle and specific manufactured devices included into this bundle:

Unique bundleSerialNumber for each individual package.
A list of devices in this bundle with product identification and device identification values.

If some already uploaded bundle needs to be replaced then you need to send a new bundle record with the same bundleSerialNumber and isUpdate parameter set to true. This new record will replace the old one so you have to include the complete list of devices into the record.

1D barcode with an encoded bundle identifier of the purchased bundle is scanned in a fulfillment center and it is used to lookup a list of devices included into the bundle, search for control log entries of these individual devices, extract the authentication material of these devices and perform this pre-registration.

Visit Manage Control Logs page of Amazon Frustration-Free Setup Developer Console to setup a secure end point to which you upload your control log files and download feedback files with the control logs processing results.

Consider downloading a command line interface tool from Downloads page of the portal that can help to generate and validate control log files using JSON schema.

Device Control Log File Format

A device control Logs are uploaded using text file with control log entries in JSON format. A control log file name is created using the following format: C_CONTROL_LOG_<date and time in yyyyMMddhhmmss format>.txt

Example

C_CONTROL_LOG_20201212235959.txt

The file content starts with the controlLogs[] object.

Example

{
  "controlLogs": [....]
}

Every device is defined within the controlLogs[] object. Each device definition must contain a "version": "4-0-3" property and a"device" : {} object.

Example

{
  "controlLogs" : [
    {
      "version" : "4-0-3",
      "device" : {
        ...
      }
    },
    {
      "version" : "4-0-3",
      "device" : {
        ...
      }
    }
  ]
}

Note: "4-0-3" is the only supported value for the "version" property at the moment.

The device Object

The device object defines the attributes of a device within the Device Control Log. The device object is a container for all other information regarding a device.

The following is an example of using the serialNumber property to identify devices. The serialNumber property must conform to the regular expression ^[0-9a-zA-Z+=_-]{5,50}$ and a minimum length of 5 characters.

Example

{
  "controlLogs" : [
    {
      "version" : "4-0-3",
      "device" : {
        "serialNumber": "device1SN"
      }
    },
    {
      "version" : "4-0-3",
      "device" : {
        "serialNumber": "device2SN"
      }
    }
  ]
}

The radios Object

The radios object is a container used to list information about all the radios within a device. The radios object supports the following sub-objects:

wifiMACs
bluetoothMACs
ethernetMACs
zigbeeMACs
bleMeshUUIDs

The radios object is optional. The radios object lists 1 or more MAC addresses for each radio, (or UUIDs in the case of BLE Mesh). You can use the radios object to list all of the radio types your device supports.

Example 1

The following example defines a device with 1 Wi-Fi radio.

{
  "controlLogs" : [
    {
      "version" : "4-0-3",
      "device" : {
        "radios": {
          "wifiMACs": [
            "A0CB678C912E"
          ]
        }
      }
    }
  ]
}

Example 2 The following example defines a device with 1 Wi-Fi radio. This radio has two MAC addresses.

{
  "controlLogs" : [
    {
      "version" : "4-0-3",
      "device": {
        "radios": {
          "wifiMACs": [
            "A0CB678C912D",
            "A0CB678C912E"
          ]
        }
      }
    }
  ]
}

Example 3

The following example defines a device with a serial number and two radios (a Wi-Fi radio and a bluetooth radio). Both radios have a single MAC addresses.

{
  "controlLogs" : [
    {
     "version" : "4-0-3",
     "device": {
        "serialNumber": "device1SN",
        "radios": {
          "wifiMACs": [
            "A0CB678C912D"
          ],
          "bluetoothMACs": [
            "A0BC60BD9121"
          ]
        }
      }
    }
  ]
}

The productIdentifier Object

The productIdentifier object is required and must contain the advertisedProductId. When you receive notification that your device type is registered, you will receive your device's Advertised Product ID (APID). This APID is used as the value for the advertisedProductId property.

Example

{
  "controlLogs" : [
    {
     "version" : "4-0-3",
     "device": {
       "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "radios": {
          "wifiMACs": [
            "A0CB678C912D"
          ],
          "bluetoothMACs": [
            "A0BC60BD9121"
          ]
        }
      }
    }
  ]
}

The zigbeeData Object

The zigbeeData object is authentication material for Zigbee radio. It provides encrypted version of your device's string encoded zigbee MAC and install code.

Example

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "zigbeeData": [
          "01BOqDGkvjgOr/zBj/sxPYkB45+IhTjY9V1iE OdkSBzwegw2T8FOrEqQW2o//38xKe8+WjKmMYB8RcTdo4e1u2"
        ]
      }
    }
  ]
}

The bleMeshOBDData Object

The bleMeshOBDData object is authentication material for BLE Mesh radio. It provides the encrypted and base64-encoded version of your device's UUID, OOB type, OOB data type, and OOB data.

Example

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
        "AzzTpz4M7Xllx3mFmbVLLxliAW+iFvA6MyfAZ4louNMli+GMvVIrlajrCwmPF6NtoE9nAOhjIYKr3GH6T+3OyR0DHhD5S6pia7aQy6/WiErToBnsQfvXIonG"
        ]
      }
    }
  ]
}

The matterData Object

The matterData object is authentication for Matter devices. It provides an encrypted version of your device's Matter-specific data. See below for more details.

Example

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "matterData": [
        "AzzTpz4M7Xllx3mFmbVLLxliAW+...5NaZJs/lUGpqXs91DI="
        ]
      }
    }
  ]
}

Encrypting Matter data

Encrypting Matter data for control logs is similar to encrypting authentication data for 2D barcodes. To encrypt Matter data:

Convert your matterData JSON string to a UTF-8 encoded byte array.
Encrypt the entire byte array created in the previous step using the Auth Material Encryption Public Key shared by Amazon that is specific to your product. 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.
Base64 encode the encrypted string from the previous step

To perform the encryption of a matterData object, you can use a cryptography toolkit such as OpenSSL. Alternatively, you can use a cryptography library for the programming language of your choosing.

For a reference implentation please download Frustration Free Setup's sample code for generating a Matter Simple Setup device control log using Java and the Bouncy Castle crypto library for Matter data encryption.

The devicePublicKey Object

The devicePublicKey is authentication material for Wi-Fi radio. It provides the device's Base64-encoded public key from a DHA certificate.

Example

{
  "controlLogs": [
    {
    "version": "4-0-3",
    "device": {
        "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "devicePublicKey": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADbBej6yy1Qqmqg6PGooyb4gaDkfKlGBTmxX2+Y58Te54="
      }
    }
  ]
}

Device Control Log Examples for various scenarios

This section provides a set of example Device Control Logs for various scenarios.

Wi-Fi Enabled Device Examples

Example 1

The following example shows the use of the serialNumber property and well as the devicePublicKey property.

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "devicePublicKey": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADbBej6yy1Qqmqg6PGooyb4gaDkfKlGBTmxX2+Y58Te54="
      }
    }
  ]
}

Example 2

The following example shows a device defined with two radios.

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1SN",
        "radios": {
          "wifiMACs": [
            "A0BC60BD9121"
          ],
          "bluetoothMACs": [
            "A0BC60BD9121"
          ]
        },
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "devicePublicKey": "MDkwEwYHKoZIzj0CAQYIKoZIzj0DAQcDIgADbBej6yy1Qqmqg6PGooyb4gaDkfKlGBTmxX2+Y58Te54="
      }
    }
  ]
}

Zigbee Enabled Device Examples

Example 1

The following example shows a zigbee device.

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "zigbeeData": [
          "01BOqDGkvjgOr/zBj/sxPYkB45+IhTjY9V1iE OdkSBzwegw2T8FOrEqQW2o//38xKe8+WjKmMYB8RcTdo4e1u2APd4Ws+gCbi5CUxZBoeLsrjSODSHROc99tUvKt"
        ]
      }
    }
  ]
}

Example 2

The following example defines a device with two radios (a zigbee radio and a bluetooth radio).

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1",
        "radios": {
          "zigbeeMACs": [
            "A0BC60BD91211234"
          ],
          "bluetoothMACs": [
            "A0BC60BD9121"
          ]
        },
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "zigbeeData": [
          "01BOqDGkvjgOr/zBj/sxPYkB45+IhTjY9V1iE OdkSBzwegw2T8FOrEqQW2o//38xKe8+WjKmMYB8RcTdo4e1u2APd4Ws+gCbi5CUxZBoeLsrjSODSHROc99tUvKt067lD"
        ]
      }
    }
  ]
}

Bluetooth Device Examples

Example 1

The following is a simple bluetooth device definition.

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
        "AzzTpz4M7Xllx3mFmbVLLxliAW+iFvA6MyfAZ4louNMli+GMvVIrlajrCwmPF6NtoE9nAOhjIYKr3GH6T+3OyR0DHhD5S6pia7aQy6/WiErToBnsQfvXIonGvuoB5JbQe/8ae5NaZJs/lUGpqXs91DI="
        ]
      }
    }
  ]
}

Example 2

The following example defines a device with two radios (a bluetooth radio and a BLEmesh radio).

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1SN",
        "radios": {
          "bluetoothMACs": [
            "A0BC60BD9121"
          ],
          "bleMeshUUIDs": [
            "6a2f41a3-c54c-fce8-32d2-0324e1c32e22"
          ]
        },
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
        "AzzTpz4M7Xllx3mFmbVLLxliAW+iFvA6MyfAZ4louNMli+GMvVIrlajrCwmPF6NtoE9nAOhjIYKr3GH6T+3OyR0DHhD5S6pia7aQy6/WiErToBnsQfvXIonGvuoB5JbQe/8ae5NaZJs/lUGpqXs91DI="
        ]
      }
    }
  ]
}

Matter Device Example and Format

The following is a simple Matter device definition.

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "device1",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "matterData": [
          "AzzTpz4M7Xllx3mFmbVLLxliAW+...5NaZJs/lUGpqXs91DI="
        ]
      }
    }
  ]
}

The matterData value in the above example is a JSON object converted to a UTF-8 encoded byte array that has been encrypted using the public key generated during device onboarding, then Base64 encoded. Its schema is as follows.

{
    "$schema": "http://json-schema.org/draft-07/schema#",
    "description": "Schema for the \"matterData\" item plaintext",
    "type": "object",
    "required": [
        "vendorId",
        "productId",
        "discriminator",
        "uniqueDeviceId",
        "rotatingIdAlgorithm",
        "passcode"
    ],
    "dependencies": {
        "productId": [
            "vendorId"
        ]
    },
    "properties": {
        "vendorId": {
            "type": "integer",
            "description": "Vendor ID",
            "minimum": 0,
            "maximum": 65535
        },
        "productId": {
            "type": "integer",
            "description": "Product ID",
            "minimum": 0,
            "maximum": 65535
        },
        "uniqueDeviceId": {
            "type": "string",
            "description": "Unique device ID used to generate a Rotating Device identifier",
            "$comment": "≥128 bits",
            "minLength": 22,
            "contentEncoding": "base64",
            "contentMediaType": "application/octet-stream"
        },
        "rotatingIdAlgorithm": {
            "type": "string",
            "description": "Algorithm used to generate rotating device identifier using the uniqueDeviceId",
            "enum": [
                "MATTER_V0",
                "MATTER_V1"
            ]
        },
        "discriminator": {
            "type": "integer",
            "description": "Discriminator",
            "minimum": 0,
            "maximum": 4095
        },
        "passcode": {
            "type": "integer",
            "description": "Passcode",
            "minimum": 1,
            "maximum": 99999998
        },
        "proofOfPossessionCode": {
            "type": "string",
            "description": "Proof-of-possession code printed on the unit"
        },
        "challengeScheme": {
            "type": "string",
            "description": "Challenge method",
            "enum": [
                "AMAZON_PREFERRED"
            ],
            "$comment": "There is one supported challenge scheme value right now, AMAZON_PREFERRED. Additional options will be available in the future."
        }
    }
}

Challenge Scheme The Challenge Scheme that is required to be provided in the Control Logs is intended to allow device makers to indicate additional challenges that must be completed by the customer before providing the Passcode during Matter Simple Setup. For now device makers should only provide the value AMAZON_PREFERRED for their challenge scheme. Additional challenges will be supported in the future but are not yet available. Keep an eye on our developer portal for news about additional schemes being supported in the future.

Here is an example of a matterData object prior to encryption.

{
  "vendorId": 9876,
  "productId": 1234,
  "uniqueDeviceId": "dGVzdGRldmljZWlkYXNhbmV4YW1wbGVvZmF1bmlxdWVkZXZpY2VpZHRlc3RkZXZpY2VpZGFzYW5leGFtcGxlb2ZhdW5pcXVlZGV2aWNlaWR0ZXN0ZGV2aWNlaWR0ZXN0",
  "rotatingIdAlgorithm": "MATTER_V1",
  "discriminator": 3210,
  "passcode": 9876543,
  "proofOfPossessionCode": "123456",
  "challengeScheme": "MATTER_SETUP_CODE_FIRST_FOUR_DIGITS"
}

Here are some more details about the fields needed for the matterData JSON object that will be encrypted.

Item	Required	Matter Spec reference	In BLE Beacon	Size	Description
Vendor ID	Yes	2.5.2, 5.1.2.2	Yes	16 bits	A number allocated by the Connectivity Standards Alliance to uniquely identify a manufacturer, vendor, or ecosystem.
Product ID	Yes	5.1.2.2	Yes	16 bits	A number allocated by the manufacturer to uniquely identify a product.
Unique ID	Yes	5.2.5.5.2	Yes	≥128 bits	A randomly-generated 128-bit or longer number programmed during factory provisioning and constant over the lifetime of the peripheral device. Used to generate the "rotating ID". The rotating ID may be made available via an unencrypted BLE characteristic at the discretion of the manufacturer.
Discriminator	Yes	5.1.2.5	Yes	12 bits	A random value in the range 0-4095 provisioned onto the device in the factory and included in the BLE advertisement to help identify devices during setup.
Passcode	Yes	5.1.2.6	N/A	27 bits	Used to establish proof-of-possession and also as the shared secret in setting up the initial secure channel with the provisionee.

Bundle Control Log File Format

A device control log for each individual device in the bundle should be sent prior to the uploading of Bundle Control logs.

A bundle control log file name is created using the following format: BUNDLE_CONTROL_LOG_<date and time in yyyyMMddhhmmss format>.txt

Example

BUNDLE_CONTROL_LOG_20201212235959.txt

A Bundle Control Log file starts with the controlLogs[] object.

Example

{
  "controlLogs": [....]
}

Every device bundle is defined within the controlLogs[] object. Each entry must contain a "version": "5-0-0" property, a "bundleSerialNumber" property, and a devices[] object.

Example

{
  "controlLogs" : [
    {
      "version" : "5-0-0",
      "bundleSerialNumber" : "ABCD",
      "devices" : [
        ...
      ]
    },
    {
      "version" : "5-0-0",
      "bundleSerialNumber" : "DCBA",
      "devices" : [
        ...
      ]
    }
  ]
}

See the devices object section for a more complete example on how to populate the devices[] object

The bundleSerialNumber Property

The bundleSerialNumber property uniquely identifies all devices within the Bundle Control Log and denotes the identifier printed as the barcode on the bundle package. The bundleSerialNumber property must conform to the regular expression ^[0-9a-zA-Z+=_-]{5,30}$ and has a minimal length of 5 characters.

The devices Object

The devices object contains identification information for each device within this bundle.

Example

The following example shows a simple Device Control log and the corresponding Device Bundle Control Log.

Device Control Log

{
  "controlLogs": [
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "GD125F3453",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
          "A8/dY7/6XjmPJ1X0MjCgNpUO/pDJgE+SyOf9VtITGlKw7tV0Y656ZSdHFG+eQ5V3j9bt8YsFAtpSOJixNLclbh71Tz3O7/ZQVLmfd9uPI+FTUIu6euLma6WSkyiONGugiXsnxLzjoblYa9lImu7OU5IkoLwXcVPHmCOiv/wq6fmu"
        ]
      }
    },
    {
      "version": "4-0-3",
      "device": {
        "serialNumber": "GD125F3454",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
          "Ay39klWvSu+r4cFyNjbQ7v7Wiuj8sB9qBi1bF2VXXJA6icpAbOPuyp3MdkH0CNNtSRCnRiQl8cqDibNT5Awngjy8XTQYugnXjCmI6UPcbSujduJlmhm3R2tlAEgwFrxaaLWEr3ho68biWRcesh58miws9yF7B5ApOKu/S16xNdjp"
        ]
      }
    }
  ]
}

Bundle Control Log

    {
      "controlLogs": [
        {
          "version": "5-0-0",
          "bundleSerialNumber": "ABCDE",
          "devices": [
            {
              "productInstanceIdentifier": {
                "serialNumber": "GD125F3453"
              },
              "productIdentifier": {
                "advertisedProductId": "abCD"
              }
            },
            {
              "productInstanceIdentifier": {
                "serialNumber": "GD125F3454"
              },
              "productIdentifier": {
                "advertisedProductId": "abCD"
              }
            }
          ]
        }
      ]
    }

Device Control Log Schema Definition

Copied to clipboard.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Amazon device control logs schema",
  "type": "object",
  "required": [
    "controlLogs"
  ],
  "properties": {
    "controlLogs": {
      "description": "An array of per-device control log records",
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "description": "Per-device control log record",
        "required": [
          "device",
          "version"
        ],
        "properties": {
          "version": {
            "type": "string",
            "description": "Control Log Version"
          },
          "device": {
            "type": "object",
            "description": "Information about a device and its various components",
            "required": [
              "productIdentifier"
            ],
            "properties": {
              "serialNumber": {
                "description": "unique serial number to resolve the third party device",
                "type": "string",
                "pattern": "^[0-9a-zA-Z+=_-]{5,50}$"
              },
              "radios": {
                "description": "The set of radios in the device",
                "type": "object",
                "properties": {
                  "wifiMACs": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "WiFi radio MAC address to resolve the third party device",
                      "pattern": "^[0-9A-F]{12}$"
                    },
                    "minItems": 1,
                    "maxItems": 2,
                    "uniqueItems": true,
                    "description": "Array of device’s WiFi radio MAC addresses - mostly just 1 element"
                  },
                  "bluetoothMACs": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "Bluetooth radio MAC address to resolve the third party device",
                      "pattern": "^[0-9A-F]{12}$"
                    },
                    "minItems": 1,
                    "maxItems": 1,
                    "uniqueItems": true,
                    "description": "Array of device’s Bluetooth radio MAC addresses - always just 1 element"
                  },
                  "ethernetMACs": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "Ethernet radio MAC address to resolve the third party device",
                      "pattern": "^[0-9A-F]{12}$"
                    },
                    "minItems": 1,
                    "maxItems": 1,
                    "uniqueItems": true,
                    "description": "Array of device’s Ethernet radio MAC addresses - always just 1 element"
                  },
                  "zigbeeMACs": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "Zigbee radio MAC address to resolve the third party device",
                      "pattern": "^[0-9A-F]{16}$"
                    },
                    "minItems": 1,
                    "maxItems": 1,
                    "uniqueItems": true,
                    "description": "Array of device’s Zigbee radio MAC addresses - always just 1 element"
                  },
                  "bleMeshUUIDs": {
                    "type": "array",
                    "items": {
                      "type": "string",
                      "description": "BLE UUID to resolve the third party device ",
                      "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
                    },
                    "minItems": 1,
                    "maxItems": 1,
                    "uniqueItems": true,
                    "description": "Array of device’s UUIDs - always just 1 element"
                  }
                }
              },
              "productIdentifier": {
                "description": "Identifier to identify a product type",
                "type": "object",
                "properties": {
                  "advertisedProductId": {
                    "type": "string",
                    "description": "Advertised Product ID of a device"
                  }
                }
              },
              "zigbeeData": {
                "type": "array",
                "description": "An array of zigbee data for a device",
                "minItems": 1,
                "maxItems": 1,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "description": "Zigbee Data is encrypted version of string encoded with zigbee mac and zigbee install code."
                }
              },
              "devicePublicKey": {
                "type": "string",
                "description": "compressed Public key in base64 encoded format"
              },
              "bleMeshOBDData": {
                "type": "array",
                "description": "An array of BLE OBD data for a device",
                "minItems": 1,
                "maxItems": 1,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "description": "BLE Mesh OBD Data is encrypted version of string encoded with UUID, OOB type, OOB data type and OOB data."
                }
              },
              "matterData": {
                "type": "array",
                "description": "An array of Matter data for a device",
                "minItems": 1,
                "maxItems": 1,
                "uniqueItems": true,
                "items": {
                  "type": "string",
                  "description": "An encrypted JSON string encoding Matter provisioning data."
                }
              }
            }
          }
        }
      }
    }
  }
}

Bundle Control Log Schema Definition

Copied to clipboard.

{
  "$schema": "http://json-schema.org/draft-04/schema#",
  "description": "Amazon control logs schema for bundles of devices",
  "type": "object",
  "required": [
    "controlLogs"
  ],
  "properties": {
    "controlLogs": {
      "description": "An array of bundle control logs",
      "type": "array",
      "minItems": 1,
        "items": {
          "type": "object",
          "description": "Per-bundle control log record",
          "required": [
            "devices",
            "bundleSerialNumber",
            "version"
          ],
          "properties": {
            "version": {
              "type": "string",
              "description": "Control Log Version - 5-0-0"
            },
            "bundleSerialNumber": {
              "type": "string",
              "pattern": "^[0-9a-zA-Z+=_-]{5,30}$",
              "description": "Serial number of a bundle"
            },
            "isUpdate": {
              "type": "boolean",
              "description": "if present and set to true, this bundle will replace an existing bundle definition"
            },
            "devices": {
              "type": "array",
              "description": "List of devices packed in the bundle",
              "minItems": 1,
              "items": {
                "type": "object",
                "description": "device identifier to resolve a device",
                "required": [
                  "productInstanceIdentifier",
                  "productIdentifier"
                ],
                "properties": {
                  "productInstanceIdentifier": {
                    "description": "Unique identifier which will be printed on barcode. Possible value could be anyone of the serialNumber, wifiMAC etc.",
                    "type": "object",
                    "properties": {
                      "serialNumber": {
                        "description": "unique serial number to resolve the third party device ",
                        "type": "string",
                        "pattern": "^[0-9a-zA-Z+=_-]{5,50}$"
                      },
                      "wifiMAC": {
                        "type": "string",
                        "description": "WiFi radio MAC address to resolve the third party device",
                        "pattern": "^[0-9A-F]{12}$"
                      },
                      "bluetoothMAC": {
                        "type": "string",
                        "description": "Bluetooth radio MAC address to resolve the third party device",
                        "pattern": "^[0-9A-F]{12}$"
                      },
                      "ethernetMAC": {
                        "type": "string",
                        "description": "Ethernet radio MAC address to resolve the third party device",
                        "pattern": "^[0-9A-F]{12}$"
                      },
                      "zigbeeMAC": {
                        "type": "string",
                        "description": "Zigbee radio MAC address to resolve the third party device",
                        "pattern": "^[0-9A-F]{16}$"
                      },
                      "bleMeshUUID": {
                        "type": "string",
                        "description": "BLE UUID to resolve the third party device ",
                        "pattern": "^[a-fA-F0-9]{8}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{4}-[a-fA-F0-9]{12}$"
                      }
                    }
                  },
                  "productIdentifier": {
                    "description": "Identifier to identify a product type",
                    "type": "object",
                    "properties": {
                      "advertisedProductId": {
                        "type": "string",
                        "description": "Advertised Product ID of a device"
                      }
                    }
                  }
                }
              }
            }
          }
        }
      }
    }
  }

Version	Date	Author	Description
1.0	Jan 21, 2021.	Amazon.	Soft DAKs and Control Logs General Availability.
1.1	Feb 12, 2021.	Amazon.	MAC or UUID as device identification.
1.2	Apr 30, 2021.	Amazon.	Bundles support.
1.3	Nov 3, 2021.	Amazon.	Matter support.

Last updated: Feb 17, 2023