Device-Jobs

AWS IoT Jobs

AWS IoT (AWS) Jobs service offered by AWS that lets you perform remote operations on a device. The benefit of using this service is you can target more than one device to perform same remote operation. The most common use case is performing Over-The-Air (OTA) firmware updates and you can also use it to perform tasks such as restarting a device.

You have to first define a set of remote operations and implement them on device side. This library handles communication with AWS Jobs service and callbacks a handler to execute the operation.

Here we have summarised how to handle jobs using this library. You can read the official documentation on Jobs to understand it better.

• When you create Job, you specify a job document and select target device.
• Once the job is created on AWS the device will be notified. On receiving the notification the device will fetch the job document, parse it, and perform the operation. The device can update the job status as it progresses gradually.
• A Job status can be one of the following:

  Status	Description
  Accepted	The device has accepted the Job.
  Rejected	The device has rejected the Job for some reason.
  In Progress	The device is performing the operation.
  Failed	The job was accepted, but failed due to execute successfully some reason.
  Successful	The job was accepted and completed successfully.

Job document

You need to attach a job document while you create a job. The job document is a JSON representation that describes the remote operation for a target device.

This is a sample job document that describes blink operation, and it specifies to blink 3 times using a count value.

{
    "action": "blink",
    "count": 3, 
    "onTime": 250,
    "offTime": 500
}

Note: The action key-value pair is necessary in the Job document, without it the library will not be able to handle jobs.

To use AWS Job service, you will also need to use AWS S3 bucket to store job documents. After creating your job document, upload it to your S3 bucket. When creating a new job you should pick the job document from this bucket.

Read the official documentation on Managing jobs here for creating a new job.

Implementation steps

To simplify things further we have broken down the process in a sequence to give you an overview.

1. Define the remote operation using job document.
2. Device side: implement remote (job) operation.
3. AWS side: upload job document and create the job.

Let's see an example of a job that will blink an LED 3 times.

Define remote operation using job document

On your computer, create a text file and copy-paste the contents of the job document shown below. You can give any name to your file, here we will name it as blink_jobDocument.txt

{
    "action": "blink",
    "count": 3, 
    "onTime": 250,
    "offTime": 500
}

Note: Keep this file aside for now. We will upload it to S3 bucket when creating a job.

Device Side: Implement remote operation

The steps below explains the necessary configuration and initialization required on device side to handle jobs. Ensure your device is provisioned with certificates otherwise you have to manually configure the device certificates.

1. Implement the job operation

Define blink_led function.

bool job_received = false;
char job_id[LENGTH_JOB_ID] = {0};
char job_document[LENGTH_JOB_DOCUMENT] = {0};
 
jobsStatus_et blink_led(job_st *ps_job)
{
    print_info("%s : %s", ps_job->idStr, ps_job->documentStr);
 
    // copy job_id & job_document
    strcpy(job_id, ps_job->idStr);
    strcpy(job_document, ps_job->documentStr);
 
    // handle the operation in application task
    job_received = true;
    
    return JOB_STATUS_IN_PROGRESS;
}

2. Initialize the system configuration

Please refer to step #1 of Publish-Subscribe user guide to use thing certificates.

If you want to use other two methods then please read the Provisioning methods of Lib AWS under Overview section and configure the system configuration variable of type systemInitConfig_st.

3. Connect to AWS

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

bool systemInitSuccess = SYSTEM_init(&s_sysConfig);

4. Register job operation

Register the job operation function as callback handler.

if (systemInitSuccess)
{
    SYSTEM_start();
    
    JOBS_register("blink", 0, blink_led);
}

5. Implement application logic

char countStr[4] = {0};
uint32_t countValue = 0;
 
// job received? perform operation
if (job_received)
{
    // variable for extracting json key-value pair
    tagStructure_st countKeyValuePair[1] = {
        {"count", countStr}
    };
 
    // parse job document to initialize count value
    if (JSON_processString(job_document, countKeyValuePair, 1))
    {
        countValue = util_getNumFromString(countStr);
 
        print_info("blink %d times\r\n", countValue);
 
        if (countValue > 0)
        {
            // blink 3 times
            for(uint8_t i=0; i<countValue; i++)
            {
                GPIO_pinWrite(LED_PIN, 1);
                TASK_DELAY_MS(500);
                GPIO_pinWrite(LED_PIN, 0);
                TASK_DELAY_MS(500);
            }
 
            JOBS_updateStatus(job_id, JOB_STATUS_SUCCESSED);
        }
    }
 
    job_received = false;
}

6. Create application task

void app_task(void *param)
{
    while (1)
    {
        switch (SYSTEM_getMode())
        {
        case SYSTEM_MODE_NORMAL:
            if (AWS_isConnected())
            {
                // job received? perform operation
            }
            break;
 
        default:
            break;
        }
 
        TASK_DELAY_MS(100);
    }
}
 
TaskHandle_t tHandle_appTask = NULL;
 
xTaskCreate(&app_task, "app_task", 1024, NULL, 4, &tHandle_appTask);

AWS Side: upload job document and create the job

1. Upload the blink_jobDocument.txt file on your S3 bucket. After uploading the file, ensure that the file can be downloaded using web browser on your computer.
2. Create a Custom Job. Follow the instructions as described here in the official documentation.