18 KiB
V2 - We are now GA!
This repository contains code for the Azure IoT SDKs for Python. This enables python developers to easily create IoT device solutions that seamlessly connect to the Azure IoT Hub ecosystem.
If you're looking for the v1.x.x client library, it is now preserved in the v1-deprecated branch.
Azure IoT SDK for Python
This repository contains the following libraries:
Critical Upcoming Changes Notice
Certificates
All Azure IoT SDK users are advised to be aware of upcoming TLS certificate changes for Azure IoT Hub and Device Provisioning Service that will impact the SDK's ability to connect to these services. In October 2022, both services will migrate from the current Baltimore CyberTrust CA Root to the DigiCert Global G2 CA root. There will be a transition period beforehand where your IoT devices must have both the Baltimore and Digicert public certificates installed in their certificate store in order to prevent connectivity issues.
Devices with only the Baltimore public certificate installed will lose the ability to connect to Azure IoT hub and Device Provisioning Service in October 2022.
To prepare for this change, make sure your device's certificate store has both of these public certificates installed.
For a more in depth explanation as to why the IoT services are doing this, please see this article.
Installing the libraries
Pip installs are provided for all of the SDK libraries in this repo:
Using the libraries
Want to start off on the right foot? Be sure to learn about common pitfalls of using this Python SDK before starting a project.
You can also view samples in each library:
- Device Client Samples cover device and Edge module scenarios.
- IoTHub Service Samples cover IoT Hub service side scenarios.
Features
✔️ feature available ✖️ feature planned but not yet supported ➖ no support planned*
*Features that are not planned may be prioritized in a future release, but are not currently planned
This SDK only supports the MQTT protocol.
Device Client Library (azure-iot-device)
IoTHub Device Client
| Features | Status | Description |
|---|---|---|
| Authentication | ✔️ | Connect your device to IoT Hub securely with supported authentication, including symmetric key, X-509 Self Signed, Certificate Authority (CA) Signed, and SASToken |
| Send device-to-cloud message | ✔️ | Send device-to-cloud messages (max 256KB) to IoT Hub with the option to add custom properties. |
| Receive cloud-to-device messages | ✔️ | Receive cloud-to-device messages and read associated custom and system properties from IoT Hub, with the option to complete/reject/abandon C2D messages. |
| Device Twins | ✔️ | IoT Hub persists a device twin for each device that you connect to IoT Hub. The device can perform operations like get twin tags, subscribe to desired properties. |
| Direct Methods | ✔️ | IoT Hub gives you the ability to invoke direct methods on devices from the cloud. The SDK supports handler for method specific and generic operation. |
| Connection Status and Error reporting | ✔️ | Error reporting for IoT Hub supported error code. |
| Connection Retry | ✔️ | Dropped connections will be retried with a fixed 10 second interval by default. This functionality can be disabled if desired, and the interval can be configured |
| Upload file to Blob | ✔️ | A device can initiate a file upload and notifies IoT Hub when the upload is complete. |
IoTHub Module Client
Note: IoT Edge for Python is scoped to Linux containers & devices only. Learn more about using Linux containers for IoT edge on Windows devices.
| Features | Status | Description |
|---|---|---|
| Authentication | ✔️ | Connect your device to IoT Hub securely with supported authentication, including symmetric key, X-509 Self Signed, and Certificate Authority (CA) Signed. SASToken authentication is not currently supported. |
| Send device-to-cloud message | ✔️ | Send device-to-cloud messages (max 256KB) to IoT Hub with the option to add custom properties. |
| Receive cloud-to-device messages | ✔️ | Receive cloud-to-device messages and read associated custom and system properties from IoT Hub, with the option to complete/reject/abandon C2D messages. |
| Device Twins | ✔️ | IoT Hub persists a device twin for each device that you connect to IoT Hub. The device can perform operations like get twin tags, subscribe to desired properties. |
| Direct Methods | ✔️ | IoT Hub gives you the ability to invoke direct methods on devices from the cloud. The SDK supports handler for method specific and generic operation. |
| Connection Status and Error reporting | ✔️ | Error reporting for IoT Hub supported error code. |
| Connection Retry | ✔️ | Dropped connections will be retried with a fixed 10 second interval. TThis functionality can be disabled if desired, and the interval can be configured |
| Direct Invocation of Method on Modules | ✔️ | Invoke method calls to another module using using the Edge Gateway. |
Provisioning Device Client
| Features | Status | Description |
|---|---|---|
| TPM Individual Enrollment | ➖ | Provisioning via Trusted Platform Module. |
| X.509 Individual Enrollment | ✔️ | Provisioning via X.509 root certificate. Please review the samples folder and this quickstart on how to create a device client. |
| X.509 Enrollment Group | ✔️ | Provisioning via X.509 leaf certificate). Please review the samples folder on how to create a device client. |
| Symmetric Key Enrollment | ✔️ | Provisioning via Symmetric key attestation). Please review the samples folder on how to create a device client. |
IoTHub Service Library (azure-iot-hub)
Registry Manager
| Features | Status | Description |
|---|---|---|
| Identity registry (CRUD) | ✔️ | Use your backend app to perform CRUD operation for individual device or in bulk. |
| Cloud-to-device messaging | ✔️ | Use your backend app to send cloud-to-device messages, and set up cloud-to-device message receivers. |
| Direct Methods operations | ✔️ | Use your backend app to invoke direct method on device. |
| Device Twins operations | ✔️ | Use your backend app to perform device twin operations. *Twin reported property update callback and replace twin are in progress. |
| Query | ✔️ | Use your backend app to perform query for information. |
| Jobs | ✖️ | Use your backend app to perform job operation. |
Releases
The Pythond SDK offers releases for new features, critical bug fixes, and Long Term Support (LTS). Versioning follows semantic versioning, x.y.z. or major.minor.patch. Any time the version is updated, it will be tagged x.y.z.
New Features and Critical Bug Fixes
New features and critical bug fixes (including security updates) will be released on the main branch. These releases will be tagged using the date formatted yyyy-mm-dd. A feature release will bump the minor version and reset the patch version to 0. A critical bug fix will bump the patch version only.
Long Term Support (LTS)
The project offers a Long Term Support (LTS) version to allow users that do not need the latest features to be shielded from unwanted changes.
LTS branches receive all bug fixes that fall in one of these categories:
- security bugfixes
- critical bugfixes (crashes, memory leaks, etc.)
No new features or improvements will be picked up in an LTS branch.
LTS branches are named lts_mm_yyyy, where mm and yyyy are the month and year when the branch was created. An example of such a branch is lts_07_2017.
LTS Schedule1
The first LTS version of the Python SDK is scheduled to be available in early 2022
Below is a table showing the mapping of the LTS branches to the packages released.
| PIP Package | GitHub Branch | LTS Tag | LTS Start Date | Maintenance End Date |
|---|---|---|---|---|
| N/A |
1 All scheduled dates are subject to change by the Azure IoT SDK team.
Contributing
This project welcomes contributions and suggestions. Most contributions require you to agree to a Contributor License Agreement (CLA) declaring that you have the right to, and actually do, grant us the rights to use your contribution. For details, visit https://cla.microsoft.com.
When you submit a pull request, a CLA-bot will automatically determine whether you need to provide a CLA and decorate the PR appropriately (e.g., label, comment). Simply follow the instructions provided by the bot. You will only need to do this once across all repos using our CLA.
This project has adopted the Microsoft Open Source Code of Conduct. For more information see the Code of Conduct FAQ or contact opencode@microsoft.com with any additional questions or comments.