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
### An Azure IoT Central device client library written in Python.
8
+
8
9
This repository contains code for the Azure IoT Central SDK for Python. This enables python developers to easily create device solutions that semealessly connect to Azure IoT Central applications.
9
10
It hides some of the complexities of the official Azure IoT SDK and uses IoT Central naming conventions.
10
11
11
12
### Disclaimer
12
-
> __This library is experimental and has the purpose of providing an easy to use solution for prototyping and small projects. Although stable and actively maintained, its use in production is discouraged.
13
-
Please refer to official [Azure IoT Python SDK](https://github.com/Azure/azure-iot-sdk-python) when building production products.__
13
+
14
+
> **This library is experimental and has the purpose of providing an easy to use solution for prototyping and small projects. Although stable and actively maintained, its use in production is discouraged.
15
+
> Please refer to official [Azure IoT Python SDK](https://github.com/Azure/azure-iot-sdk-python) when building production products.**
14
16
15
17
_If you're looking for the v0.x.x client library, it is now preserved [here](https://github.com/obastemur/iot_client/tree/master/python).
16
18
Latest version on pypi is 0.3.9_
17
19
18
20
## Prerequisites
19
-
+ Python 2.7+ or Python 3.7+ (recommended)
21
+
22
+
- Python 2.7+ or Python 3.7+ (recommended)
20
23
21
24
## Installing `iotc`
22
25
23
26
```
24
27
pip install iotc
25
28
```
29
+
26
30
These clients are available with an asynchronous API, as well as a blocking synchronous API for compatibility scenarios. **We recommend you use Python 3.7+ and the asynchronous API.**
27
31
28
32
| Python Version | Asynchronous API | Synchronous API |
Check out the [sample repository](samples) for example code showing how the SDK can be used in the various scenarios:
36
38
37
-
*[py3](samples/py3.py) - Sending telemetry and receiving properties and commands with device connected through **symmetric key** (Python 3.7+)
38
-
*[py3_x509](samples/py3_x509.py) - Sending telemetry and receiving properties and commands with device connected through **x509 certificates** (Python 3.7+)
39
-
*[py3_file_logger](samples/py3_file_logger.py) - Print logs on file with rotation (Python 3.7+)
40
-
*[py3_eventhub_logger](samples/py3_eventhub_logger.py) - Redirect logs to Azure Event Hub (Python 3.7+)
39
+
Check out the [sample repository](samples) for example code showing how the SDK can be used in the various scenarios:
41
40
41
+
-[async_device_key](samples/async_device_key) - Sending telemetry and receiving properties and commands with device connected through **symmetric key** (Python 3.7+)
42
+
-[async_x509](samples/async_x509.py) - Sending telemetry and receiving properties and commands with device connected through **x509 certificates** (Python 3.7+)
43
+
-[async_file_logger](samples/async_file_logger.py) - Print logs on file with rotation (Python 3.7+)
44
+
-[async_eventhub_logger](samples/async_eventhub_logger.py) - Redirect logs to Azure Event Hub (Python 3.7+)
42
45
43
46
**The following samples are legacy samples**, they work with the sycnhronous API intended for use with Python 2.7, or in compatibility scenarios with later versions. We recommend you use the asynchronous API and Python3 samples above instead.
44
47
45
-
46
-
*[py2](samples/py2.py) - Sending telemetry and receiving properties and commands with device connected through **symmetric key** (Python 2.7+)
47
-
*[py2_x509](samples/py2_x509.py) - Sending telemetry and receiving properties and commands with device connected through **x509 certificates** (Python 2.7+)
48
-
48
+
-[sync_device_key](samples/sync_device_key.py) - Sending telemetry and receiving properties and commands with device connected through **symmetric key** (Python 2.7+)
49
+
-[sync_x509](samples/sync_x509.py) - Sending telemetry and receiving properties and commands with device connected through **x509 certificates** (Python 2.7+)
49
50
50
51
Samples by default parse a configuration file including required credentials. Just create a file called **samples.ini** inside the _samples_ folder with a content like this:
The configuration file can include one or more sections representing device connection details. Section names must match references in the sample file.
65
67
66
68
### Run samples with local changes
69
+
67
70
It is possible to run samples against the local copy of the device client. This is particularly useful when testing patches not yet published upstream.
68
71
Just add an entry to **samples.ini** in the _DEFAULT_ section:
72
+
69
73
```ini
70
74
[DEFAULT]
71
75
Local = yes
72
76
```
73
77
74
78
## Importing the module
79
+
75
80
Sync client (Python 2.7+ and 3.7+) can be imported in this way:
76
81
77
82
```py
78
83
from iotc import IoTCClient
79
84
```
85
+
80
86
Async client (with asyncio for Python 3.7+ only) can be imported like this:
IOTCConnectType enum can be imported from the same module of IoTCClient
98
106
99
107
_'certPhrase'_ is optional and represents the password for the certificate if any
100
108
101
109
**_A handy tool to generate self-signed certificates in order to test x509 authentication can be found in the IoTCentral Node.JS SDK [here.](https://github.com/lucadruda/iotc-nodejs-device-client#generate-x509-certificates)_**
102
110
103
-
104
111
#### SAS
112
+
105
113
```py
106
114
scopeId ='scopeID'
107
115
device_id ='device_id'
@@ -110,27 +118,35 @@ sasKey = 'masterKey' # or use device key directly
110
118
iotc = IoTCClient(device_id, scopeId,
111
119
IOTCConnectType.IOTC_CONNECT_SYMM_KEY, sas_key)
112
120
```
121
+
113
122
IOTCConnectType enum can be imported from the same module of IoTCClient
114
123
115
124
### Connect
125
+
116
126
Sync
127
+
117
128
```
118
129
iotc.connect()
119
130
```
131
+
120
132
Async
133
+
121
134
```py
122
135
await iotc.connect()
123
136
```
137
+
124
138
After successfull connection, IOTC context is available for further commands.
125
139
126
140
### Reconnection
127
-
The device client automatically handle reconnection in case of network failures or disconnections. However if process runs for long time (e.g. unmonitored devices) a reconnection might fail because of credentials expiration.
141
+
142
+
The device client automatically handle reconnection in case of network failures or disconnections. However if process runs for long time (e.g. unmonitored devices) a reconnection might fail because of credentials expiration.
128
143
129
144
To control reconnection and reset credentials the function _is_connected()_ is available and can be used to test connection status inside a loop or before running operations.
130
145
131
146
e.g.
147
+
132
148
```py
133
-
retry =0# stop reconnection attempts
149
+
retry =0# stop reconnection attempts
134
150
while true:
135
151
if iotc.is_connected():
136
152
# do something
@@ -141,13 +157,37 @@ while true:
141
157
iotc.connect()
142
158
```
143
159
160
+
## Cache Credentials
144
161
162
+
The IoT Central device client accepts a storage manager to cache connection credentials. This allows to skip unnecessary device re-provisioning and requests to provisioning service.
163
+
When valid credentials are present, device connects directly to IoT Central, otherwise it asks provisioning service for new credentials and eventually cache them.
164
+
165
+
Provided class must extend [_Storage_](src/iotc/models.py) abstract class.
166
+
167
+
```py
168
+
classFileStorage(Storage):
169
+
def__init__(self):
170
+
# initialize file read
171
+
...
172
+
defretrieve(self):
173
+
# read from file
174
+
...
175
+
return CredentialsCache(
176
+
hub_name,
177
+
device_id,
178
+
key,
179
+
)
180
+
defpersist(self, credentials):
181
+
# write to file
182
+
...
183
+
```
145
184
146
185
## Operations
147
186
148
187
### Send telemetry
149
188
150
189
e.g. Send telemetry every 3 seconds
190
+
151
191
```py
152
192
while iotc.is_connected():
153
193
await iotc.send_telemetry({
@@ -157,22 +197,28 @@ while iotc.is_connected():
157
197
})
158
198
time.sleep(3)
159
199
```
160
-
An optional *properties* object can be included in the send methods, to specify additional properties for the message (e.g. timestamp,etc... ).
200
+
201
+
An optional _properties_ object can be included in the send methods, to specify additional properties for the message (e.g. timestamp,etc... ).
161
202
Properties can be custom or part of the reserved ones (see list [here](https://github.com/Azure/azure-iot-sdk-csharp/blob/master/iothub/device/src/MessageSystemPropertyNames.cs#L36)).
162
203
163
204
> Payload content type and encoding are set by default to 'application/json' and 'utf-8'. Alternative values can be set using these functions:<br/>
By default device auto-approval in IoT Central is disabled, which means that administrator needs to approve the device registration to complete the provisioning process.
229
281
This can be done from explorer page after selecting the device
To change default behavior, administrator can enable device auto-approval from Device Connection page under the Administration section.
235
287
With automatic approval a device can be provisioned without any manual action and can start sending/receiving data after status changes to "Provisioned"
0 commit comments