Skip to main content Link Menu Expand (external link) Document Search Copy Copied

Constructing and uploading Sidewalk control logs

The control logs can be constructed from the output of the signing tool with some additional information. The logs can then be consolidated, in case there are multiple devices, and then uploaded to Amazon Sidewalk.

Important
The steps in this section need to be performed only by the contract manufacturer (CM). You don’t have to take any action. This section describes how the signing tools can generate and consolidate the control logs, and how it can be uploaded to Amazon Sidewalk for provisioning your Sidewalk devices.

The following steps show how to construct and upload your control logs.

Topics

Step 1: Construct control logs

If you’re using the control log version 4-0-1, the signing tool can generate the control logs file using a format that can be ingested into WCL using Amazon’s electronic data interchange (EDI) system or SFTP endpoints.

To generate the control logs and specify the directory where the logs will be generated, use the parameter --control_log_dir when running the Sidewalk signing tool. For more information and how to run the tool, see Sidewalk signing tool parameters

The signing tool will generate a WCL file for the device in the specified directory, with a name C_CONTROL_LOG_<date and time in yyyyMMddhhmmss format>.txt. The control logs generated will use a format that complies with the version 4-0-1 and contains the required device information to be uploaded to Amazon Sidewalk, such as the SMSN, APID, and the Sidewalk certificate chains. For more information, see the control logs specification section.

In this code, the serialNumber and the certificate chains sidewalkED25519CertificateChain and sidewalkP256R1CertificateChain are obtained by running the Sidewalk signing tool. You obtain the APID when creating a Sidewalk profile.

{
  "controlLogs" : [
    {
      "version" : "4-0-1",
      "device" : {
        "serialNumber": "device1SN",                                     
        "productIdentifier": {
          "advertisedProductId": "GZBd"                                  
        },
        "sidewalkData": {
          "sidewalkED25519CertificateChain": "ZfZFVIghs+3EJrr...qRB+Aw==", 
          "sidewalkP256R1CertificateChain": "ZfZFVIghs+3EJrr...BZ1Bw==",   
          "label": "PRODUCTION / PREPRODUCTION"
        }
      }
    }
  ]
}

Step 2: Consolidate control logs

The control log file generated by the Sidewalk signing tool contains the control log information only for a single Sidewalk device as the certificates are signed only for a single device at a time. If you have multiple Sidewalk devices, their control logs can be consolidated into a single control log file for WCL ingestion. To consolidate the control logs, use the tool consolidate_cl.py provided by the Sidewalk signing tool.

For example, the following command shows how to run this tool. You can move all the control logs to be consolidated into a single directory and then run the tool from that directory.

python3 consolidate_cl.py /tmp/cl/C_CONTROL_LOG_*.txt

In this example, the command reads all control log files that are in the /tmp/cl directory. After the tool runs successfully, it generates a new control log file, for example C_CONTROL_LOG_20221021155511.txt, that will contain the control log content of its inputs in the directory.

Processing /tmp/cl/C_CONTROL_LOG_20221018122452.txt
Processing /tmp/cl/C_CONTROL_LOG_20221018141057.txt
Processing /tmp/cl/C_CONTROL_LOG_20221018141105.txt
Processing /tmp/cl/C_CONTROL_LOG_20221018141106.txt
Processing /tmp/cl/C_CONTROL_LOG_20221018141108.txt
Processing /tmp/cl/C_CONTROL_LOG_20221018141109.txt
Processing /tmp/cl/C_CONTROL_LOG_20221018141110.txt

...


C_CONTROL_LOG_20221021155511.txt

The consolidated control log file will contain the required information for multiple devices. The following code shows a sample control log file.

{
  "controlLogs" : [
    {
      "version" : "4-0-1",
      "device" : {
        "serialNumber": "device1SN",
         "productIdentifier": {
          "advertisedProductId": "abCD"
        },
        "sidewalkData": {
          "sidewalkED25519CertificateChain": "ZfZFVIghs+3EJrr...qRB+Aw==",
          "sidewalkP256R1CertificateChain": "ZfZFVIghs+3EJrr...BZ1Bw==",
          "label": "PRODUCTION / PREPRODUCTION"
        }
      }
    },
    {
      "version" : "4-0-1",
      "device" : {
        "serialNumber": "device2SN",
        "productIdentifier": {
          "advertisedProductId": "CfnC"
        },
        "sidewalkData": {
          "sidewalkED25519CertificateChain": "3OJknQsyH949Ism...qRB+Aw==",
          "sidewalkP256R1CertificateChain": "3OJknQsyH949Ism...BZ1Bw==",
          "label": "PRODUCTION / PREPRODUCTION"
        }
      }
    }
  ]
}

