Skip to main content

Microsoft Azure IoT Device Library

Project description

Azure IoT Device SDK

The Azure IoT Device SDK for Python provides functionality for communicating with the Azure IoT Hub for both Devices and Modules.

Note that this SDK is currently in preview, and is subject to change.

Features

The SDK provides the following clients:

  • Provisioning Device Client

    • Creates a device identity on the Azure IoT Hub
  • IoT Hub Device Client

    • Send telemetry messages to Azure IoT Hub
    • Receive Cloud-to-Device (C2D) messages from the Azure IoT Hub
    • Receive and respond to direct method invocations from the Azure IoT Hub
  • IoT Hub Module Client

    • Supports Azure IoT Edge Hub and Azure IoT Hub
    • Send telemetry messages to a Hub or to another Module
    • Receive Input messages from a Hub or other Modules
    • Receive and respond to direct method invocations from a Hub or other Modules

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.

Python Version Asynchronous API Synchronous API
Python 3.5.3+ YES YES
Python 3.4 NO YES
Python 2.7 NO YES

Installation

pip install azure-iot-device

Set up an IoT Hub and create a Device Identity

  1. Install the Azure CLI (or use the Azure Cloud Shell) and use it to create an Azure IoT Hub.

    az iot hub create --resource-group <your resource group> --name <your IoT Hub name>
    
    • Note that this operation make take a few minutes.
  2. Add the IoT Extension to the Azure CLI, and then register a device identity

    az extension add --name azure-cli-iot-ext
    az iot hub device-identity create --hub-name <your IoT Hub name> --device-id <your device id>
    
  3. Retrieve your Device Connection String using the Azure CLI

    az iot hub device-identity show-connection-string --device-id <your device id> --hub-name <your IoT Hub name>
    

    It should be in the format:

    HostName=<your IoT Hub name>.azure-devices.net;DeviceId=<your device id>;SharedAccessKey=<some value>
    

Send a simple telemetry message

  1. Begin monitoring for telemetry on your IoT Hub using the Azure CLI

    az iot hub monitor-events --hub-name <your IoT Hub name> --output table
    
  2. On your device, set the Device Connection String as an enviornment variable called IOTHUB_DEVICE_CONNECTION_STRING.

    Windows

    set IOTHUB_DEVICE_CONNECTION_STRING=<your connection string here>
    
    • Note that there are NO quotation marks around the connection string.

    Linux

    export IOTHUB_DEVICE_CONNECTION_STRING="<your connection string here>"
    
  3. Copy the following code that sends a single message to the IoT Hub into a new python file on your device, and run it from the terminal or IDE (requires Python 3.7+):

    import asyncio
    import os
    from azure.iot.device.aio import IoTHubDeviceClient
    
    
    async def main():
        # Fetch the connection string from an enviornment variable
        conn_str = os.getenv("IOTHUB_DEVICE_CONNECTION_STRING")
    
        # Create instance of the device client using the connection string
        device_client = IoTHubDeviceClient.create_from_connection_string(conn_str)
    
        # Send a single message
        print("Sending message...")
        await device_client.send_message("This is a message that is being sent")
        print("Message successfully sent!")
    
        # finally, disconnect
        await device_client.disconnect()
    
    
    if __name__ == "__main__":
        asyncio.run(main())
    
  4. Check the Azure CLI output to verify that the message was received by the IoT Hub. You should see the following output:

    Starting event monitor, use ctrl-c to stop...
    event:
      origin: <your Device name>
      payload: This is a message that is being sent
    
  5. Your device is now able to connect to Azure IoT Hub!

Additional Samples

Check out the samples repository for example code showing how the SDK can be used in a variety of scenarios, including:

  • Sending multiple telemetry messages at once.
  • Receiving Cloud-to-Device messages.
  • Using Edge Modules with the Azure IoT Edge Hub.
  • Send and receive updates to device twin
  • Receive invocations to direct methods
  • Register a device with the Device Provisioning Service
  • Legacy scenarios for Python 2.7 and 3.4

Getting help and finding API docs

Our SDK makes use of docstrings which means you cand find API documentation directly through Python with use of the help command:

>>> from azure.iot.device import IoTHubDeviceClient
>>> help(IoTHubDeviceClient)

Project details


Download files

Download the file for your platform. If you're not sure which to choose, learn more about installing packages.

Files for azure-iot-device, version 2.0.0rc11
Filename, size File type Python version Upload date Hashes
Filename, size azure_iot_device-2.0.0rc11-py2.py3-none-any.whl (212.0 kB) File type Wheel Python version py2.py3 Upload date Hashes View hashes
Filename, size azure-iot-device-2.0.0rc11.tar.gz (146.0 kB) File type Source Python version None Upload date Hashes View hashes

Supported by

Elastic Elastic Search Pingdom Pingdom Monitoring Google Google BigQuery Sentry Sentry Error logging AWS AWS Cloud computing DataDog DataDog Monitoring Fastly Fastly CDN SignalFx SignalFx Supporter DigiCert DigiCert EV certificate StatusPage StatusPage Status page