Consola del desarrollador
Gracias por tu visita. Esta página solo está disponible en inglés.

Control Log Specification

This guide describes the format and use of Control Logs.

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.

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-0" property and a"device" : {} object.

Example

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

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-0",
      "device" : {
        "serialNumber": "device1SN"
      }
    },
    {
      "version" : "4-0-0",
      "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-0",
      "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-0",
      "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-0",
     "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-0",
     "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-0",
      "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-0",
      "device": {
        "serialNumber": "device1SN",
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
        "AzzTpz4M7Xllx3mFmbVLLxliAW+iFvA6MyfAZ4louNMli+GMvVIrlajrCwmPF6NtoE9nAOhjIYKr3GH6T+3OyR0DHhD5S6pia7aQy6/WiErToBnsQfvXIonG"
        ]
      }
    }
  ]
}

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

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"device" : {} object.

Example

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

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-0",
      "device": {
        "radios": {
          "bleMeshUUIDs": [
            "6a2f41a3-c54c-fce8-32d2-0324e1c32e22"
          ]
        },
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
        "AzzTpz4M7Xllx3mFmbVLLxliAW+iFvA6MyfAZ4louNMli+GMvVIrlajrCw"
        ]
      }
    },
    {
      "version": "4-0-0",
      "device": {
        "radios": {
          "bleMeshUUIDs": [
            "6a2f41a3-c54c-fce8-32d2-0324e1c32e33"
          ]
        },
        "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "bleMeshOBDData": [
        "AzzTpz4M7Xllx3mFmbVLLxliAW+iFvA6MyfAZ4louNMli+GMvVIrlajrCwx"
        ]
      }
    }
  ]
}

Bundle Control Log

    {
      "controlLogs": [
        {
          "version": "5-0-0",
          "bundleSerialNumber": "ABCDE",
          "devices": [
            {
              "productInstanceIdentifier" {
                "bleMeshUUID": "6a2f41a3-c54c-fce8-32d2-0324e1c32e32"
              },
              "productIdentifier": {
                "advertisedProductId": "abCD"
              }
            },
            {
              "productInstanceIdentifier" {
                "bleMeshUUID": "6a2f41a3-c54c-fce8-32d2-0324e1c32e33"
              },
              "productIdentifier": {
                "advertisedProductId": "abCD"
              }
            }
          ]
        }
      ]
    }

Device Control Log Schema Definition

{
  "$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."
                }
              }
            }
          }
        }
      }
    }
  }
}

Bundle Control Log Schema Definition

{
  "$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.
       

Last updated: Nov 29, 2020