AWS IoT Jobs Library Demo
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
free Community
version of Visual Studio 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
MQTT mutual authentication demo.
Source Code Organization
The demo project is called jobs_demo.sln
and can be found in the
FreeRTOS-Plus Jobs_Demo repository on GitHub in the following directory:
FreeRTOS-Plus\Demo\AWS\Jobs_Windows_Simulator\Jobs_Demo
Configure the Demo Project
The demo uses the FreeRTOS-Plus-TCP TCP/IP stack, so follow
the instructions provided for the
TCP/IP starter
project to:
- Install
the pre-requisite components (such as WinPCap).
- Optionally
set a static or dynamic IP address, gateway address and netmask.
- Optionally
set a MAC address.
-
Select an Ethernet network interface on your host machine.
The above settings should be changed in the Jobs demo project.
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 in the MQTT mutual authentication demo.
Build the Demo Project
The demo project uses the free community edition of Visual Studio. To build the demo:
- Open the Visual Studio solution file
FreeRTOS-Plus/Demo/AWS/Jobs_Windows_Simulator/Jobs_Demo/jobs_demo.sln
from within the Visual Studio IDE.
- Select build solution from the IDE's build menu.
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 using either the AWS IoT console or the AWS CLI. See
create-job in the AWS CLI Command Reference for more information about creating a job. The demo
requires the job document to have an "action" key set to "print" to print a message to the console. The format for this job document is as follows:
{
"action": "print",
"message": "INSERT_MESSAGE_HERE"
}
Using the AWS CLI, a job can be created as follows (command prompt):
aws iot create-job \
--job-id 12383 \
--targets arn:aws:iot:us-east-1:1234567890:thing/device1 \
--document "{\"action\":\"print\",\"message\":\"hello world!\"}"
The arguments used above are examples only.
The demo also uses a job document that has the "action" key set to "publish"
to republish the message to a topic. The format for the job document is as follows:
{
"action": "publish",
"message": "INSERT_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 in
JobsDemoExample.c on GitHub. This function performs the following operations:
- Establish an MQTT connection using the helper functions in
mqtt_demo_helpers.c
.
- 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
Jobs library.)
- 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 Jobs library.)
- Repeatedly call
MQTT_ProcessLoop
to receive incoming messages which are handed to
prvEventCallback
for processing.
- After the demo receives the exit action, unsubscribe from the MQTT topic and disconnect, using the helper
functions in
mqtt_demo_helpers.c
.
Callback for Received MQTT messages
This function calls Jobs_MatchTopic
from the Jobs library to classify the incoming MQTT message.
If the message type corresponds to a new job, prvNextJobHandler
is called.
The function prvNextJobHandler
, and the functions it calls, parse the job document from the
JSON-formatted message, and execute the action specified by the job. Of particular interest is the function
prvSendUpdateForJob
.
The source code for this callback function for incoming messages can be found in JobsDemoExample.c on GitHub.
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.
The source code for the prvSendUpdateForJob
function can be found in JobsDemoExample.c on
GitHub.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.