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
This article shows an example implementation of the Contoso Virtual Vacuum component enumerator. You can reference this example to implement a custom component enumerator for your Internet of Things (IoT) devices. A *component* is an identity beneath the device level that has a composition relationship with the host device.
13
+
This article shows an example implementation of a Device Update for IoT Hub component enumerator. You can reference this example to implement a custom component enumerator for your IoT devices. A *component* is an identity beneath the device level that has a composition relationship with the host device.
14
14
15
-
## What is Contoso Virtual Vacuum?
15
+
This article demonstrates a component enumerator using a virtual IoT device called Contoso Virtual Vacuum. Component enumerators are used to implement the *proxy update* feature.
16
16
17
-
Contoso Virtual Vacuum is a virtual IoT device that we use to demonstrate the *proxy update* feature.
18
-
19
-
Proxy update enables updating multiple components on the same IoT device or multiple sensors connected to the IoT device with a single over-the-air deployment. Proxy update supports an installation order for updating components. It also supports multiple-step updating with pre-installation, installation, and post-installation capabilities.
17
+
Proxy update enables updating multiple components on the same IoT device or multiple sensors connected to the IoT device with a single over-the-air deployment. Proxy update supports an installation order for updating components. It also supports multiple-step updating with pre-installation, installation, and post-installation capabilities.
20
18
21
19
Use cases where proxy updates are applicable include:
22
20
23
21
- Targeting specific update files to partitions on the device.
24
22
- Targeting specific update files to apps or components on the device.
25
23
- Targeting specific update files to sensors connected to IoT devices over a network protocol (for example, USB or CAN bus).
26
24
27
-
The Device Update Agent runs on the host device. It can send each update to a specific component or to a group of components of the same hardware class (that is, requiring the same software or firmware update).
25
+
For more information, see [Proxy updates and multi-component updating](device-update-proxy-updates.md).
26
+
27
+
The Device Update agent runs on the host device. It can send each update to a specific component or to a group of components of the same hardware class (that is, requiring the same software or firmware update).
28
+
29
+
## What is a component enumerator?
30
+
31
+
A component enumerator is an extension for the Device Update agent that provides information about every component that you need for an over-the-air update via a host device's Azure IoT Hub connection.
32
+
33
+
The Device Update agent is device and component agnostic. By itself, the agent doesn't know anything about components on (or connected to) a host device at the time of the update.
34
+
35
+
To enable proxy updates, device builders must identify all the components on the device that can be updated and assign a unique name to each component. Also, a group name can be assigned to components of the same hardware class, so that the same update can be installed onto all components in the same group. Then, the update content handler can install and apply the update to the correct components.
36
+
37
+
:::image type="content" source="media/understand-device-update/contoso-virtual-vacuum-update-flow.svg" alt-text="Diagram that shows the proxy update flow." lightbox="media/understand-device-update/contoso-virtual-vacuum-update-flow.svg":::
38
+
39
+
Here are the responsibilities of each part of the proxy update flow:
40
+
41
+
-**Device builder**
42
+
43
+
- Design and build the device.
44
+
45
+
- Integrate the Device Update agent and its dependencies.
46
+
47
+
- Implement a device-specific component enumerator extension and register with the Device Update agent.
48
+
49
+
The component enumerator uses the information from a component inventory or a configuration file to augment static component data (Device Update required) with dynamic data (for example, firmware version, connection status, and hardware identity).
50
+
51
+
- Create a proxy update that contains one or more child updates that target one or more components on (or connected to) the device.
52
+
53
+
- Send the update to the solution operator.
54
+
55
+
-**Solution operator**
56
+
57
+
- Import the update and manifest to the Device Update service.
58
+
59
+
- Deploy the update to a group of devices.
60
+
61
+
-**Device Update agent**
62
+
63
+
- Get update information from IoT Hub via the device twin or module twin.
64
+
65
+
- Invoke a *steps handler* to process the proxy update intended for one or more components on the device.
66
+
67
+
The example in this article has two updates: `host-fw-1.1` and `motors-fw-1.1`. For each child update, the parent steps handler invokes a child steps handler to enumerate all components that match the `Compatibilities` properties specified in the child update's manifest file. Next, the handler downloads, installs, and applies the child update to all targeted components.
68
+
69
+
To get the matching components, the child update calls a `SelectComponents` API provided by the component enumerator. If there are no matching components, the child update is skipped.
70
+
71
+
- Collect all update results from parent and child updates, and report those results to IoT Hub.
72
+
73
+
-**Child steps handler**
74
+
75
+
- Iterate through a list of component instances that are compatible with the child update content. For more information, see [Steps handler](https://github.com/Azure/iot-hub-device-update/tree/main/src/content_handlers/steps_handler).
76
+
77
+
In production, device builders can use [existing handlers](https://github.com/Azure/iot-hub-device-update/tree/main/src/content_handlers) or implement a custom handler that invokes any installer needed for an over-the-air update. For more information, see [Implement a custom update content handler](https://github.com/Azure/iot-hub-device-update/tree/main/docs/agent-reference/how-to-implement-custom-update-handler.md).
28
78
29
79
## Virtual Vacuum components
30
80
31
-
For this demonstration, Contoso Virtual Vacuum consists of five logical components:
81
+
For this article, we use a virtual IoT device to demonstrate the key concepts and features. The Contoso Virtual Vacuum device consists of five logical components:
32
82
33
83
- Host firmware
34
84
- Host boot file system
@@ -38,7 +88,7 @@ For this demonstration, Contoso Virtual Vacuum consists of five logical componen
38
88
39
89
:::image type="content" source="media/understand-device-update/contoso-virtual-vacuum-components-diagram.svg" alt-text="Diagram that shows the Contoso Virtual Vacuum components." lightbox="media/understand-device-update/contoso-virtual-vacuum-components-diagram.svg":::
40
90
41
-
We used the following directory structure to simulate the components:
91
+
The following directory structure simulates the components:
42
92
43
93
```sh
44
94
/usr/local/contoso-devices/vacuum-1/hostfw
@@ -53,8 +103,7 @@ We used the following directory structure to simulate the components:
53
103
54
104
Each component's directory contains a JSON file that stores a mock software version number of each component. Example JSON files are *firmware.json* and *diskimage.json*.
55
105
56
-
> [!NOTE]
57
-
> For this demo, to update the components' firmware, we'll copy *firmware.json* or *diskimage.json* (update payload) to the targeted components' directory.
106
+
For this demo, to update the components' firmware, we'll copy *firmware.json* or *diskimage.json* (update payload) to the targeted components' directory.
58
107
59
108
Here's an example *firmware.json* file:
60
109
@@ -66,46 +115,9 @@ Here's an example *firmware.json* file:
66
115
```
67
116
68
117
> [!NOTE]
69
-
> Contoso Virtual Vacuum contains software or firmware versions for the purpose of demonstrating proxy update. It doesn't provide any other functionality.
70
-
71
-
## What is a component enumerator?
72
-
73
-
A component enumerator is a Device Update Agent extension that provides information about every component that you need for an over-the-air update via a host device's Azure IoT Hub connection.
74
-
75
-
The Device Update Agent is device and component agnostic. By itself, the agent doesn't know anything about components on (or connected to) a host device at the time of the update.
76
-
77
-
To enable proxy updates, device builders must identify all updateable components on the device and assign a unique name to each component. Also, a group name can be assigned to components of the same hardware class, so that the same update can be installed onto all components in the same group. The update content handler can then install and apply the update to the correct components.
78
-
79
-
:::image type="content" source="media/understand-device-update/contoso-virtual-vacuum-update-flow.svg" alt-text="Diagram that shows the proxy update flow." lightbox="media/understand-device-update/contoso-virtual-vacuum-update-flow.svg":::
80
-
81
-
Here are the responsibilities of each part of the proxy update flow:
82
-
83
-
-**Device builder**
84
-
- Design and build the device.
85
-
- Integrate the Device Update Agent and its dependencies.
86
-
- Implement a device-specific component enumerator extension and register with the Device Update Agent.
87
-
88
-
The component enumerator uses the information from a component inventory or a configuration file to augment static component data (Device Update required) with dynamic data (for example, firmware version, connection status, and hardware identity).
89
-
- Create a proxy update that contains one or more child updates that target one or more components on (or connected to) the device.
90
-
- Send the update to the solution operator.
91
-
-**Solution operator**
92
-
- Import the update (and manifest) to the Device Update service.
93
-
- Deploy the update to a group of devices.
94
-
-**Device Update Agent**
95
-
- Get update information from Azure IoT Hub (via device twin or module twin).
96
-
- Invoke a *steps handler* to process the proxy update intended for one or more components on the device.
97
-
98
-
This example has two updates: `host-fw-1.1` and `motors-fw-1.1`. For each child update, the parent steps handler invokes a child steps handler to enumerate all components that match the `Compatibilities` properties specified in the child update's manifest file. Next, the handler downloads, installs, and applies the child update to all targeted components.
99
-
100
-
To get the matching components, the child update calls a `SelectComponents` API provided by the component enumerator. If there are no matching components, the child update is skipped.
101
-
- Collect all update results from parent and child updates, and report those results to Azure IoT Hub.
102
-
-**Child steps handler**
103
-
- Iterate through a list of component instances that are compatible with the child update content. For more information, see [Steps handler](https://github.com/Azure/iot-hub-device-update/tree/main/src/content_handlers/steps_handler).
104
-
105
-
106
-
In production, device builders can use [existing handlers](https://github.com/Azure/iot-hub-device-update/tree/main/src/content_handlers) or implement a custom handler that invokes any installer needed for an over-the-air update. For more information, see [Implement a custom update content handler](https://github.com/Azure/iot-hub-device-update/tree/main/docs/agent-reference/how-to-implement-custom-update-handler.md).
118
+
> Contoso Virtual Vacuum contains software or firmware versions for the purpose of demonstrating proxy update. It doesn't provide any other functionality.
107
119
108
-
## Implement a component enumerator for the Device Update Agent (C language)
120
+
## Implement a component enumerator (C language)
109
121
110
122
### Requirements
111
123
@@ -124,13 +136,13 @@ The `ComponentInfo` JSON string must include the following properties:
124
136
| Name | Type | Description |
125
137
|---|---|---|
126
138
|`id`| string | A component's unique identity (device scope). Examples include hardware serial number, disk partition ID, and unique file path of the component.|
127
-
|`name`| string| A component's logical name. This is the name that a device builder assigns to a component that's available in every device of the same `device` class.<br/><br/>For example, every Contoso Virtual Vacuum device contains a motor that drives a left wheel. Contoso assigned *left motor* as a common (logical) name for this motor to easily refer to this component, instead of hardware ID, which can be globally unique.|
139
+
|`name`| string| A component's logical name. This property is the name that a device builder assigns to a component that's available in every device of the same `device` class.<br/><br/>For example, every Contoso Virtual Vacuum device contains a motor that drives a left wheel. Contoso assigned *left motor* as a common (logical) name for this motor to easily refer to this component, instead of hardware ID, which can be globally unique.|
128
140
|`group`|string|A group that this component belongs to.<br/><br/>For example, all motors could belong to a *motors* group.|
129
-
|`manufacturer`|string|For a physical hardware component, this is a manufacturer or vendor name.<br/><br/>For a logical component, such as a disk partition or directory, it can be any device builder's defined value.|
130
-
|`model`|string|For a physical hardware component, this is a model name.<br/><br/>For a logical component, such as a disk partition or directory, this can be any device builder's defined value.|
141
+
|`manufacturer`|string|For a physical hardware component, this property is a manufacturer or vendor name.<br/><br/>For a logical component, such as a disk partition or directory, it can be any device builder's defined value.|
142
+
|`model`|string|For a physical hardware component, this property is a model name.<br/><br/>For a logical component, such as a disk partition or directory, this property can be any device builder's defined value.|
131
143
|`properties`|object| A JSON object that contains any optional device-specific properties.|
132
144
133
-
Here's an example of `ComponentInfo` code:
145
+
Here's an example of `ComponentInfo` code based on the Contoso Virtual Vacuum components:
134
146
135
147
```json
136
148
{
@@ -150,7 +162,7 @@ Here's an example of `ComponentInfo` code:
150
162
151
163
### Example return values
152
164
153
-
Following is a JSON document returned from the `GetAllComponents` function. It's based on the example implementation of the Contoso component enumerator.
165
+
Following is a JSON document returned from the `GetAllComponents` function. It's based on the example implementation of the Contoso Virtual Vacuum component enumerator.
154
166
155
167
```json
156
168
{
@@ -356,13 +368,13 @@ Here's the parameter's output for the *hostfw* component:
356
368
357
369
## Inventory file
358
370
359
-
The example implementation shown earlier for the Contoso component enumerator will read the device-specific components' information from the *component-inventory.json* file. Note that this example implementation is only for demonstration purposes.
371
+
The example implementation shown earlier for the Contoso Virtual Vacuum component enumerator will read the device-specific components' information from the *component-inventory.json* file. This example implementation is only for demonstration purposes.
360
372
361
-
In a production scenario, some properties should be retrieved directly from the actual components. These properties include `id`, `manufacturer`, and `model`.
373
+
In a production scenario, some properties should be retrieved directly from the actual components. These properties include `id`, `manufacturer`, and `model`.
362
374
363
375
The device builder defines the `name` and `group` properties. These values should never change after they're defined. The `name` property must be unique within the device.
364
376
365
-
####Example component-inventory.json file
377
+
### Example component-inventory.json file
366
378
367
379
> [!NOTE]
368
380
> The content in this file looks almost the same as the returned value from the `GetAllComponents` function. However, `ComponentInfo` in this file doesn't contain `version` and `status` properties. The component enumerator will populate these properties at runtime.
@@ -466,7 +478,7 @@ For example, for *hostfw*, the value of the property `properties.version` will b
466
478
467
479
## Next steps
468
480
469
-
This example is written in C++. You can choose to use C if you prefer. To explore example source codes, see:
481
+
The example in this article used C. To explore C++ example source codes, see:
0 commit comments