Skip to content

Commit 83a6f9f

Browse files
sfodsfod
authored
Improve readme (#836)
1 parent c1d527b commit 83a6f9f

File tree

2 files changed

+236
-243
lines changed

2 files changed

+236
-243
lines changed

‎README.md‎

Lines changed: 108 additions & 78 deletions
Original file line numberDiff line numberDiff line change
@@ -1,138 +1,168 @@
11
# AWS IoT Device SDK for C++ v2
22

3-
This document provides information about the AWS IoT device SDK for C++ V2. This SDK is built on the [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)
3+
The AWS IoT Device SDK for C++ v2 connects your C++ applications and devices to the AWS IoT platform. It handles the complexities of secure communication, authentication, and device management so you can focus on your IoT solution. The SDK makes it easy to use AWS IoT services like Device Shadows, Jobs, Fleet Provisioning, and Commands.
44

5-
__Jump To:__
5+
**Supported Platforms**: Linux, Windows 11+, macOS 14+
66

7-
* [Supported Architectures](#supported-architectures)
7+
> **Note**: The SDK is known to work on older platform versions, but we only guarantee compatibility for the platforms listed above.
8+
9+
*__Topics:__*
10+
* [Features](#features)
811
* [Installation](#installation)
9-
* [Samples](./samples)
10-
* [Mac-Only TLS Behavior](#mac-only-tls-behavior)
11-
* [Getting Help](#getting-help)
12-
* [FAQ](./documents/FAQ.md)
13-
* [API Docs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/)
12+
* [Minimum Requirements](#minimum-requirements)
13+
* [Building from source](#building-from-source)
14+
* [Getting Started](#getting-started)
15+
* [Samples](samples)
1416
* [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
15-
* [Migration Guide from the AWS IoT SDK for C++ v1](./documents/MIGRATION_GUIDE.md)
17+
* [Getting Help](#getting-help)
18+
* [Resources](#resources)
1619

17-
## Supported Architectures
20+
## Features
1821

19-
### Linux
20-
- manylinux2014-x64
21-
- manylinux2014-x86
22-
- al2-x64
23-
- alpine-3.16-x64
24-
- alpine-3.16-x86
25-
- alpine-3.16-armv6
26-
- alpine-3.16-armv7
27-
- alpine-3.16-arm64
28-
- raspberry pi bullseye
29-
- ARM64 /aarch64
30-
- ArmV7
31-
- x86\_64
32-
- x86
33-
### Windows
34-
- Win32
35-
- x64
36-
- ARM64
37-
### Mac
38-
- Apple Silicone (M1 and higher)
39-
- Apple Intel Chips (x86\_64)
22+
The primary purpose of the AWS IoT Device SDK for C++ v2 is to simplify the process of connecting devices to AWS IoT Core and interacting with AWS IoT services on various platforms. The SDK provides:
23+
24+
* Integrated service clients for AWS IoT Core services
25+
* Secure device connections to AWS IoT Core using MQTT protocol including MQTT 5.0
26+
* Support for [multiple authentication methods and connection types](./documents/MQTT5_Userguide.md#connecting-to-aws-iot-core)
27+
28+
#### Supported AWS IoT Core services
29+
30+
* The [AWS IoT Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html) service manages device state information in the cloud.
31+
* The [AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service sends remote operations to connected devices.
32+
* The [AWS IoT fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) service generates and delivers device certificates automatically.
33+
* The [AWS IoT Device Management commands](https://docs.aws.amazon.com/iot/latest/developerguide/iot-remote-command.html) service sends instructions from the cloud to connected devices.
4034

4135
## Installation
4236

37+
The recommended way to use the AWS IoT Device SDK for C++ v2 in your project is to build it from source.
38+
4339
### Minimum Requirements
40+
41+
To develop applications with the AWS IoT Device SDK for C++ v2, you need:
42+
4443
* C++ 11 or higher
45-
* Clang 6+ or GCC 4.8+ or MSVC 2015+
44+
* Clang 6+ or GCC 4.8+ or MSVC 2015+
4645
* CMake 3.9+
4746

48-
[Step-by-step instructions](./documents/PREREQUISITES.md)
47+
See [detailed setup instructions](./documents/PREREQUISITES.md) for more information.
48+
49+
#### Supported Architectures
50+
51+
**Linux:**
52+
- manylinux2014-x64, manylinux2014-x86
53+
- al2-x64
54+
- alpine-3.16 (x64, x86, armv6, armv7, arm64)
55+
- raspberry pi bullseye
56+
- ARM64/aarch64, ArmV7, x86_64, x86
57+
58+
**Windows:**
59+
- Win32, x64, ARM64
4960

61+
**macOS:**
62+
- Apple Silicon (M1 and higher)
63+
- Apple Intel Chips (x86_64)
5064

51-
### Build from source
65+
### Building from source
5266

53-
``` sh
67+
```bash
5468
# Create a workspace directory to hold all the SDK files
5569
mkdir sdk-workspace
5670
cd sdk-workspace
71+
5772
# Clone the repository
5873
git clone --recursive https://github.com/aws/aws-iot-device-sdk-cpp-v2.git
59-
# Make a build directory for the SDK. Can use any name.
74+
75+
# Make a build directory for the SDK
6076
mkdir aws-iot-device-sdk-cpp-v2-build
6177
cd aws-iot-device-sdk-cpp-v2-build
62-
# continue with the build steps below based on OS
6378
```
6479

65-
#### MacOS and Linux
66-
```sh
67-
# Generate the SDK build files.
68-
# -DCMAKE_INSTALL_PREFIX needs to be the absolute/full path to the directory.
69-
# (Example: "/Users/example/sdk-workspace/).
80+
#### macOS and Linux
81+
82+
> [!NOTE]
83+
> **Linux specific**
84+
> The IoT SDK uses [s2n-tls](https://github.com/aws/s2n-tls) for TLS on Linux. However, s2n-tls uses libcrypto (the cryptography library from OpenSSL). To simplify building, s2n-tls and libcrypto source code are included as git submodules and built with the SDK. If your application also loads the system OpenSSL installation (e.g., via libcurl), there may be crashes from using two different libcrypto versions simultaneously. In this case, configure with `-DUSE_OPENSSL=ON` to link against system libcrypto and avoid conflicts.
85+
86+
```bash
87+
# Generate the SDK build files
88+
# -DCMAKE_INSTALL_PREFIX needs to be the absolute/full path to the directory
7089
# -DCMAKE_BUILD_TYPE can be "Release", "RelWithDebInfo", or "Debug"
7190
cmake -DCMAKE_INSTALL_PREFIX="<absolute path to sdk-workspace>" -DCMAKE_BUILD_TYPE="Debug" ../aws-iot-device-sdk-cpp-v2
72-
# Build and install the library. Once installed, you can develop with the SDK and run the samples
91+
92+
# Build and install the library
7393
cmake --build . --target install
7494
```
7595

7696
#### Windows
77-
``` sh
78-
# Generate the SDK build files.
79-
# -DCMAKE_INSTALL_PREFIX needs to be the absolute/full path to the directory.
80-
# (Example: "C:/users/example/sdk-workspace/).
97+
98+
> [!TIP]
99+
> Due to path length limitations in the Windows API, we recommend cloning to a short path like: `C:\dev\iotsdk`
100+
101+
```bash
102+
# Generate the SDK build files
103+
# -DCMAKE_INSTALL_PREFIX needs to be the absolute/full path to the directory
81104
cmake -DCMAKE_INSTALL_PREFIX="<absolute path sdk-workspace dir>" ../aws-iot-device-sdk-cpp-v2
82-
# Build and install the library. Once installed, you can develop with the SDK and run the samples
105+
106+
# Build and install the library
83107
# -config can be "Release", "RelWithDebInfo", or "Debug"
84108
cmake --build . --target install --config "Debug"
85109
```
86110

87-
**Windows specific notes**:
88-
* Due to maximum path length limitations in the Windows API, we recommend cloning to a short path like: `C:\dev\iotsdk`
89-
* `--config` is only REQUIRED for multi-configuration build tools (VisualStudio/MsBuild being the most common).
111+
`--config` is only required for multi-configuration build tools (Visual Studio/MSBuild)
112+
113+
## Getting Started
114+
115+
To get started with the AWS IoT Device SDK for C++ v2:
90116

91-
**Linux specific notes**:
117+
1. **Build the SDK** - See the [Installation](#installation) section for build instructions
92118

93-
If your application uses OpenSSL, configure with `-DUSE_OPENSSL=ON`.
119+
2. **Choose your connection method** - The SDK supports multiple authentication methods including X.509 certificates, AWS credentials, and custom authentication. [MQTT5 User Guide connection section](./documents/MQTT5_Userguide.md#connecting-to-aws-iot-core) provides more guidance
94120

95-
The IoT SDK does not use OpenSSL for TLS.
96-
On Apple and Windows, the OS's default TLS library is used.
97-
On Linux, [s2n-tls](https://github.com/aws/s2n-tls) is used.
98-
But s2n-tls uses libcrypto, the cryptography math library bundled with OpenSSL.
99-
To simplify the build process, the source code for s2n-tls and libcrypto are
100-
included as git submodules and built along with the IoT SDK.
101-
But if your application is also loading the system installation of OpenSSL
102-
(i.e. your application uses libcurl which uses libssl which uses libcrypto)
103-
there may be crashes as the application tries to use two different versions of libcrypto at once.
121+
3. **Follow a complete example** - Check out the [samples](samples) directory
104122

105-
Setting `-DUSE_OPENSSL=ON` will cause the IoT SDK to link against your system's
106-
existing `libcrypto`, instead of building its own copy.
123+
4. **Learn MQTT5 features** - For advanced usage and configuration options, see the [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
107124

108125
## Samples
109126

110-
[Samples README](./samples)
127+
Check out the [samples](samples) directory for working code examples that demonstrate:
128+
- [Basic MQTT connection and messaging](./samples/README.md#mqtt5-client-samples)
129+
- [AWS IoT Device Shadow operations](./samples/service_clients/shadow/shadow-sandbox/README.md)
130+
- [AWS IoT Jobs](./samples/service_clients/jobs/jobs-sandbox/README.md)
131+
- AWS IoT Fleet provisioning: [basic](./samples/service_clients/fleet_provisioning/provision-basic/README.md) and [with CSR](./samples/service_clients/fleet_provisioning/provision-csr/README.md)
132+
- [AWS IoT Commands](./samples/service_clients/commands/commands-sandbox/README.md)
133+
- Secure Tunneling: [secure tunnel](./samples/others/secure_tunneling/secure_tunnel/README.md) and [tunnel notification](./samples/others/secure_tunneling/tunnel_notification/README.md)
111134

112-
### Mac-Only TLS Behavior
135+
The samples provide ready-to-run code with detailed setup instructions for each authentication method and use case.
136+
137+
## Getting Help
138+
139+
The best way to interact with our team is through GitHub.
140+
* Open [discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions): Share ideas and solutions with the SDK community
141+
* Search [issues](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues): Find created issues for answers based on a topic
142+
* Create an [issue](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues/new/choose): New feature request or file a bug
143+
144+
If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
145+
146+
#### Mac-Only TLS Behavior
113147

114148
Please note that on Mac, once a private key is used with a certificate, that certificate-key pair is imported into the Mac Keychain. All subsequent uses of that certificate will use the stored private key and ignore anything passed in programmatically. Beginning in v1.7.3, when a stored private key from the Keychain is used, the following will be logged at the "info" log level:
115149

116150
```
117-
static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided.
151+
static: certificate has an existing certificate-key pair that was previously imported into the Keychain.
152+
Using key from Keychain instead of the one provided.
118153
```
119154

120-
## Getting Help
121-
122-
The best way to interact with our team is through GitHub. You can open a [discussion](https://github.com/aws/aws-iot-device-sdk-cpp-v2/discussions) for guidance questions or an [issue](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues/new/choose) for bug reports, or feature requests. You may also find help on community resources such as [StackOverFlow](https://stackoverflow.com/questions/tagged/aws-iot) with the tag [#aws-iot](https://stackoverflow.com/questions/tagged/aws-iot) or if you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
155+
## Resources
123156

124-
Please make sure to check out our resources too before opening an issue:
157+
Check out our resources for additional guidance too before opening an issue:
125158

126159
* [FAQ](./documents/FAQ.md)
160+
* [AWS IoT Core Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html)
161+
* [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
127162
* [API Docs](https://aws.github.io/aws-iot-device-sdk-cpp-v2/)
128-
* [IoT Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs))
129-
* Check for similar [Issues](https://github.com/aws/aws-iot-device-sdk-cpp-v2/issues)
130163
* [AWS IoT Core Documentation](https://docs.aws.amazon.com/iot/)
131-
* [Dev Blog](https://aws.amazon.com/blogs/?awsf.blog-master-iot=category-internet-of-things%23amazon-freertos%7Ccategory-internet-of-things%23aws-greengrass%7Ccategory-internet-of-things%23aws-iot-analytics%7Ccategory-internet-of-things%23aws-iot-button%7Ccategory-internet-of-things%23aws-iot-device-defender%7Ccategory-internet-of-things%23aws-iot-device-management%7Ccategory-internet-of-things%23aws-iot-platform)
132-
* Integration with AWS IoT Services such as
133-
[Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)
134-
and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
135-
is provided by code that been generated from a model of the service.
164+
* [Dev Blog](https://aws.amazon.com/blogs/iot/category/internet-of-things/)
165+
* [Migration Guide from the AWS IoT SDK for C++ v1](./documents/MIGRATION_GUIDE.md)
136166
* [Secure Tunnel User Guide](./documents/Secure_Tunnel_Userguide.md)
137167
* [Contributions Guidelines](./documents/CONTRIBUTING.md)
138168

0 commit comments

Comments
 (0)