View a markdown version of this page

Amazon IoT Jobs library demo - FreeRTOS
IntroductionSource code organizationConfigure the Amazon IoT MQTT broker connectionFunctionality
Services or capabilities described in Amazon Web Services documentation might vary by Region. To see the differences applicable to the China Regions, see Getting Started with Amazon Web Services in China (PDF).

Amazon IoT Jobs library demo

Important

This is an archived version of the FreeRTOS User Guide for use with FreeRTOS release 202012.00. For the latest version of this document, see the FreeRTOS User Guide.

Introduction

The Amazon IoT Jobs library demo shows you how to connect to the Amazon IoT Jobs service through an MQTT connection, retrieve a job from Amazon IoT, and process it on a device. The Amazon 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 Amazon IoT MQTT broker using TLS in the same manner as the MQTT 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 Amazon IoT MQTT broker connection

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

Functionality

The demo shows the workflow used to receive jobs from Amazon IoT and process them on a device. The demo is interactive and requires you to create jobs by using either the Amazon IoT console or the Amazon Command Line Interface (Amazon CLI). For more information about creating a job, see create-job in the Amazon 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 Amazon CLI to create a job as in the following example command.


aws iot create-job \
    --job-id t12 \
    --targets arn:aws-cn: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 Amazon 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 Amazon 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 Amazon 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.