Skip to content

Commit 1f47cf0

Browse files
sfodsfod
authored
Improve readme (#664)
1 parent 19e78af commit 1f47cf0

File tree

3 files changed

+227
-262
lines changed

3 files changed

+227
-262
lines changed

‎README.md‎

Lines changed: 75 additions & 42 deletions
Original file line numberDiff line numberDiff line change
@@ -1,89 +1,122 @@
1-
# AWS IoT Device SDK v2 for Python
1+
# AWS IoT Device SDK for Python v2
22

33
[![Version](https://img.shields.io/pypi/v/awsiotsdk.svg?style=flat)](https://pypi.org/project/awsiotsdk/)
44

5-
This document provides information about the AWS IoT Device SDK v2 for Python. This SDK is built on the [AWS Common Runtime](https://docs.aws.amazon.com/sdkref/latest/guide/common-runtime.html)
5+
The AWS IoT Device SDK for Python v2 connects your Python 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, and Fleet Provisioning.
66

7-
*__Jump To:__*
7+
**Supported Platforms**: Linux, Windows 11+, macOS 14+
8+
9+
> **Note**: The SDK is known to work on older platform versions, but we only guarantee compatibility for the platforms listed above.
10+
11+
*__Topics:__*
12+
* [Features](#features)
813
* [Installation](#installation)
14+
* [Minimum Requirements](#minimum-requirements)
15+
* [Installing from PyPI](#installing-from-pypi)
16+
* [Getting Started](#getting-started)
917
* [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-python-v2/)
1418
* [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
15-
* [Migration Guide from the AWS IoT SDK for Python v1](./documents/MIGRATION_GUIDE.md)
19+
* [Getting Help](#getting-help)
20+
* [Resources](#resources)
21+
22+
## Features
23+
24+
The primary purpose of the AWS IoT Device SDK for Python 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:
1625

26+
* Integrated service clients for AWS IoT Core services
27+
* Secure device connections to AWS IoT Core using MQTT protocol including MQTT 5.0
28+
* Support for [multiple authentication methods and connection types](./documents/MQTT5_Userguide.md#how-to-create-an-mqtt5-client-based-on-desired-connection-method)
29+
30+
#### Supported AWS IoT Core services
31+
32+
* 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.
33+
* The [AWS IoT Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html) service sends remote operations to connected devices.
34+
* The [AWS IoT fleet provisioning](https://docs.aws.amazon.com/iot/latest/developerguide/provision-wo-cert.html) service generates and delivers device certificates automatically.
1735

1836
## Installation
1937

38+
The recommended way to use the AWS IoT Device SDK for Python v2 in your project is to install it from PyPI.
39+
2040
### Minimum Requirements
41+
42+
To develop applications with the AWS IoT Device SDK for Python v2, you need:
43+
2144
* Python 3.8+
2245

23-
[Step-by-step instructions](./documents/PREREQUISITES.md)
46+
See [detailed setup instructions](./documents/PREREQUISITES.md) for more information.
2447

25-
### Install from PyPI
48+
### Installing from PyPI
2649

27-
#### MacOS and Linux:
50+
#### macOS and Linux:
2851

29-
```
52+
```bash
3053
python3 -m pip install awsiotsdk
3154
```
3255

3356
#### Windows:
3457

35-
```
58+
```bash
3659
python -m pip install awsiotsdk
3760
```
3861

39-
### Install from source
62+
### Building from source
4063

41-
```bash
42-
# 1. Create a workspace directory to hold all the SDK files
43-
mkdir sdk-workspace
44-
cd sdk-workspace
64+
See the [Development Guide](./documents/DEVELOPING.md) for detailed instructions on building from source and using local builds.
4565

46-
# 2. Clone the repository. You could select the version of the SDK you desire to use.
47-
git clone -b <SDK_VERSION> https://github.com/aws/aws-iot-device-sdk-python-v2.git
66+
## Getting Started
4867

49-
# 3. (Optional) Setup the version number of your local build. The default version
50-
# for awsiotsdk is set to "1.0.0-dev", you can set the version number of the
51-
# local build in "aws-iot-device-sdk-python-v2/awsiot/__init__.py"
52-
sed -i "s/__version__ = '1.0.0-dev'/__version__ = '<SDK_VERSION>'/" \
53-
aws-iot-device-sdk-python-v2/awsiot/__init__.py
68+
To get started with the AWS IoT Device SDK for Python v2:
5469

55-
# 4. Install using Pip (use 'python' instead of 'python3' on Windows)
56-
python3 -m pip install ./aws-iot-device-sdk-python-v2
57-
```
70+
1. **Install the SDK** - See the [Installation](#installation) section for installation details
71+
72+
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#how-to-create-an-mqtt5-client-based-on-desired-connection-method) and [MQTT5 X509 sample](./samples/mqtt/mqtt5_x509.md) provide more guidance
73+
74+
3. **Follow a complete example** - Check out the [samples](samples) directory
75+
76+
4. **Learn MQTT5 features** - For advanced usage and configuration options, see the [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
5877

5978
## Samples
6079

61-
[Samples README](samples)
80+
Check out the [samples](samples) directory for working code examples that demonstrate:
81+
- [Basic MQTT connection and messaging](./samples/mqtt/mqtt5_x509.md)
82+
- [AWS IoT Device Shadow operations](./samples/service_clients/shadow.md)
83+
- [AWS IoT Jobs](./samples/service_clients/jobs.md)
84+
- AWS IoT Fleet provisioning: [basic](./samples/service_clients/fleet_provisioning_basic.md) and [with CSR](./samples/service_clients/fleet_provisioning_csr.md)
85+
86+
The samples provide ready-to-run code with detailed setup instructions for each authentication method and use case.
87+
88+
## Getting Help
89+
90+
The best way to interact with our team is through GitHub.
91+
* Open [discussion](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions): Share ideas and solutions with the SDK community
92+
* Search [issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues): Find created issues for answers based on a topic
93+
* Create an [issue](https://github.com/aws/aws-iot-device-sdk-python-v2/issues/new/choose): New feature request or file a bug
94+
95+
If you have a support plan with [AWS Support](https://aws.amazon.com/premiumsupport/), you can also create a new support case.
96+
97+
#### Mac-Only TLS Behavior
6298

63-
### Mac-Only TLS Behavior
99+
> [!NOTE]
100+
> This SDK does not support TLS 1.3 on macOS. Support for TLS 1.3 on macOS is planned for a future release.
64101
65102
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:
66103

67104
```
68-
static: certificate has an existing certificate-key pair that was previously imported into the Keychain. Using key from Keychain instead of the one provided.
105+
static: certificate has an existing certificate-key pair that was previously imported into the Keychain.
106+
Using key from Keychain instead of the one provided.
69107
```
70108

71-
## Getting Help
72-
73-
The best way to interact with our team is through GitHub. You can open a [discussion](https://github.com/aws/aws-iot-device-sdk-python-v2/discussions) for guidance questions or an [issue](https://github.com/aws/aws-iot-device-sdk-python-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.
109+
## Resources
74110

75-
Please make sure to check out our resources too before opening an issue:
111+
Check out our resources for additional guidance too before opening an issue:
76112

77113
* [FAQ](./documents/FAQ.md)
114+
* [AWS IoT Core Developer Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html)
115+
* [MQTT5 User Guide](./documents/MQTT5_Userguide.md)
78116
* [API Docs](https://aws.github.io/aws-iot-device-sdk-python-v2/)
79-
* [IoT Guide](https://docs.aws.amazon.com/iot/latest/developerguide/what-is-aws-iot.html) ([source](https://github.com/awsdocs/aws-iot-docs))
80-
* Check for similar [Issues](https://github.com/aws/aws-iot-device-sdk-python-v2/issues)
81117
* [AWS IoT Core Documentation](https://docs.aws.amazon.com/iot/)
82-
* [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)
83-
* Integration with AWS IoT Services such as
84-
[Device Shadow](https://docs.aws.amazon.com/iot/latest/developerguide/iot-device-shadows.html)
85-
and [Jobs](https://docs.aws.amazon.com/iot/latest/developerguide/iot-jobs.html)
86-
is provided by code that been generated from a model of the service.
118+
* [Dev Blog](https://aws.amazon.com/blogs/iot/category/internet-of-things/)
119+
* [Migration Guide from the AWS IoT SDK for Python v1](./documents/MIGRATION_GUIDE.md)
87120
* [Contributions Guidelines](./documents/CONTRIBUTING.md)
88121

89122
## License

‎documents/DEVELOPING.md‎

Lines changed: 23 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,23 @@
1+
# Development Guide
2+
3+
This document provides instructions for building the AWS IoT Device SDK for Python v2.
4+
5+
## Building from source
6+
7+
```bash
8+
# 1. Create a workspace directory to hold all the SDK files
9+
mkdir sdk-workspace
10+
cd sdk-workspace
11+
12+
# 2. Clone the repository. You could select the version of the SDK you desire to use.
13+
git clone -b <SDK_VERSION> https://github.com/aws/aws-iot-device-sdk-python-v2.git
14+
15+
# 3. (Optional) Setup the version number of your local build. The default version
16+
# for awsiotsdk is set to "1.0.0-dev", you can set the version number of the
17+
# local build in "aws-iot-device-sdk-python-v2/awsiot/__init__.py"
18+
sed -i "s/__version__ = '1.0.0-dev'/__version__ = '<SDK_VERSION>'/" \
19+
aws-iot-device-sdk-python-v2/awsiot/__init__.py
20+
21+
# 4. Install using Pip (use 'python' instead of 'python3' on Windows)
22+
python3 -m pip install ./aws-iot-device-sdk-python-v2
23+
```

0 commit comments

Comments
 (0)