Step 3: Upload control logs

After you’ve provisioned your Sidewalk device, you must upload the control logs file to Amazon Sidewalk that includes information about the provisioned device. This information includes the device identifier, APID, SMSN, and Sidewalk certificate chain.

To upload your control logs, use either of the following approaches:

Topics

Upload control logs using EDI

After a contract manufacturer (CM) has been issued a YubiHSM key, the CM must set up the factory line to provision devices using the Sidewalk certificates. For your Sidewalk devices to connect to the cloud and use other AWS services, the control logs must be uploaded to Amazon.

For information about uploading the control logs using Amazon’s electronic data interchange (EDI) system, contact Amazon Sidewalk support.

Upload control logs using SFTP endpoint

To upload the control logs using an SFTP endpoint, perform the following steps.

  1. Sign in to your developer account and go to the Frustration-Free Setup (FFS) developer console.

  2. Go to the Control Logs section of the FFS developer console and choose Manage Control Logs.

  3. Enter information about the business you want to onboard, which includes the Company Name, Contact name, Group Email, and Contact phone. Choose Onboard.
    [Image NOT FOUND]

  4. Generate a secure RSA key and upload the public key on the portal.

    1. To generate the RSA key, run the following command.

      ssh-keygen -t rsa -b 2048 -m PEM

    2. Enter the file in which to save the key and the passphrase when prompted.

      Running this command generates two files --control_log_key and --control_log_key.pub.

    3. Upload the public key --control_log_key.pub on the portal by choosing Choose file and then choose Create.

      A pair of SFTP endpoints will be generated for sending the control logs and for receiving feedback.

