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
Automatic device management in Azure IoT Hub automates many of the repetitive and complex tasks of managing large device fleets. With automatic device management, you can target a set of devices based on their properties, define a desired configuration, and then let IoT Hub update the devices when they come into scope. This update is done using an _automatic device configuration_, which lets you summarize completion and compliance, handle merging and conflicts, and roll out configurations in a phased approach.
17
+
Automatic device management in Azure IoT Hub automates many of the repetitive and complex tasks of managing large device fleets. With automatic device management, you can target a set of devices based on their properties, define a desired configuration, and then let IoT Hub update the devices when they come into scope. This update is done using an _automatic device configuration_ or _automatic module configuration_, which lets you summarize completion and compliance, handle merging and conflicts, and roll out configurations in a phased approach.
Automatic device management works by updating a set of device twins with desired properties and reporting a summary that's based on device twin reported properties. It introduces a new class and JSON document called a *Configuration* that has three parts:
21
+
Automatic device management works by updating a set of device twins or module twins with desired properties and reporting a summary that's based on twin reported properties. It introduces a new class and JSON document called a *Configuration* that has three parts:
22
22
23
-
* The **target condition** defines the scope of device twins to be updated. The target condition is specified as a query on device twin tags and/or reported properties.
23
+
* The **target condition** defines the scope of device twins or module twins to be updated. The target condition is specified as a query on device twin tags and/or reported properties.
24
24
25
-
* The **target content** defines the desired properties to be added or updated in the targeted device twins. The content includes a path to the section of desired properties to be changed.
25
+
* The **target content** defines the desired properties to be added or updated in the targeted device twins or module twins. The content includes a path to the section of desired properties to be changed.
26
26
27
-
* The **metrics** define the summary counts of various configuration states such as **Success**, **In Progress**, and **Error**. Custom metrics are specified as queries on device twin reported properties. System metrics are the default metrics that measure twin update status, such as the number of device twins that are targeted and the number of twins that have been successfully updated.
27
+
* The **metrics** define the summary counts of various configuration states such as **Success**, **In Progress**, and **Error**. Custom metrics are specified as queries on twin reported properties. System metrics are the default metrics that measure twin update status, such as the number of twins that are targeted and the number of twins that have been successfully updated.
28
28
29
-
Automatic device configurations run for the first time shortly after the configuration is created and then at five minute intervals. Metrics queries run each time the automatic device configuration runs.
29
+
Automatic configurations run for the first time shortly after the configuration is created and then at five minute intervals. Metrics queries run each time the automatic configuration runs.
30
30
31
31
## CLI prerequisites
32
32
33
33
* An [IoT hub](../iot-hub/iot-hub-create-using-cli.md) in your Azure subscription.
34
34
*[Azure CLI](https://docs.microsoft.com/cli/azure/install-azure-cli) in your environment. At a minimum, your Azure CLI version must be 2.0.24 or above. Use `az –-version` to validate. This version supports az extension commands and introduces the Knack command framework.
35
35
* The [IoT extension for Azure CLI](https://github.com/Azure/azure-iot-cli-extension).
36
36
37
-
## Implement device twins to configure devices
37
+
## Implement twins
38
38
39
-
Automatic device configurations require the use of device twins to synchronize state between the cloud and devices. Refer to [Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md) for guidance on using device twins.
39
+
Automatic device configurations require the use of device twins to synchronize state between the cloud and devices. For more information, see [Understand and use device twins in IoT Hub](iot-hub-devguide-device-twins.md).
40
40
41
-
## Identify devices using tags
41
+
Automatic module configurations require the use of module twins to synchronize state between the cloud and modules. For more information, see [Understand and use module twins in IoT Hub](iot-hub-devguide-module-twins.md).
42
42
43
-
Before you create a configuration, you must specify which devices you want to affect. Azure IoT Hub identifies devices using tags in the device twin. Each device can have multiple tags, and you can define them any way that makes sense for your solution. For example, if you manage devices in different locations, add the following tags to a device twin:
43
+
## Use tags to target twins
44
+
45
+
Before you create a configuration, you must specify which devices or modules you want to affect. Azure IoT Hub identifies devices and using tags in the device twin, and identifies modules using tags in the module twin. Each device or modules can have multiple tags, and you can define them any way that makes sense for your solution. For example, if you manage devices in different locations, add the following tags to a device twin:
44
46
45
47
```json
46
48
"tags": {
@@ -53,9 +55,9 @@ Before you create a configuration, you must specify which devices you want to af
53
55
54
56
## Define the target content and metrics
55
57
56
-
The target content and metric queries are specified as JSON documents that describe the device twin desired properties to set and reported properties to measure. To create an automatic device configuration using Azure CLI, save the target content and metrics locally as .txt files. You use the file paths in a later section when you run the command to apply the configuration to your device.
58
+
The target content and metric queries are specified as JSON documents that describe the device twin or module twin desired properties to set and reported properties to measure. To create an automatic configuration using Azure CLI, save the target content and metrics locally as .txt files. You use the file paths in a later section when you run the command to apply the configuration to your device.
57
59
58
-
Here's a basic target content sample:
60
+
Here's a basic target content sample for an automatic device configuration:
59
61
60
62
```json
61
63
{
@@ -69,14 +71,38 @@ Here's a basic target content sample:
69
71
}
70
72
```
71
73
74
+
Automatic module configurations behave very similarly, but you target `moduleContent` instead of `deviceContent`.
75
+
76
+
```json
77
+
{
78
+
"content": {
79
+
"moduleContent": {
80
+
"properties.desired.chillerWaterSettings": {
81
+
"temperature": 38,
82
+
"pressure": 78
83
+
}
84
+
}
85
+
}
86
+
```
87
+
72
88
Here are examples of metric queries:
73
89
74
90
```json
75
91
{
76
92
"queries": {
77
-
"Compliant": "select deviceId from devices where configurations.[[chillersettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
78
-
"Error": "select deviceId from devices where configurations.[[chillersettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
79
-
"Pending": "select deviceId from devices where configurations.[[chillersettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
93
+
"Compliant": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'",
94
+
"Error": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='error'",
95
+
"Pending": "select deviceId from devices where configurations.[[chillerdevicesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='pending'"
96
+
}
97
+
}
98
+
```
99
+
100
+
Metric queries for modules are also similar to queries for devices, but you select for `moduleId` from `devices.modules`. For example:
101
+
102
+
```json
103
+
{
104
+
"queries": {
105
+
"Compliant": "select deviceId, moduleId from devices.module where configurations.[[chillermodulesettingswashington]].status = 'Applied' AND properties.reported.chillerWaterSettings.status='current'"
80
106
}
81
107
}
82
108
```
@@ -102,11 +128,11 @@ Use the following command to create a configuration:
102
128
103
129
* --**hub-name** - Name of the IoT hub in which the configuration will be created. The hub must be in the current subscription. Switch to the desired subscription with the command `az account set -s [subscription name]`
104
130
105
-
* --**target-condition** - Enter a target condition to determine which devices will be targeted with this configuration. The condition is based on device twin tags or device twin desired properties and should match the expression format. For example, `tags.environment='test'` or `properties.desired.devicemodel='4000x'`.
131
+
* --**target-condition** - Enter a target condition to determine which devices or modules will be targeted with this configuration. For automatic device configuration, the condition is based on device twin tags or device twin desired properties and should match the expression format. For example, `tags.environment='test'` or `properties.desired.devicemodel='4000x'`. For automatic module configuration, the condition is based on module twin tags or module twin desired properties.. For example, `from devices.modules where tags.environment='test'` or `from devices.modules where properties.reported.chillerProperties.model='4000x'`.
106
132
107
-
* --**priority** - A positive integer. In the event that two or more configurations are targeted at the same device, the configuration with the highest numerical value for Priority will apply.
133
+
* --**priority** - A positive integer. In the event that two or more configurations are targeted at the same device or module, the configuration with the highest numerical value for Priority will apply.
108
134
109
-
* --**metrics** - Filepath to the metric queries. Metrics provide summary counts of the various states that a device may report back after applying configuration content. For example, you may create a metric for pending settings changes, a metric for errors, and a metric for successful settings changes.
135
+
* --**metrics** - Filepath to the metric queries. Metrics provide summary counts of the various states that a device or module may report back after applying configuration content. For example, you may create a metric for pending settings changes, a metric for errors, and a metric for successful settings changes.
110
136
111
137
## Monitor a configuration
112
138
@@ -123,13 +149,13 @@ az iot hub configuration show --config-id [configuration id] \
123
149
124
150
Inspect the configuration in the command window. The **metrics** property lists a count for each metric that is evaluated by each hub:
125
151
126
-
***targetedCount** - A system metric that specifies the number of device twins in IoT Hub that match the targeting condition.
152
+
* **targetedCount** - A system metric that specifies the number of device twins or module twins in IoT Hub that match the targeting condition.
127
153
128
-
***appliedCount** - A system metric specifies the number of devices that have had the target content applied.
154
+
* **appliedCount** - A system metric specifies the number of devices or modules that have had the target content applied.
129
155
130
156
* **Your custom metric** - Any metrics you've defined are user metrics.
131
157
132
-
You can show a list of device IDs or objects for each of the metrics by using the following command:
158
+
You can show a list of device IDs, module IDs, or objects for each of the metrics by using the following command:
133
159
134
160
```cli
135
161
az iot hub configuration show-metric --config-id [configuration id] \
* --**config-id** - The name of the deployment that exists in the IoT hub.
140
166
141
-
* --**metric-id** - The name of the metric for which you want to see the list of device IDs, for example `appliedCount`.
167
+
* --**metric-id** - The name of the metric for which you want to see the list of device IDs or module IDs, for example `appliedCount`.
142
168
143
169
* --**hub-name** - Name of the IoT hub in which the deployment exists. The hub must be in the current subscription. Switch to the desired subscription with the command `az account set -s [subscription name]`.
144
170
@@ -150,11 +176,11 @@ When you modify a configuration, the changes immediately replicate to all target
150
176
151
177
If you update the target condition, the following updates occur:
152
178
153
-
* If a device twin didn't meet the old target condition, but meets the new target condition and this configuration is the highest priority for that device twin, then this configuration is applied to the device twin.
179
+
* If a twin didn't meet the old target condition, but meets the new target condition and this configuration is the highest priority for that twin, then this configuration is applied.
154
180
155
-
* If a device twin no longer meets the target condition, the settings from the configuration will be removed and the device twin will be modified by the next highest priority configuration.
181
+
* If a twin currently running this configuration no longer meets the target condition, the settings from the configuration will be removed and the twin will be modified by the next highest priority configuration.
156
182
157
-
* If a device twin currently running this configuration no longer meets the target condition and doesn't meet the target condition of any other configurations, then the settings from the configuration will be removed and no other changes will be made on the twin.
183
+
* If a twin currently running this configuration no longer meets the target condition and doesn't meet the target condition of any other configurations, then the settings from the configuration will be removed and no other changes will be made on the twin.
158
184
159
185
Use the following command to update a configuration:
When you delete a configuration, any device twins take on their next highest priority configuration. If device twins don't meet the target condition of any other configuration, then no other settings are applied.
206
+
When you delete a configuration, any device twins or module twins take on their next highest priority configuration. If twins don't meet the target condition of any other configuration, then no other settings are applied.
181
207
182
208
Use the following command to delete a configuration:
0 commit comments