Quality RTOS & Embedded Software

LIBRARIES
WHAT'S NEW
FreeRTOS:
AWS Reference Integrations:
FreeRTOS SMP:
Embedded World track keynote:
NOTE: The AWS IoT Device Defender library is now available with preconfigured examples in the main FreeRTOS download and 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 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+TCP TCP/IP stack, so follow the instructions provided for the TCP/IP starter project to:

  1. Install the pre-requisite components (such as WinPCap).
  2. Optionally set a static or dynamic IP address, gateway address and netmask.
  3. Optionally set a MAC address.
  4. 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:

  1. 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.
  2. 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 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 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 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 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 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 on GitHub.

Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.