NOTE: The AWS IoT Device Defender library is now available with preconfigured
examples in the main
FreeRTOS download and in the
FreeRTOS repository on GitHub.
AWS IoT Device Defender Demo
Introduction
The AWS IoT Device Defender Demo shows you how to interact with the
AWS IoT Device Defender
service through an MQTT connection, submit a device defender report including custom metrics, and verify that the report was accepted.
The AWS IoT Device Defender 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 required to run this demo. This demo establishes a mutually authenticated secure connection to the AWS IoT
MQTT broker using TLS.
Source Code Organization
The demo project is called defender_demo.sln
and can be found in the Device_Defender_Demo repository on GitHub in the following directory:
FreeRTOS-Plus/Demo/AWS/Device_Defender_Windows_Simulator/Device_Defender_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 file FreeRTOSConfig.h
in the Device Defender 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 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/Device_Defender_Windows_Simulator/Device_Defender_Demo/defender_demo.sln
from within the Visual Studio IDE.
- Select build solution from the IDE's build menu.
Functionality
This demo shows you how to construct a device defender report and publish it from a device to the AWS IoT Device Defender Service.
The demo connects to the AWS IoT broker, collects networking and custom metrics from the device, constructs
a JSON report using the collected metrics, and publishes the report. The structure of the demo is shown in the following sections.
The source code for the prvDefenderDemoTask()
function can be found in the
DefenderDemoExample.c file on Github.
This screenshot shows the expected output when the demo executes correctly:
Click to enlarge
Subscribing to Defender Topics
The function prvSubscribeToDefenderTopics()
subscribes to MQTT topics to receive a response when:
- A device defender report it has published is accepted.
The macro DEFENDER_API_JSON_ACCEPTED
is used to construct the topic string.
- A device defender report it has published is rejected.
The macro DEFENDER_API_JSON_REJECTED
is used to construct the topic string.
The source code for the prvSubscribeToDefenderTopics()
function can be found in the
DefenderDemoExample.c file on
GitHub.
Collecting Device Metrics
The function prvCollectDeviceMetrics()
gathers networking metrics, using the functions defined in
metrics_collector.h
, as well as custom metrics. The networking metrics collected are:
- the number of bytes and packets sent and received
- the open TCP ports
- the open UDP ports
- the established TCP connections
The custom metrics collected are:
- the stack high water mark (with type number)
- the device’s task ids (with type number list)
The source code for the prvCollectDeviceMetrics()
function can be found in the
DefenderDemoExample.c file on
GitHub.
Generating the Device Defender Report
The function prvGenerateDeviceMetricsReport()
generates a device defender report. It is defined in
report_builder.h
. The function takes the networking metrics and a buffer as input, creates a JSON
document in the format expected by the AWS IoT Device Defender Service, and writes it to the specified buffer.
The format of the JSON document that the AWS IoT Device Defender Service expects is specified
here.
The source code for the prvGenerateDeviceMetricsReport()
function can be found in the
DefenderDemoExample.c file on
GitHub.
Publishing the Device Defender Report
The function prvPublishDeviceMetricsReport()
publishes the device defender report on the
appropriate MQTT topic. The report is constructed, in JSON, using the macro DEFENDER_API_JSON_PUBLISH
.
The source code for the prvPublishDeviceMetricsReport()
function can be found in the
DefenderDemoExample.c file on
GitHub.
Callback for Handling Responses
The function prvPublishCallback()
handles incoming MQTT messages. It uses the
Defender_MatchTopic
API from the Device Defender library to check if the incoming MQTT message is from
the AWS IoT Device Defender service. If the message is from the service, it parses the received JSON response and
extracts the report ID. Then it verifies that the report ID is the same as the one sent in the device defender report.
The source code for the prvPublishCallback()
function can be found in the
DefenderDemoExample.c file on
GitHub.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.