Metadata-Version: 2.1
Name: azure-iot-hub
Version: 2.0.0rc1
Summary: Microsoft Azure IoTHub Service Library
Home-page: https://github.com/Azure/azure-iot-sdk-python/tree/master/azure-iot-hub
Author: Microsoft Corporation
Author-email: opensource@microsoft.com
License: MIT License
Platform: UNKNOWN
Classifier: Development Status :: 3 - Alpha
Classifier: Intended Audience :: Developers
Classifier: Topic :: Software Development :: Libraries :: Python Modules
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 2
Classifier: Programming Language :: Python :: 2.7
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.4
Classifier: Programming Language :: Python :: 3.5
Classifier: Programming Language :: Python :: 3.6
Classifier: Programming Language :: Python :: 3.7
Requires-Python: >=2.7, !=3.0.*, !=3.1.*, !=3.2.*, !=3.3*, <4
Description-Content-Type: text/markdown
Requires-Dist: msrest

# Azure IoTHub Service  SDK

The Azure IoTHub Service SDK for Python provides functionality for communicating with the Azure IoT Hub.

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

## Features

The SDK provides the following clients:

* ### IoT Hub Registry Manager

  * Provides CRUD operations for device on IoTHub
  * Get statistics about the IoTHub service and devices

* ### Digital Twin Service Client

  * Read and update Digital Twin
  * Read Digital Twin Interface Instances
  * Read Model

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 | Synchronous API |
| -------------- | --------------- |
| Python 3.5.3+  | **YES**         |
| Python 3.4     | **YES**         |
| Python 2.7     | **YES**         |

## Installation

```python
pip install azure-iot-hub
```

## Set up an IoT Hub

1. Install the [Azure CLI](https://docs.microsoft.com/en-us/cli/azure/install-azure-cli?view=azure-cli-latest) (or use the [Azure Cloud Shell](https://shell.azure.com/)) and use it to [create an Azure IoT Hub](https://docs.microsoft.com/en-us/cli/azure/iot/hub?view=azure-cli-latest#az-iot-hub-create).

```bash
az iot hub create --resource-group <your resource group> --name <your IoT Hub name>
```

* Note that this operation make take a few minutes.

## How to use the IoTHub Registry Manager

* ### Create an IoTHubRegistryManager

```python
registry_manager = IoTHubRegistryManager(iothub_connection_str)
```

* ### Create a device

```python
new_device = registry_manager.create_device_with_sas(device_id, primary_key, secondary_key, device_state)
```

* ### Read device information

```python
device = registry_manager.get_device(device_id)
```

* ### Update device information

```python
device_updated = registry_manager.update_device_with_sas(
    device_id, etag, primary_key, secondary_key, device_state)
```

* ### Delete device

```python
registry_manager.delete_device(device_id)
```

* ### Get service statistics

```python
registry_statistics = registry_manager.get_service_statistics()
```

* ### Get device registry statistics

```python
registry_statistics = registry_manager.get_device_registry_statistics()
```

## How to use the Digital Twin Service Client

* ### Create an DigitalTwinServiceClient

```python
digital_twin_service_client = DigitalTwinServiceClient(iothub_connection_str)
```

* ### Get DigitalTwin of a particular device

```python
digital_twin = digital_twin_service_client.get_digital_twin(device_id)
```

* ### Get a DigitalTwin Interface Instance

```python
digital_twin_interface_instance = digital_twin_service_client.get_digital_twin_interface_instance(
    device_id, interface_instance_name
)
```

* ### Update DigitalTwin with a patch

```python
digital_twin_updated = digital_twin_service_client.update_digital_twin(device_id, patch, etag)
```

* ### Update a DigitalTwin property by name

```python
digital_twin_service_client.update_digital_twin_property(
    device_id, interface_instance_name, property_name, property_value
)
```

* ### Get a Model

```python
digital_twin_model = digital_twin_service_client.get_model(model_id)
```

## IoTHub Samples

Check out the [samples repository](https://github.com/Azure/azure-iot-sdk-python/tree/master/azure-iot-hub/samples) for more detailed samples

## Getting help and finding API docs

Our SDK makes use of docstrings which means you can find API documentation directly through Python with use of the [help](https://docs.python.org/3/library/functions.html#help) command:

```python
>>> from azure.iot.hub import IoTHubRegistryManager
>>> help(IoTHubRegistryManager)

>>> from azure.iot.hub import DigitalTwinServiceClient
>>> help(DigitalTwinServiceClient)
```


