AWS IoT Device Defender library - FreeRTOS

AWS IoT Device Defender library


AWS IoT Device Defender is an AWS IoT service that enables you to monitor connected devices to detect abnormal behavior and to mitigate security risks. With AWS IoT Device Defender, you can enforce consistent IoT configurations across your AWS IoT device fleet and respond quickly when devices are compromised.

FreeRTOS provides a library that allows your FreeRTOS-based devices to work with AWS IoT Device Defender. You can download FreeRTOS with the Device Defender library from the FreeRTOS Console by adding the Device Defender library to your software configuration. You can also clone the FreeRTOS GitHub repository, which includes all FreeRTOS libraries. See the file for instructions.


The FreeRTOS AWS IoT Device Defender library only supports a subset of the device-side AWS IoT Device Defender metrics related to connection metrics. For more information, see Usage restrictions.

Dependencies and requirements

The Device Defender library has the following dependencies:


FreeRTOS Device Defender error codes

The Device Defender library returns error codes as positive values. For more information about each error code, see AwsIotDefenderError_t in the Device Defender C SDK API Reference.

FreeRTOS Device Defender events

The Device Defender library includes the AwsIotDefenderCallback_t callback function, which returns positive, enumerated values known as "events" that indicate success or failure. For more information about event types, see AwsIotDefenderEventType_t in the Device Defender C SDK API Reference.

Debugging FreeRTOS Device Defender

To enable the debugging for the Device Defender library, set the log level for Device Defender to debug mode in the global configuration file:


For more information, see the Global Configuration File Reference.

Developer support

The Device Defender library includes the AwsIotDefender_strerror helper function, which returns a string that describes the error that you provide to the function:

const char * AwsIotDefender_strerror( AwsIotDefenderError_t error );

Usage restrictions

Although the AWS IoT Device Defender service supports both JSON and CBOR formats for data serialization, the FreeRTOS Device Defender library currently only supports CBOR, which is controlled by the configuration option AWS_IOT_DEFENDER_FORMAT.

Additionally, the FreeRTOS AWS IoT Device Defender library only supports a subset of device-side AWS IoT Device Defender metrics:

Long Name Short Name Parent Element Description
remote_addr rad connections Lists the remote address of a TCP connection.
total t established_connections Lists the number of established TCP connections.

For example:

{ "tcp_connections": { "established_connections": { "connections": [ { "remote_addr": "" }, { "remote_addr": "" } ], "total": 2 } } }

This JSON document is for example purposes only, as FreeRTOS Device Defender library does not support JSON-formatted metrics.


The macro AWS_IOT_SECURE_SOCKETS_METRICS_ENABLED must be defined to enable the secure sockets metrics. Leaving this macro undefined could result in unpredictable behavior.

FreeRTOS Device Defender API

For a full API reference, see the Device Defender C SDK API Reference.

Example usage

For a full example of the Device Defender library in use, see AWS IoT Device Defender demo.