AWS IoT Jobs library demo

Important

This demo is hosted on the Amazon-FreeRTOS repository which is deprecated. We recommend that you start here when you create a new project. If you already have an existing FreeRTOS project based on the now deprecated Amazon-FreeRTOS repository, see the Amazon-FreeRTOS Github Repository Migration Guide.

Introduction

The AWS IoT Jobs library demo shows you how to connect to the AWS IoT Jobs service through an MQTT connection, retrieve a job from AWS IoT, and process it on a device. The AWS IoT Jobs demo project uses the FreeRTOS Windows port, so it can be built and evaluated with the Visual Studio Community version on Windows. No microcontroller hardware is needed. The demo establishes a secure connection to the AWS IoT MQTT broker using TLS in the same manner as the coreMQTT mutual authentication demo.

Note

To set up and run the FreeRTOS demos, follow the steps in Getting Started with FreeRTOS.

Source code organization

The demo code is in the jobs_demo.c file and can be found on the GitHub website or in the freertos/demos/jobs_for_aws/ directory.

Configure the AWS IoT MQTT broker connection

In this demo, you use an MQTT connection to the AWS IoT MQTT broker. This connection is configured in the same way as the coreMQTT mutual authentication demo.

Functionality

The demo shows the workflow used to receive jobs from AWS IoT and process them on a device. The demo is interactive and requires you to create jobs by using either the AWS IoT console or the AWS Command Line Interface (AWS CLI). For more information about creating a job, see create-job in the AWS CLI Command Reference. The demo requires the job document to have an action key set to print to print a message to the console.

See the following format for this job document.

{
    "action": "print",
    "message": "ADD_MESSAGE_HERE"
} 

You can use the AWS CLI to create a job as in the following example command.

aws iot create-job \
    --job-id t12 \
    --targets arn:aws:iot:region:123456789012:thing/device1 \
    --document '{"action":"print","message":"hello world!"}'
        

The demo also uses a job document that has the action key set to publish to republish the message to a topic. See the following format for this job document.

{
    "action": "publish",
    "message": "ADD_MESSAGE_HERE",
    "topic": "topic/name/here"
}

The demo loops until it receives a job document with the action key set to exit to exit the demo. The format for the job document is as follows.

{
    "action: "exit"
} 

Entry point of the Jobs demo

The source code for the Jobs demo entry point function can be found on GitHub. This function performs the following operations:

1. Establish an MQTT connection using the helper functions in mqtt_demo_helpers.c.

2. Subscribe to the MQTT topic for the NextJobExecutionChanged API, using helper functions in mqtt_demo_helpers.c. The topic string is assembled earlier, using macros defined by the AWS IoT Jobs library.

3. Publish to the MQTT topic for the StartNextPendingJobExecution API, using helper functions in mqtt_demo_helpers.c. The topic string is assembled earlier, using macros defined by the AWS IoT Jobs library.

4. Repeatedly call MQTT_ProcessLoop to receive incoming messages which are handed to prvEventCallback for processing.

5. After the demo receives the exit action, unsubscribe from the MQTT topic and disconnect, using the helper functions in the mqtt_demo_helpers.c file.

Callback for received MQTT messages

The prvEventCallback function calls Jobs_MatchTopic from the AWS IoT Jobs library to classify the incoming MQTT message. If the message type corresponds to a new job, prvNextJobHandler() is called.

The prvNextJobHandler function, and the functions it calls, parse the job document from the JSON-formatted message, and run the action specified by the job. Of particular interest is the prvSendUpdateForJob function.

Send an update for a running job

The function prvSendUpdateForJob() calls Jobs_Update() from the Jobs library to populate the topic string used in the MQTT publish operation that immediately follows.