You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: readme.md
+76-4Lines changed: 76 additions & 4 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,19 +1,38 @@
1
1
# Microsoft Azure IoT SDKs for Python
2
2
3
3
This repository contains the following:
4
-
5
4
***Azure IoT Hub Device SDK for Python**: to connect client devices to Azure IoT Hub
6
5
***Azure IoT Hub Service SDK for Python**: enables developing back-end applications for Azure IoT
7
6
8
-
To find SDKs in other languages for Azure IoT, please refer to the [azure-iot-sdks][azure-iot-sdks] repository.
9
-
10
7
To create and manage an instance of IoT Hub in your Azure subscription using Python, you can use the [Azure IoT Hub management library for Python][azure-iot-mgmt-lib]. Read more [here][azure-iot-mgmt-lib-doc].
11
8
12
9
To manage all your Azure resources using Python, you can leverate the [Azure CLI v2][azure-cli-v2].
13
10
11
+
To find SDKs in other languages for Azure IoT, please refer to the [azure-iot-sdks][azure-iot-sdks] repository.
12
+
14
13
## Developing applications for Azure IoT
15
14
Visit [Azure IoT Dev Center][iot-dev-center] to learn more about developing applications for Azure IoT.
16
15
16
+
## Key features and roadmap
17
+
18
+
:white_check_mark: feature available :large_blue_diamond: feature in-progress :large_orange_diamond: feature planned :x: no support planned
| Authentication |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| Connect your device to IoT Hub securely with [supported authentication](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-security-deployment), including private key, SASToken, X-509 Self Signed and Certificate Authority (CA) Signed. X-509 (CA) Signed is not supported on .NET SDK yet. |
23
+
| Retry policies |:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:white_check_mark:|:white_check_mark:| Retry policy for unsuccessful device-to-cloud messages have three options: no try, exponential backoff with jitter (default) and custom. |
24
+
| Connection status reporting |:large_orange_diamond:|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:||
25
+
| Devices multiplexing over single connection |:white_check_mark:|:x:|:x:|:white_check_mark:|:white_check_mark:||
26
+
| Connection Pooling - Specifying number of connections |:white_check_mark:|:x:|:x:|:white_check_mark:|:white_check_mark:| Send device-to-cloud messages to IoT Hub with custom properties. You can also choose to batch send at most 256 KBs (not available over MQTT and AMQP). Send device-to-cloud messages with system properties in backlog. Click [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-messages-d2c) for detailed information on the IoT Hub features. |
| Receive C2D messages |:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| Receive cloud-to-device messages and read associated custom and system properties from IoT Hub, with the option to complete/reject/abandon C2D messages (not available over MQTT and MQTT-websocket). Click [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-messages-c2d) for detailed information on the IoT Hub features. |
29
+
| Upload file to Blob |:white_check_mark:|:x:|:x:|:x:|:x:| A device can initiate a file upload and notifies IoT Hub when the upload is complete. Click [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-file-upload) for detailed information on the IoT Hub features. |
30
+
| Device Twins |:x:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:| 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. Send reported properties version and desired properties version are in backlog. Click [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-device-twins) for detailed information on the IoT Hub features. |
31
+
| Direct Methods |:x:|:white_check_mark:|:white_check_mark:|:white_check_mark:|:white_check_mark:| 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. Click [here](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-devguide-direct-methods) for detailed information on the IoT Hub features. |
32
+
| Error reporting (TBD) |:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:| Error reporting for exceeding quota, authentication error, throttling error, and device not found error. |
33
+
| SDK Options |:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:| Set SDK options for proxy settings, client version string, polling time, specify TrustedCert for IoT hub, Network interface selection, C2D keep alive. |
34
+
| Device Provisioning Service |:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:|:large_orange_diamond:||
35
+
17
36
## How to clone the repository
18
37
The repository is using [GitHub Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for its dependencies. In order to automatically clone these submodules, you need to use the --recursive option as described here:
Devices and data sources in an IoT solution can range from a simple network-connected sensor to a powerful, standalone computing device. Devices may have limited processing capability, memory, communication bandwidth, and communication protocol support. The IoT device SDKs enable you to implement client applications for a wide variety of devices.
31
-
***Using PyPI package on Windows, Linux (Ubuntu) or Raspberry Pi**: the simplest way to use the Azure IoT SDK for Python to develop device apps on Windows is to leverage the PyPI package which you can install following these [instructions][PyPI-install-instructions]
50
+
***Using PyPI package on Windows, Linux (Ubuntu) or Raspberry Pi**: the simplest way to use the Azure IoT SDK for Python to develop device apps on Windows is to leverage the PyPI package which you can install following these [instructions][PyPI-install-instructions].
51
+
***Clone the repository**: The repository is using [GitHub Submodules](https://git-scm.com/book/en/v2/Git-Tools-Submodules) for its dependencies. In order to automatically clone these submodules, you need to use the --recursive option as described here:
If you have downloaded the zip instead of cloning the repository, you will need to run the following command to restore submodules:
56
+
```
57
+
git submodule update --init --recursive
58
+
```
59
+
32
60
***Building the libraries and working with the SDK code**: follow [these instructions][devbox-setup].
33
61
34
62
## Samples
35
63
This repository contains various Python sample applications that illustrate how to use the Microsoft Azure IoT SDKs for Python.
36
64
*[Device SDK samples][device-samples]
37
65
*[Service SDK samples][service-samples]
38
66
67
+
## OS platforms and hardware compatibility
68
+
[ATTN:CONTENT REQUIRED - this whole section is copied from the C SDK, please check requirements.]
69
+
70
+
The IoT Hub device SDK for Python can be used with a broad range of OS platforms and devices:
71
+
[INCLUDE A LIST OF PLATFORMS SUPPORTED BY Python OUT OF BOX]
72
+
73
+
The minimum requirements are for the device platform to support the following:
74
+
75
+
-**Being capable of establishing an IP connection**: only IP-capable devices can communicate directly with Azure IoT Hub.
76
+
-**Support TLS**: required to establish a secure communication channel with Azure IoT Hub.
77
+
-**Support SHA-256** (optional): necessary to generate the secure token for authenticating the device with the service. Different authentication methods are available and not all require SHA-256.
78
+
-**Have a Real Time Clock or implement code to connect to an NTP server**: necessary for both establishing the TLS connection and generating the secure token for authentication.
79
+
-**Having at least 64KB of RAM**: the memory footprint of the SDK depends on the SDK and protocol used as well as the platform targeted. The smallest footprint is achieved targeting microcontrollers.
80
+
81
+
You can find an exhaustive list of the OS platforms the various SDKs have been tested against in the [Azure Certified for IoT device catalog](https://catalog.azureiotsuite.com/). Note that you might still be able to use the SDKs on OS and hardware platforms that are not listed on this page: all the SDKs are open sourced and designed to be portable. If you have suggestions, feedback or issues to report, refer to the Contribution and Support sections below.
82
+
39
83
## Contribution, feedback and issues
40
84
If you encounter any bugs, have suggestions for new features or if you would like to become an active contributor to this project please follow the instructions provided in the [contribution guidelines](.github/CONTRIBUTING.md).
41
85
@@ -51,6 +95,33 @@ Here is what you can expect Microsoft Support to be able to help with:
*[Prepare your development environment to use the Azure IoT device SDK for C][devbox-setup]
99
+
*[Setup IoT Hub][setup-iothub]
100
+
101
+
## SDK folder structure
102
+
[ATTN:CONTENT REQUIRED - please provide descriptions and check those provided (they were largely based on the descriptions in the c SDK)]
103
+
104
+
### /build_all
105
+
106
+
This folder contains platform-specific build scripts for the client libraries and dependent components.
107
+
108
+
### /device
109
+
110
+
Contains Azure IoT Hub client components that provide the raw messaging capabilities of the library. Refer to the API documentation and samples for information on how to use it.
111
+
112
+
* iothub_client_python: contains C source of the Python extension module. This module wraps the IoT Hub C SDK as extension module for Python. The C extension interface is specific to Boost Python and it does not work on other implementations.
113
+
* samples: contains simple sample Python applications excercising basic features using AMQP, MQTT and HTTP.
114
+
* tests: contains Python C extension module unit tests. The unit tests exercise a mocked Python extension module to test the Python interface.
115
+
116
+
### /doc
117
+
118
+
This folder contains application development guides and device setup instructions.
119
+
120
+
### /jenkins
121
+
122
+
### /service
123
+
124
+
Contains libraries that enable interactions with the IoT Hub service to perform operations such as sending messages to devices and managing the device identity registry.
54
125
55
126
# Long Term Support
56
127
@@ -85,6 +156,7 @@ This project has adopted the [Microsoft Open Source Code of Conduct](https://ope
0 commit comments