The Internet of Things on AWS – Official Blog

Schedule remote operations using AWS IoT Device Management Jobs

Introduction

Once Internet of Things (IoT) devices are deployed in the field, on-site intervention can be challenging, expensive, and may not be feasible due to technical and logistical constraints. The ability to perform remote updates on your IoT device software is an important factor that improves your IoT application’s lifespan and operational resilience, provisions the latest functionality, addresses bug fixes, and reduces security risks. AWS IoT Device Management is a fully managed service that helps you register, organize, monitor, and remotely manage IoT devices at scale. Developers are using AWS IoT Device Management Jobs to perform remote actions (e.g., firmware updates, device reboots, factory resets, etc.) on devices that are connected to AWS IoT Core.

A “job” is a set of operations defined in the cloud and sent to and ran on one or more devices, while a job execution is an instance of such a remote action on a targeted device. For example, developers can define a single job that performs an “Over-The-Air” (OTA) update on 1000 devices, which then executes 1000 job executions to update each individual device. In many situations, developers need a mechanism to control the time window during which jobs are active and running, such as a start and end time configurable parameter, as well as the ability to cancel job executions upon reaching an end time, to stop rolling out remaining executions which were not started. Examples of use cases where this is needed are:

  • IoT devices are performing sensitive operations in a factory, such as controlling industrial equipment, and must be updated on schedules,
  • IoT devices provide consumer services, such as internet connectivity in homes, and should only be upgraded during periods of idleness,
  • IoT devices operate under strict availability Service Level Agreements (SLAs), where remote operations must be performed only during defined time windows to reduce operational disruptions.

This blog post provides guidance for developers looking to schedule rollouts of jobs, using AWS IoT Device Management Jobs scheduling feature.

Metadata

Learning level: 300
Services used: AWS IoT Device Management, AWS IoT Core, AWS IoT Device Client.

Prerequisites

To be able to run through the steps in this blog, you will need:

  1. An AWS account and permissions to provision IoT things, and use AWS IoT Device Management features.
  2. To run the steps in this blog, access to AWS IoT Device Client with its Jobs feature, as the open source software running on a simulated IoT device, is needed. In production, you can continue using your existing on device set-up.
  3. An application to interact with your operating system command line interface (e.g.: Terminal on Mac OS, or Powershell on Windows).
  4. AWS Command Line Interface (CLI) installed. Refer to AWS CLI Documentation for instructions on how to install and configure AWS CLI.
  5. An AWS Identity and Access Management (IAM) user with the credentials for creating AWS resources through CLI.

Schedule AWS IoT Job rollouts – walkthrough

Step 1: Create an IoT thing and configure the AWS IoT Device Client

To get started with creating the IoT thing and setting up AWS IoT Device Client, you can follow part 1, 2 and 3 from the Getting started workshop. Name your IoT thing demoDevice . After performing these steps, you should have AWS IoT Device Client with the Jobs feature enabled and running, and your IoT thing created with the correct policy in place.

Step 2: Create the AWS IoT Job from an AWS managed template

We will be creating a job to reboot the device at a provided start time, using the AWS managed template AWS-Reboot.

In the scheduling configuration of the job, you can specify the start time, end time, as well as the end behavior for all job executions after a job reaches the selected end time. As an end behavior, you can specify what should happen to the remaining job executions, including retry attempts and queued jobs, when the end time is reached. The requirements for the start time, end time, and end behavior can be found here.

Note that the start time and end time must be passed into the CLI command as Coordinated Universal Time (UTC) strings. Additionally, you need to make sure that the start time is scheduled a minimum of thirty minutes from the current time.

To create the job, you can use the AWS CLI, and run the following commands:

1. Create the required environment variables:

export ACCOUNT_ID=<Replace with your account ID>
export THING_NAME=<Replace with your thing name>
export REGION =<Replace with your region>
export JOB_ID =<Replace with your job ID>
export START_TIME =<Replace with your desired start time>

2. Run the command below to create an IoT job:

 aws iot create-job \
 --targets arn:aws:iot:${REGION}:${ACCOUNT_ID}:thing/${THING_NAME} \
 --job-id ${JOB_ID} \
 --job-template-arn arn:aws:iot:${REGION}::jobtemplate/AWS-Reboot:1.0 \
 --document-parameters pathToHandler=/etc/.aws-iot-device-client/jobs \
 --scheduling-config startTime=${START_TIME}

3. Verify the AWS CLI output. It should look like below:

{ "jobArn": "arn:aws:iot:${REGION}:${ACCOUNT_ID}:job/reboot-scheduled-job", "jobId": "${JOB_ID}", "description": "A managed job template for rebooting the device." }

Step 3: Verify scheduled job creation in AWS IoT Console

To verify the scheduled job creation, do the following:

1. In the AWS IoT Console, in the left menu, choose Manage-> Remote actions-> Jobs, and ensure that your job that has been created.

2. You should check that the “Job status” is Scheduled, and that the estimated start time is correct. The time zone displayed in the AWS Management Console is your current system time zone.

IoT Jobs Scheduled Job

3. Once the start time is reached, you should see that the job changes to IN PROGRESS.

Step 4: Check the AWS IoT Device Client logs for job execution feedback

Once the start time is reached, the next step is to tail the logs of the AWS IoT Device Client, for successful job execution. The standard location of the log is in /var/log/aws-iot-device-client/aws-iot-device-client.log. If you modified the log location configuration, please use your location.

For a successful job execution, the log should look similar to the one below.

Step 5: Cleaning Up

To avoid further costs, you should clean up the used resources:

1. Follow the clean up steps from the Getting started workshop, to remove only the resources you created in Step 1.

2. You should delete the created IoT job. You can use the following AWS CLI command to delete the job:

aws iot delete-job —job-id ${JOB_ID}

Conclusion

Once IoT devices are in the field, you can use AWS IoT Device Management Jobs feature to remotely manage your device’s operation and schedule critical updates. Performing such operations could be restricted to pre-defined time windows, to reduce disruptions in normal usage, or comply with down-time SLAs commitments in your customer agreement. In this blog post, you have learnt how to schedule AWS IoT Jobs executions from the cloud using the Jobs Scheduling configuration and the AWS IoT Device Client, without the need to modify any of the on-device behavior.

About the Authors

Alina Dima is a Senior Developer Advocate, in the AWS IoT Global Advocacy team, at Amazon Web Services. She is passionate about helping developers accelerate their journeys in the IoT ecosystem, and working with IoT communities to build better and move faster, from prototype to scale. Alina has worked in various industries such as telecommunications, manufacturing, automotive, retail, and photovoltaic. With nearly 20 years of experience as a software engineer, technical delivery manager and architect, she has designed and built multiple highly scalable, operationally ready IoT solutions, with millions of devices running in production today.
Chelsea Pan is a Sr. Product Manager at Amazon Web Services and is based in Seattle. She oversees the AWS IoT Device Management services on product strategy, roadmap planning, business analysis and insights, customer engagement, and other product management areas. Chelsea led the launch of several fast-growing security products in her career.