Provisioning

AWS IoT Provision by claim

AWS provides several different ways to provision a device and install unique certificates on it. This library implements Provision by Claim process. You should read this page from the official aws documentation about this process before going any further.

Ensure you that you setup the following on your AWS account before using this library.

1. A policy for the claim certificate
2. Claim certificates with its policy attached
3. A fleet policy, and
4. Provisioning template

While setting up on AWS Side, you would have downloaded the claim certificate files:

1. AWS Root CA certificate.
2. Claim certificate.
3. Claim Private key.

If you haven't set it up yet, then read the "AWS Side" setup from one of our blogpost on this topic here and set it up.

We already have an example project in the aws-iot-examples directory for your reference.

Device side setup

After setting up on AWS Side you should now use our library and let it handle the provsioning by claim process.

1. Initialize the system configuration

You should use claim certificate method of provisioning. You will have to initialize the System configuration and AWS configuration by configuring the following information in the variable of type systemInitConfig_st.

• Your WiFi SSID and Password.
• Your AWS IoT endpoint as hostname, and Port number as 8883.

  Note: You can find your AWS IoT end-point from the AWS IoT Dashboard > Settings using the navigation menu.

• Your Provisioning Template name.
• Your Claim Certificates.
  • Inside the _Certificates/claimCerts folder, copy the thing certificate files. Rename the files respectively as follows.
    1. Rename the AWS Root CA file as aws-root-ca.pem
    2. Rename the Claim certificate file as claim-certificate.pem
    3. Rename the Claim private key file as claim-private.pem.key

Here is the sample code for systemInitConfig_st configuration:

extern const uint8_t aws_root_ca_pem_start[] asm("_binary_aws_root_ca_pem_start");
extern const uint8_t claim_certificate_pem_crt_start[] asm("_binary_claim_certificate_pem_crt_start");
extern const uint8_t claim_private_pem_key_start[] asm("_binary_claim_private_pem_key_start");
 
void app_eventsCallBackHandler(systemEvents_et eventId)
{
    switch (eventId)
    {       
        case EVENT_AWS_CONNECTED:
            print_info("EVENT_AWS_CONNECTED");
            break;
        
        case EVENT_AWS_DISCONNECTED:
            print_info("EVENT_AWS_DISCONNECTED");
            break;
    }
}
 
systemInitConfig_st s_sysConfig = {
    .pDeviceNamePrefixStr = DEVICE_NAME_PREFIX,
    .systemEventCallBack = app_eventsCallBackHandler,
 
    .pWifiSsidStr  = <your wifi ssid>,
    .pWifiPwdStr   = <your wifi password>,
 
    .s_awsConfig  = {
        .pHostNameStr        = <your aws iot endpoint>,
        .port_u16            = 8883,
        .pClaimTemplateStr   = <your provisioning template name>,
 
        .pRootCaStr          = (char *)aws_root_ca_pem_start,
        .pCaimCertStr        = (char *)claim_certificate_pem_crt_start,
        .pClaimPrivateKeyStr = (char *)claim_private_pem_key_start
    }
};

2. Connect to AWS

Using the above configuration initialize the system and connect to AWS.

SYSTEM_init(&s_sysConfig);

3. Check if device is provisioned

After initializing the system the device connects to AWS. If the device is not provisioned it will send the request to generate the thing certificates, downloads and saves it to its internal flash memory.

void app_main()
{
    // configure s_sysConfig variables
 
    // handles provisioning if the device is not provisioned
    bool initSuccess = SYSTEM_init(&s_sysConfig);
 
    if (initSuccess)
    {
        SYSTEM_start();
    }
 
    while(1)
    {
        if (FLASH_isDeviceRegistered())
        {
            printf("Device is already provisioned");
        }
        else
        {
            printf("Device is not provisioned");
        }
 
        vTaskDelay(1000 / portTICK_RATE_MS);
    }
}

4. Flash the application

Erase the entire chip and then flash the application

# erase entire chip
idf.py erase_flash -p <your serial port>
 
# build and flash the application
idf.py flash monitor -p <your serial port>

Note: Don't erase the entire chip when your device is already provisioned or has claim certificates installed.