Integrating the Device Defender Library with the MQTT Agent
Introduction
This example uses the MQTT agent to interact with the AWS IoT Device Defender service by submitting device defender reports, including custom metrics, and verifying that the reports were accepted. The MQTT agent enables the Defender reporting functionality to run in the background and share the MQTT connection with other tasks.
The Device Defender demo code runs as a task in the
same demo project as the
MQTT agent demo and the
OTA demo. Follow the directions on the
MQTT agent demo documentation page in order to obtain and configure the project. To use the Device Defender demo task, configure your project to connect to
AWS IoT Core, and then perform the additional project and AWS account configurations specified on this page.
See the comments at the top of each C file in the Source Directory for additional information.
Instructions
Getting Started
Start by setting up the project as described on the MQTT agent demo documentation page. Be sure to follow all of the steps starting with:
- Learning about the MQTT Agent demo
- Obtaining the source code
- Configuring FreeRTOS-Plus-TCP
- Configuring the MQTT broker
- Configuring the MQTT Agent
Follow the instructions to
connect using the AWS IoT Core MQTT broker and test the connection using one of the simple MQTT tasks. This will ensure connectivity to AWS IoT Core is working correctly before moving on to enabling the Device Defender task.
Once connectivity is working with a non-Defender demo, the following instructions show you how to:
- Set up the custom metrics on your AWS account.
- Configure a security profile to retain submitted reports.
- Enable and run the demo task.
- View the submitted metrics.
Creating custom metrics using the AWS IoT console
As the demo submits custom metrics, the first step is to configure these metrics on the AWS account. The demo uses two custom metrics, named “stack_high_water_mark” (of type number) and “task_numbers” (of type number list). Start by going to the AWS IoT console.
In the navigation pane of the AWS IoT console, choose Defend, Detect, and then Metrics.
Click to enlarge.
Click “Create” in the custom metrics section. Under “Name”, enter “stack_high_water_mark”. Under “Type”, select “number”. Then click “Create custom metric”.
Click to enlarge.
Repeat the prior step, except use “task_numbers” for the name and “number-list” for the type. You should see both metrics as shown below.
Click to enlarge.
Configuring a Security Profile
In order for submitted reports to be retained, a security profile needs to be configured. Start by going to the AWS IoT console.
In the navigation pane of the AWS IoT console, choose Defend, Detect, and then Security Profiles.
Click to enlarge.
Under “Create Security Profile”, select “Create Rule-based anomaly Detect profile”. Enter a name under “Name”. Under the dot menu, click “Delete” to remove the default behavior.
Click to enlarge.
Expand the “Additional Metrics to retain” section, and click the first checkbox in order to select all the metrics. Click next. Then on the Alert targets page, just click “Next”.
Click to enlarge.
On the Attach page, select “All things”, and then click “Next”. Click “Save” on the Confirm page.
Click to enlarge.
Configuring and Running the Demo
In order to run this demo, you'll need to set up your connection to AWS IoT Core. Follow the
configuration steps here, and once you've completed those, perform the following steps:
NOTE: Make sure that democonfigCLIENT_IDENTIFIER was set to the name of your Thing.
- Enable the defender demo task by updating democonfigCREATE_DEFENDER_DEMO to 1.
- Run the demo and let it submit some reports. By default, it sends a report every 30 seconds.
- When a report is successful, the following message will be printed to the console:
The defender report was accepted by the service.
Viewing the metrics on the AWS IoT Console
Once the demo has submitted reports, you can view them to verify they are working as intended. Start by going to the AWS IoT console.
In the navigation pane of the AWS IoT console, choose Manage, and then Things.
Select the Thing created for the demo, and select the “Defender metrics” tab. Here you can select reported metrics, including custom metrics, and view reported values. Reports may take some time to show up.
Click to enlarge.
Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.
