samples

Sample apps for the AWS IoT Device SDK for C++ v2

MQTT5 Samples

MQTT5 is the recommended MQTT Client. It has many benefits over MQTT311 outlined in the MQTT5 User Guide

• Mqtt5 Pub-Sub
  • Direct MQTT with X509-based mutual TLS
  • MQTT over Websockets with Sigv4 authentication
  • Direct MQTT with Custom Authentication
  • MQTT over Websockets with Cognito
  • HTTP Proxy
• Mqtt5 Shared Subscription
• Mqtt5 Jobs
• Mqtt5 Shadow
• Mqtt5 Fleet Provisioning

MQTT311 Samples

• Basic Pub-Sub
• Basic Connect
• Websocket Connect
• PKCS#11 Connect
• PKCS#12 Connect
• x509 Credentials Provider Connect
• Windows Certificate MQTT Connect
• Custom Authorizer Connect
• Cognito Connect
• Shadow
• Jobs
• Fleet provisioning

Other Samples

• Secure Tunnel
• Secure Tunnel Notification
• Cycle Pub-Sub
• Greengrass discovery
• Greengrass IPC
• Mqtt5 Device Defender
• Mqtt311 Device Defender

Build Instruction

Firstly, build and install aws-iot-devices-sdk-cpp-v2 with following instructions from Installation.

Build individual sample

Change directory into one of the samples. Under the directory of the sample you wish to build, run the following commands:

cmake -B build -S . -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>" -DCMAKE_BUILD_TYPE="<Release|RelWithDebInfo|Debug>" .
cmake --build build --config "<Release|RelWithDebInfo|Debug>"

For CMake versions that do not support the -B command, go to the directory of the sample you wish to build and run the following commands:

mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>" -DCMAKE_BUILD_TYPE="<Release|RelWithDebInfo|Debug>" ..
cmake --build . --config "<Release|RelWithDebInfo|Debug>"

Build all samples

Change directory to the aws-iot-device-sdk-cpp-v2/samples directory and then run the following commands:

cmake -B build -S . -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>" -DCMAKE_BUILD_TYPE="<Release|RelWithDebInfo|Debug>"
cmake --build build --config "<Release|RelWithDebInfo|Debug>"

This will compile all the samples at once and place the executables under the build directory relative to their file path. To view the commands for a given sample, run the compiled program and pass --help. For example, with the MQTT5 PubSub sample:

./build/mqtt5/mqtt5_pubsub/mqtt5_pubsub --help

This will compile all of the samples at once. You can then find the samples in the aws-iot-device-sdk-cpp-v2/samples/build folder. For example, the MQTT5 PubSub sample will be located at aws-iot-device-sdk-cpp-v2/samples/build/mqtt5/mqtt5_pubsub.

For CMake versions that do not support the -B command, go to the aws-iot-device-sdk-cpp-v2/samples directory and run the following commands:

mkdir build
cd build
cmake -DCMAKE_PREFIX_PATH="<absolute path sdk-cpp-workspace dir>" -DCMAKE_BUILD_TYPE="<Release|RelWithDebInfo|Debug>" ..
cmake --build . --config "<Release|RelWithDebInfo|Debug>"

Note that building all the samples at once is currently only available in the V2 C++ IoT SDK at this time.

Sample Build Notes

• -DCMAKE_PREFIX_PATH needs to be set to the path aws-iot-device-sdk-cpp-v2 installed at. Since Installation takes sdk-cpp-workspace as an example, this file uses that example too.

• -DCMAKE_BUILD_TYPE and --config needs to match the CMAKE_BUILD_TYPE when aws-iot-device-sdk-cpp-v2 built. --config is only REQUIRED for multi-configuration build tools.

Sample help

All samples will show their options by passing in --help. For example:

./build/mqtt5/mqtt5_pubsub/mqtt5_pubsub --help

Which will result in output showing all of the options that can be passed in at the command line, along with descriptions of what each does and whether or not they are optional or not.

Enable logging in samples

To enable logging in the samples, you can pass in --verbosity, and optionally --log_file, to the sample:

./build/basic-pub-sub --verbosity "Trace" --log_file "log.txt"

• --verbosity: The level of logging shown. Can be Trace, Debug, Info, Warn, Error, Fatal or None. Logging will not occur if this is not passed in with None or greater logging level.
• --log_file: The filepath to store the logs at. This is optional, and if undefined the logs will be printed to stdout instead.