|
| 1 | +--- |
| 2 | +title: Azure IoT Hub module identity & module twin (Azure CLI) |
| 3 | +description: Learn how to create a module identity and update a module twin using Azure CLI. |
| 4 | +author: kgremban |
| 5 | +ms.author: kgremban |
| 6 | +ms.service: iot-hub |
| 7 | +services: iot-hub |
| 8 | +ms.date: 02/17/2023 |
| 9 | +ms.devlang: azurecli |
| 10 | +ms.topic: conceptual |
| 11 | +ms.custom: mqtt, devx-track-azurecli |
| 12 | +--- |
| 13 | + |
| 14 | +# Get started with IoT Hub module identities and module twins using Azure CLI |
| 15 | + |
| 16 | +[!INCLUDE [iot-hub-selector-module-twin-getstarted](../../includes/iot-hub-selector-module-twin-getstarted.md)] |
| 17 | + |
| 18 | +[Module identities and module twins](iot-hub-devguide-module-twins.md) are similar to Azure IoT Hub device identities and device twins, but provide finer granularity. Just as Azure IoT Hub device identities and device twins enable a back-end application to configure a device and provide visibility on the device's conditions, module identities and module twins provide these capabilities for the individual components of a device. On capable devices with multiple components, such as operating system devices or firmware devices, module identities and module twins allow for isolated configuration and conditions for each component. |
| 19 | + |
| 20 | +[!INCLUDE [iot-hub-basic](../../includes/iot-hub-basic-whole.md)] |
| 21 | + |
| 22 | +This article shows you how to create an Azure CLI session in which you: |
| 23 | + |
| 24 | +* Create a device identity, then create a module identity for that device. |
| 25 | + |
| 26 | +* Update a set of desired properties for the module twin associated with the module identity. |
| 27 | + |
| 28 | +## Prerequisites |
| 29 | + |
| 30 | +* Azure CLI. You can also run the commands in this article using the [Azure Cloud Shell](/azure/cloud-shell/overview), an interactive CLI shell that runs in your browser or in an app such as Windows Terminal. If you use the Cloud Shell, you don't need to install anything. If you prefer to use the CLI locally, this article requires Azure CLI version 2.36 or later. Run `az --version` to find the version. To locally install or upgrade Azure CLI, see [Install Azure CLI](/cli/azure/install-azure-cli). |
| 31 | + |
| 32 | +* An IoT Hub. Create one with the [CLI](iot-hub-create-using-cli.md) or the [Azure portal](iot-hub-create-through-portal.md). |
| 33 | + |
| 34 | +* Make sure that port 8883 is open in your firewall. The samples in this article use MQTT protocol, which communicates over port 8883. This port can be blocked in some corporate and educational network environments. For more information and ways to work around this issue, see [Connecting to IoT Hub (MQTT)](iot-hub-mqtt-support.md#connecting-to-iot-hub). |
| 35 | + |
| 36 | +## Prepare the Cloud Shell |
| 37 | + |
| 38 | +If you want to use the Azure Cloud Shell, you must first launch and configure it. If you use the CLI locally, skip to the [Prepare a CLI session](#prepare-a-cli-session) section. |
| 39 | + |
| 40 | +1. Select the **Cloud Shell** icon from the page header in the Azure portal. |
| 41 | + |
| 42 | + :::image type="content" source="./media/quickstart-send-telemetry-cli/cloud-shell-button.png" alt-text="Screenshot of the global controls from the page header of the Azure portal, highlighting the Cloud Shell icon."::: |
| 43 | + |
| 44 | + > [!NOTE] |
| 45 | + > If this is the first time you've used the Cloud Shell, it prompts you to create storage, which is required to use the Cloud Shell. Select a subscription to create a storage account and Microsoft Azure Files share. |
| 46 | +
|
| 47 | +2. Use the environment selector in the Cloud Shell toolbar to select your preferred CLI environment. This article uses the **Bash** environment. You can also use the **PowerShell** environment. |
| 48 | + |
| 49 | + > [!NOTE] |
| 50 | + > Some commands require different syntax or formatting in the **Bash** and **PowerShell** environments. For more information, see [Tips for using the Azure CLI successfully](/cli/azure/use-cli-effectively?tabs=bash%2Cbash2). |
| 51 | +
|
| 52 | + :::image type="content" source="./media/quickstart-send-telemetry-cli/cloud-shell-environment.png" alt-text="Screenshot of an Azure Cloud Shell window, highlighting the environment selector in the toolbar."::: |
| 53 | + |
| 54 | +## Prepare a CLI session |
| 55 | + |
| 56 | +Next, you must prepare an Azure CLI session. If you're using the Cloud Shell, you run the session in a Cloud Shell tab. If using a local CLI client, you run the session in a CLI instance. |
| 57 | + |
| 58 | +1. If you're using the Cloud Shell, skip to the next step. Otherwise, run the [az login](/cli/azure/reference-index#az-login) command in the CLI session to sign in to your Azure account. |
| 59 | + |
| 60 | + If you're using the Cloud Shell, you're automatically signed into your Azure account. All communication between your Azure CLI session and your IoT hub is authenticated and encrypted. As a result, this article doesn't need extra authentication that you'd use with a real device, such as a connection string. For more information about signing in with Azure CLI, see [Sign in with Azure CLI](/cli/azure/authenticate-azure-cli). |
| 61 | + |
| 62 | + ```azurecli |
| 63 | + az login |
| 64 | + ``` |
| 65 | + |
| 66 | +1. In the CLI session, run the [az extension add](/cli/azure/extension#az-extension-add) command. The command adds the Microsoft Azure IoT Extension for Azure CLI to your CLI shell. The extension adds IoT Hub, IoT Edge, and IoT Device Provisioning Service (DPS) specific commands to Azure CLI. After you install the extension, you don't need to install it again in any Cloud Shell session. |
| 67 | + |
| 68 | + ```azurecli |
| 69 | + az extension add --name azure-iot |
| 70 | + ``` |
| 71 | + |
| 72 | + [!INCLUDE [iot-hub-cli-version-info](../../includes/iot-hub-cli-version-info.md)] |
| 73 | + |
| 74 | +## Create a device identity and module identity |
| 75 | + |
| 76 | +In this section, you create a device identity for your IoT hub in the CLI session, and then create a module identity using that device identity. You can create up to 50 module identities under each device identity. |
| 77 | + |
| 78 | +To create a device identity and module identity: |
| 79 | + |
| 80 | +1. In the CLI session, run the [az iot hub device-identity create](/cli/azure/iot/hub/device-identity#az-iot-hub-device-identity-create) command, replacing the following placeholders with their corresponding values. This command creates the device identity for your module. |
| 81 | + |
| 82 | + *{DeviceName}*. The name of your device. |
| 83 | + |
| 84 | + *{HubName}*. The name of your IoT hub. |
| 85 | + |
| 86 | + ```azurecli |
| 87 | + az iot hub device-identity create --device-id {DeviceName} --hub-name {HubName} |
| 88 | + ``` |
| 89 | +
|
| 90 | +1. In the CLI session, run the [az iot hub module-identity create](/cli/azure/iot/hub/module-identity#az-iot-hub-module-identity-create) command, replacing the following placeholders with their corresponding values. This command creates the module identity for your module, under the device identity you created in the previous step. |
| 91 | +
|
| 92 | + *{DeviceName}*. The name of your device. |
| 93 | +
|
| 94 | + *{HubName}*. The name of your IoT hub. |
| 95 | +
|
| 96 | + *{ModuleName}*. The name of your device's module. |
| 97 | +
|
| 98 | + ```azurecli |
| 99 | + az iot hub module-identity create --device-id {DeviceName} --hub-name {HubName} \ |
| 100 | + --module-id {ModuleName} |
| 101 | + ``` |
| 102 | +
|
| 103 | +## Update the module twin |
| 104 | +
|
| 105 | +Once a module identity is created, a module twin is implicitly created in IoT Hub. In this section, you use the CLI session to update a set of desired properties on the module twin associated with the module identity you created in the previous section. |
| 106 | +
|
| 107 | +1. In the CLI session, run the [az iot hub module-twin update](/cli/azure/iot/hub/module-twin#az-iot-hub-module-twin-update) command, replacing the following placeholders with their corresponding values. In this example, we're updating multiple desired properties on the module twin for the module identity we created in the previous section. |
| 108 | +
|
| 109 | + *{DeviceName}*. The name of your device. |
| 110 | +
|
| 111 | + *{HubName}*. The name of your IoT hub. |
| 112 | +
|
| 113 | + *{ModuleName}*. The name of your device's module. |
| 114 | +
|
| 115 | + ```azurecli |
| 116 | + az iot hub module-twin update --device-id {DeviceName} --hub-name {HubName} \ |
| 117 | + --module-id {ModuleName} \ |
| 118 | + --desired '{"conditions":{"temperature":{"warning":75, "critical":100}}}' |
| 119 | + ``` |
| 120 | +
|
| 121 | +1. In the CLI session, confirm that the JSON response shows the results of the update operation. In the following JSON response example, we used `SampleDevice` and `SampleModule` for the `{DeviceName}` and `{ModuleName}` placeholders, respectively, in the `az iot hub module-twin update` CLI command. |
| 122 | +
|
| 123 | + ```json |
| 124 | + { |
| 125 | + "authenticationType": "sas", |
| 126 | + "capabilities": null, |
| 127 | + "cloudToDeviceMessageCount": 0, |
| 128 | + "connectionState": "Disconnected", |
| 129 | + "deviceEtag": "Mzg0OEN1NzW=", |
| 130 | + "deviceId": "SampleDevice", |
| 131 | + "deviceScope": null, |
| 132 | + "etag": "AAAAAAAAAAI=", |
| 133 | + "lastActivityTime": "0001-01-01T00:00:00+00:00", |
| 134 | + "modelId": "", |
| 135 | + "moduleId": "SampleModule", |
| 136 | + "parentScopes": null, |
| 137 | + "properties": { |
| 138 | + "desired": { |
| 139 | + "$metadata": { |
| 140 | + "$lastUpdated": "2023-02-17T21:26:10.5835633Z", |
| 141 | + "$lastUpdatedVersion": 2, |
| 142 | + "conditions": { |
| 143 | + "$lastUpdated": "2023-02-17T21:26:10.5835633Z", |
| 144 | + "$lastUpdatedVersion": 2, |
| 145 | + "temperature": { |
| 146 | + "$lastUpdated": "2023-02-17T21:26:10.5835633Z", |
| 147 | + "$lastUpdatedVersion": 2, |
| 148 | + "critical": { |
| 149 | + "$lastUpdated": "2023-02-17T21:26:10.5835633Z", |
| 150 | + "$lastUpdatedVersion": 2 |
| 151 | + }, |
| 152 | + "warning": { |
| 153 | + "$lastUpdated": "2023-02-17T21:26:10.5835633Z", |
| 154 | + "$lastUpdatedVersion": 2 |
| 155 | + } |
| 156 | + } |
| 157 | + } |
| 158 | + }, |
| 159 | + "$version": 2, |
| 160 | + "conditions": { |
| 161 | + "temperature": { |
| 162 | + "critical": 100, |
| 163 | + "warning": 75 |
| 164 | + } |
| 165 | + } |
| 166 | + }, |
| 167 | + "reported": { |
| 168 | + "$metadata": { |
| 169 | + "$lastUpdated": "0001-01-01T00:00:00Z" |
| 170 | + }, |
| 171 | + "$version": 1 |
| 172 | + } |
| 173 | + }, |
| 174 | + "status": "enabled", |
| 175 | + "statusReason": null, |
| 176 | + "statusUpdateTime": "0001-01-01T00:00:00+00:00", |
| 177 | + "tags": null, |
| 178 | + "version": 3, |
| 179 | + "x509Thumbprint": { |
| 180 | + "primaryThumbprint": null, |
| 181 | + "secondaryThumbprint": null |
| 182 | + } |
| 183 | + } |
| 184 | + ``` |
| 185 | +
|
| 186 | +## Next steps |
| 187 | +
|
| 188 | +To learn how to use Azure CLI to extend your IoT solution and schedule updates on devices, see [Schedule and broadcast jobs](schedule-jobs-cli.md). |
| 189 | +
|
| 190 | +To continue getting started with IoT Hub and device management patterns, such as end-to-end image-based update, see [Device Update for Azure IoT Hub article using the Raspberry Pi 3 B+ Reference Image](../iot-hub-device-update/device-update-raspberry-pi.md). |
0 commit comments