Notice: Running the AWS IoT Device Client will incur usage of AWS IoT services, and is likely to incur charges on your AWS account. Please refer the pricing pages for AWS IoT Core, AWS IoT Device Management, and AWS IoT Device Defender for more details.
Jump To:
- Introduction
- Installation
- Setup & Configuration
- Jobs Feature
- Fleet Provisioning Feature
- Device Defender Feature
- Secure Tunneling Feature
- Named Shadow Feature
- Logging
- Samples:
- Doxygen Documentation
- Additional Resources
- Security
- License
Sections:
The AWS IoT Device Client is free, open-source, modular software written in C++ that you can compile and install on your Embedded Linux based IoT devices to access AWS IoT Core, AWS IoT Device Management, and AWS IoT Device Defender features by default. It serves as a reference implementation for your IoT devices to work with AWS IoT services, with operational best practices baked in – using it is the easiest way to create a proof-of-concept (PoC) for your IoT project. What’s more, since it is open-source, you can modify it to fit your business needs, or optimize it when you wish to scale up from a PoC to production.
The modular IoT Device Client consists of a “base client” and discrete “client-side features” that support the following:
- The base client handles MQTT connectivity with AWS IoT core - it enables your IoT device to automatically connect and make subscriptions to feature-relevant MQTT topics. It also provides a logging API for device side logs.
- The client-side Jobs feature enables you to execute remote actions on your device when you use the Jobs feature of the AWS IoT Device Management service. It provides support for a few remote actions by default, and extensibility for custom actions. You can use custom actions to remotely control the state of your IoT devices.
- The client-side Secure Tunneling feature enables secure, privileged access to your IoT device when you use the Secure Tunneling feature in the AWS IoT Device Management service.
- The client-side Device Defender feature enables you to collect standard Device Side Metrics when you use the Rules Detect feature in the AWS IoT Device Defender service.
- The client-side Fleet Provisioning feature enables you to replace provisional credentials with device-specific ones when you onboard a fleet of devices using the Fleet Provisioning capability of AWS IoT Core. It creates a device specific certificate and private key, and registers the device on AWS IoT Core.
- The client-side Named Shadows feature enables you to control your IoT device using AWS IoT Named Shadows. Shadows can store your device's state information and make it available to your device, AWS IoT services, your custom apps and other AWS services whether the device is online and connected to AWS IoT or not.
The AWS IoT Device Client currently works on IoT devices with common microprocessors (x86_64, ARM architectures), and common Linux software environments (Debian, Ubuntu, and RHEL).
Sections:
- C++ 11 or higher
- CMake 3.10+
- OpenSSL 1.1.1
- aws-iot-device-sdk-cpp-v2 commit hash located in
CMakeLists.txt.awssdk
Note: The TLS stack, and the version of the SDK mentioned above is what our CI uses. You could potentially use a different TLS stack for example, we just don't actively test or support this.
To use the AWS IoT Device Client, you'll need to compile an executable using the source code provided by this repository. Below, you'll find instructions for how to build the AWS IoT Device Client for your target machine.
The following commands should work for most users when you plan to run the AWS IoT Device Client on the same machine that you're performing the compilation on:
# Building
git clone https://github.com/awslabs/aws-iot-device-client
cd aws-iot-device-client
mkdir build
cd build
cmake ../
cmake --build . --target aws-iot-device-client
# Setup
cd ../
./setup.sh # At this point you'll need to respond to prompts for information, including paths to your thing certs
# Run the AWS IoT Device Client
./aws-iot-device-client # This command runs the executable
cmake ../
cmake --build . --target test-aws-iot-device-client
./build/test/test-aws-iot-device-client
Setting Up The Device Client
Configuring the AWS IoT Device Client
File and Directory Permission Requirements
Jobs Feature Readme
Fleet Provisioning Feature Readme
Device Defender Feature Readme
Secure Tunneling Feature Readme
Named Shadow Feature Readme
This section provides links to additional AWS IoT resources that may help you use and modify the AWS IoT Device Client:
- API Documentation generated by Doxygen
- Related SDKs, Samples, and Documentation
- AWS IoT Device SDK for C++ v2
See CONTRIBUTING for more information.
This project is licensed under the Apache-2.0 License.