The Upload endpoint is for sending control log to Amazon, and the Feedback endpoint is for receiving responses from Amazon about the uploaded control log.

  1. Choose the control log file that you want to upload. This example uses the control log file that was created in Step 2: Consolidate control logs.
  {
    "controlLogs": [
      {
        "version": "4-0-1",
        "device": {
          "serialNumber": "418A07E3811B8CED614BD27BD2445FAE50A7376A3EB9993CA2017F497A87A68F",
          "productIdentifier": {
            "advertisedProductId": "vLpm"
          },
          "sidewalkData": {
            "sidewalkP256R1CertificateChain": "QYoH44EbjO1hS9J70kRfrlCnN2o+uZk8ogF/SXqHpo+brYZmMkXBv4uRdqlI76h2lDlwFRPtDaKCNx4wnbtLxPy50i1v7R/HKlftXYYqHd5F031Ul60gCiUBFilD+bGz5bAEuktyV+IiO37OMwj4ctUmMI9qL+3YqrPWbt8re0OPihdvppJG1pRwn/uoEJy7jHKmyncRzUP3vN/TE1pNiQEOAPq8LXwuG1NtZ73FcCVFL2BGLV+aBWwX5QW768cujyO2LjP3dEc0QmOiESr4IpoZ8hzeOgXdRU5khPpOxyD4z60/96exsJUmbByDi3jSg1rpOO+sp0jiTemYs1xzSRyXJ1omEv4R0GiTZ6Np1wB7P+PgtFeHtXosMKBPtQvBXzoiOADXAHgCh5Bb/CJT2V3tUA2Sc4swmGggv2KHa/44s4hHtYURlomTw4DTS9WhHjG2Bx2O5jpDuXnzgP2ogf46KwA3o8bczrhzh+kAOgJ7Qu2VY9uupDkvQF63zPDwRiEObHe+hSdDYPccf+ZVJiXOv1Xdd0H2g/efg7hZnxlCKib8//mR1wDPAHyVtZg7AK5NSfOcL6JTw58K0LyK4n8FmpQuRkkqLBRpjbP0sf4Yr26FQxYcjDPnEG4bDw9oMJw0vmRNv8Zc0f5WQxPoqrq/7tQM2UnCF7IFd2pqsCH/QgCM9tD5NgOakB5NUKmxBkkiv8G9n4gZCLRsFS47GAbAfubjcGHgJmBQtnUAAALPsP34BS6EzJO5AsS5pC7QTpjBtAbLN9SdXOT9w4H1x8Nkp0ujLxWRN37IEy0V9DrPK2w1g74uqWPfUPnSBjtvM55JnQpmm23WQNvHa1Vr6zmWDjzjHpcNirPbzXyBlKEhkX4xylaSMnm4UrVXtAMaAJ/csC4HPTKr3dazdvEkhwGAAAIFByCjSp/5WHc4AhsyjMvKCsZQiKgiI8ECwjfXBaSZdY4zYsRlO3FC428H1atrFChFCZT0Bqt5LPXD38bMSB+vAUJiP8XqiEdXeqf2mYMJ5ykoDpwkve/cUQfPpjzFQlQfvwjBwiJDANKkOKoNT3bUGz+/f/pyTE+xMRdIUBZ1Bw==",
            "sidewalkED25519CertificateChain": "QYoH44EbjO1hS9J70kRfrlCnN2o+uZk8ogF/SXqHpo+vSnWG/O1S3JGmJI05w5WzKzoc2qsxIoWXOYnD+O4nfSrWb5tPENmKqXrvEVCwb3ctGyAdh7l7IqB+5MJFYNuoHBGM7E5vas/bdB9K8wc5PJmM981pSzSAdD7Gxwh0QAMBDQD6ztjDszbA7PExBCnaTDCxiasDIB+zbDHbXHDLg/BuUwlKyiAHZuVhTcsHhJZ2I+ZriyKiVw94cygt3Ho6Rq3Q2p4vmKJc5+BY6QkiywGDi5GvL1qkaJtRI1HZwt55i9sDANgAeLEEIQOLF30faw/kYhUbbNcEkiVD5LhGgrm7IxWzhyhvQW2jbSvlKddKgFD+B4Ko/aJzmusXOMcMty09XFXVysUEGJngunFMQu5A26SF04J5+SsEkZidAAdzvVjYH24FBADQAHyZnTAM5V/SciHcAlBTsXb5lXKnnTbl+8rxt5KwdsfKdEfyUbpASLiBH53wm+UHJ1+4nrzQ1B0pPeDkY+hapWp7jXRwd4FZFJhQgOMpW/A2RR/m7HMJZCMKgeSeO+c3hgx1AAADGz+gFBeX/ZNN8VJwnsNfgzj4me1HgVJdUo4W9kvx9cr2jHWkC3Oj/bdBTh1+yBjOC53yHlQK/l1GHrEWiWPPnE434LRxnWkwr8EHD4oieJxC8fkIxkQfj+gHhU79Z+oAAYAAAzsnf9SDIZPoDXF0TdC9POqTgld0oXDl2XPaVD4CvvLearrOSlFv+lsNbC4rgZn23MtIBM/7YQmJwmQ+FXRup6Tkubg1hpz04J/09dxg8UiZmntHiUr1GfkTOFMYqRB+Aw=="
          }
        }
      },
  
      {},    
      ...
    ]
  }

  1. To upload the control logs, perform the following steps.

    1. First start the SFTP endpoint.

      sftp --oIdentityFile={path_to_key_file}/control_log_key \ 
    --oHostKeyAlgorithms=+ssh-dss sftp://{upload_endpoint}/To_Amazon

    2. Next upload the control log file to the endpoint.

      # Display local directory listing.
sftp> lls
       
# Upload control log file name.
sftp> put <local_path>/<control_log_filename>
       
# Exit out of the SFTP connection.
sftp> exit

    It takes few minutes for the control log to be processed and feedback to be received. Once completed, an email will be sent to the email address provided in the onboarding phase in step 3 where you specified the onboarding business information for control logs.

Next steps

Now that the control log has been sent via email, the third party user can use AWS IoT Core for Amazon Sidewalk to provision these devices to AWS IoT in bulk.

The user can open the email received and download the CSV file attached to the email. The CSV file summarizes the control log upload status, as shown below. This file will be used to provision the Sidewalk devices in bulk using AWS IoT Core for Amazon Sidewalk. For more information, see Bulk provisioning devices with AWS IoT Core for Amazon Sidewalk in the AWS IoT Core developer guide.

[Image NOT FOUND]

Back to top

©2023 Amazon.com, Inc. or its affiliates (collectively, “Amazon”). All Rights Reserved.