Azure IoT Central device client for Python
Project description
iotc - Azure IoT Central - Python (light) device SDK Documentation
Prerequisites
Python 2.7+ or Python 3.4+ or Micropython 1.9+
Runtime dependencies vary per platform
Install
Python 2/3
pip install iotc
Common Concepts
- API calls should return
0
on success anderror code
otherwise. - External API naming convention follows
lowerCamelCase
forDevice
class members
Usage
import iotc
device = iotc.Device(scopeId, keyORCert, deviceId, credType)
- scopeId : Azure IoT DPS Scope Id
- keyORcert : Symmetric key or x509 Certificate
- deviceId : Device Id
- credType :
IOTConnectType.IOTC_CONNECT_SYMM_KEY
orIOTConnectType.IOTC_CONNECT_X509_CERT
keyORcert
for X509
certificate:
credType = IOTConnectType.IOTC_CONNECT_X509_CERT
keyORcert = {
"keyfile": "/src/python/test/device.key.pem",
"certfile": "/src/python/test/device.cert.pem"
}
keyORcert
for SAS
token:
credType = IOTConnectType.IOTC_CONNECT_SYMM_KEY
keyORcert = "xxxxxxxxxxxxxxx........"
setLogLevel
set logging level
device.setLogLevel(logLevel)
logLevel : (default value is IOTC_LOGGING_DISABLED
)
class IOTLogLevel:
IOTC_LOGGING_DISABLED = 1
IOTC_LOGGING_API_ONLY = 2
IOTC_LOGGING_ALL = 16
i.e. => device.setLogLevel(IOTLogLevel.IOTC_LOGGING_API_ONLY)
setExitOnError
enable/disable application termination on mqtt later exceptions. (default false)
device.setExitOnError(isEnabled)
i.e. => device.setExitOnError(True)
setModelData
set the device model data (if any)
device.setModelData(modelJSON)
modelJSON : Device model definition.
i.e. => device.setModelData({"iotcModelId":"PUT_MODEL_ID_HERE"})
setTokenExpiration
set the token expiration timeout. default is 21600 seconds (6 hours)
device.setTokenExpiration(totalSeconds)
totalSeconds : timeout in seconds.
i.e. => device.setTokenExpiration(600)
setServiceHost
set the service endpoint URL
device.setServiceHost(url)
url : URL for service endpoint. (default value is global.azure-devices-provisioning.net
)
call this before connect
setQosLevel
Set the MQTT Quality of Service (QoS) level desired for all MQTT publish calls
device.setQosLevel(qosLevel)
qosLevel : (default value is IOTC_QOS_AT_MOST_ONCE
)
class IOTQosLevel:
IOTC_QOS_AT_MOST_ONCE = 0
IOTC_QOS_AT_LEAST_ONCE = 1
Note: IOTC_QOS_AT_LEAST_ONCE will have slower performance than IOTC_QOS_AT_MOST_ONCE as the MQTT client must store the value for possible replay and also wait for an acknowledgement from the IoT Hub that the MQTT message has been received. Think of IOTC_QOS_AT_MOST_ONCE as "fire and forget" vs. IOTC_QOS_AT_LEAST_ONCE as "guaranteed delivery". As the developer you should consider the importance of 100% data delivery vs. increased connection time and data traffic over the data connection.
call this before connect
setCleanSession
set the clean session flag of the mqtt client
device.setCleanSession(value)
value : boolean flag to enable or disable clean session (default is True)
call this before connect
connect
connect device client # blocking
. Raises ConnectionStatus
event.
device.connect()
or
device.connect(hostName)
i.e. => device.connect()
sendTelemetry
send telemetry
device.sendTelemetry(payload, [[optional system properties]])
payload : A text payload.
i.e. => device.sendTelemetry('{ "temperature": 15 }')
You may also set system properties for the telemetry message. See also iothub message format
i.e. => device.sendTelemetry('{ "temperature":22 }', {"iothub-creation-time-utc": time.time()})
sendState
send device state
device.sendState(payload)
payload : A text payload.
i.e. => device.sendState('{ "status": "WARNING"}')
sendProperty
send reported property
device.sendProperty(payload)
payload : A text payload.
i.e. => device.sendProperty('{"countdown":{"value": %d}}')
doNext
let framework do the partial MQTT work.
device.doNext()
isConnected
returns whether the connection was established or not.
device.isConnected()
i.e. => device.isConnected()
disconnect
disconnect device client
device.disconnect()
i.e. => device.disconnect()
getDeviceSettings
pulls latest twin data (device properties). Raises SettingsUpdated
event.
device.getDeviceSettings()
i.e. => device.getDeviceSettings()
getHostName
returns the iothub hostname cached during the initial connection.
device.getHostName()
i.e. => device.getDeviceHostName()
on
set event callback to listen events
ConnectionStatus
: connection status has changedMessageSent
: message was sentCommand
: a command received from Azure IoT CentralSettingsUpdated
: device settings were updated
i.e.
def onconnect(info):
if info.getStatusCode() == 0:
print("connected!")
device.on("ConnectionStatus", onconnect)
def onmessagesent(info):
print("message sent -> " + info.getPayload())
device.on("MessageSent", onmessagesent)
def oncommand(info):
print("command name:", info.getTag())
print("command args: ", info.getPayload())
device.on("Command", oncommand)
def onsettingsupdated(info):
print("setting name:", info.getTag())
print("setting value: ", info.getPayload())
device.on("SettingsUpdated", onsettingsupdated)
callback info class
iotc
callbacks have a single argument derived from IOTCallbackInfo
.
Using this interface, you can get the callback details and respond back when it's necessary.
public members of IOTCallbackInfo
are;
getResponseCode()
: get response code or None
getResponseMessage()
: get response message or None
setResponse(responseCode, responseMessage)
: set callback response
i.e. => info.setResponse(200, 'completed')
getClient()
: get active device
client
getEventName()
: get the name of the event
getPayload()
: get the payload or None
getTag()
: get the tag or None
getStatusCode()
: get callback status code
sample app
import iotc
from iotc import IOTConnectType, IOTLogLevel
from random import randint
deviceId = "DEVICE_ID"
scopeId = "SCOPE_ID"
deviceKey = "DEVICE_KEY"
# see iotc.Device documentation above for x509 argument sample
iotc = iotc.Device(scopeId, deviceKey, deviceId, IOTConnectType.IOTC_CONNECT_SYMM_KEY)
iotc.setLogLevel(IOTLogLevel.IOTC_LOGGING_API_ONLY)
iotc.setQosLevel(IOTQosLevel.IOTC_QOS_AT_MOST_ONCE)
gCanSend = False
gCounter = 0
def onconnect(info):
global gCanSend
print("- [onconnect] => status:" + str(info.getStatusCode()))
if info.getStatusCode() == 0:
if iotc.isConnected():
gCanSend = True
elif info.getStatusCode() == 5: # token expired. force reconnection
gCanSend = False
iotc.connect()
def onmessagesent(info):
print("\t- [onmessagesent] => " + str(info.getPayload()))
def oncommand(info):
print("command name:", info.getTag())
print("command value: ", info.getPayload())
def onsettingsupdated(info):
print("setting name:", info.getTag())
print("setting value: ", info.getPayload())
iotc.on("ConnectionStatus", onconnect)
iotc.on("MessageSent", onmessagesent)
iotc.on("Command", oncommand)
iotc.on("SettingsUpdated", onsettingsupdated)
iotc.connect()
while iotc.isConnected():
iotc.doNext() # do the async work needed to be done for MQTT
if gCanSend == True:
if gCounter % 20 == 0:
gCounter = 0
print("Sending telemetry..")
iotc.sendTelemetry("{\"temp\": " + str(randint(20, 45)) + "}")
gCounter += 1
Project details
Release history Release notifications | RSS feed
Download files
Download the file for your platform. If you're not sure which to choose, learn more about installing packages.