Skip to content

Commit 6336850

Browse files
v-thepetv-thepet
committed
in progress
1 parent 2844551 commit 6336850

File tree

6 files changed

+257
-293
lines changed

6 files changed

+257
-293
lines changed

‎articles/iot-hub-device-update/device-update-raspberry-pi.md

Lines changed: 175 additions & 202 deletions
Large diffs are not rendered by default.

‎articles/iot-hub-device-update/device-update-simulator.md

Lines changed: 65 additions & 74 deletions
Original file line numberDiff line numberDiff line change
@@ -9,67 +9,55 @@ ms.service: azure-iot-hub
99
ms.subservice: device-update
1010
---
1111

12-
# Tutorial: Azure Device Update for IoT Hub using the Ubuntu 18.04 simulator agent
12+
# Tutorial: Azure Device Update for IoT Hub using a simulator agent
1313

14-
Azure Device Update for IoT Hub supports image-based, package-based, and script-based updates. This tutorial demonstrates an end-to-end image-based update for Device Update for IoT Hub that uses an Ubuntu 18.04 x64 simulator agent.
14+
Azure Device Update for IoT Hub supports image-based, package-based, and script-based updates. This tutorial demonstrates an end-to-end image-based Device Update update that uses an Ubuntu 18.04 x64 simulator agent.
1515

1616
Image updates provide a high level of confidence in the end state of the device, and don't pose the same package and dependency management challenges as package or script based updates. It's easier to replicate the results of an image update between a preproduction and production environment, or easily adopt an A/B failover model.
1717

1818
In this tutorial, you:
1919
> [!div class="checklist"]
2020
>
2121
> - Assign an IoT device to a Device Update group by using tags.
22-
> - Download and install an image.
23-
> - Import an update.
22+
> - Download and install an image update.
23+
> - Import the image update.
2424
> - Deploy the image update.
2525
> - Monitor the update deployment.
2626
2727
## Prerequisites
2828

29-
- A test IoT device
30-
- A [Device Update account and instance configured with an IoT hub](create-device-update-account.md)
29+
- An IoT device
3130
- An Ubuntu 18.04 x64 physical or virtual machine
32-
33-
## Get the simulator files
34-
35-
1. Download the *Tutorial_Simulator.zip* ZIP archive from the **Assets** section of the latest release on the [GitHub Device Update Releases](https://github.com/Azure/iot-hub-device-update/releases) page. If your test device is different than your development machine, download the ZIP file onto both devices.
36-
37-
You can use `wget` to download the ZIP file. Replace `<release_version>` with the latest release, for example `1.0.0`.
38-
39-
```bash
40-
wget https://github.com/Azure/iot-hub-device-update/releases/download/<release_version>/Tutorial_Simulator.zip
41-
```
42-
43-
1. Unzip the file.
31+
- A [Device Update account and instance configured with an IoT hub](create-device-update-account.md)
4432

4533
## Register and configure a device and module
4634

47-
Add a device to the device registry in your IoT hub. Every device that connects to IoT Hub must be registered.
35+
Add the device to the device registry in your IoT hub. Every device that connects to IoT Hub must be registered.
4836

4937
1. In the [Azure portal](https://portal.azure.com), open the IoT hub page associated with your Device Update instance.
5038
1. In the navigation pane, select **Device management** > **Devices**.
5139
1. On the **Devices** page, select **Add Device**.
5240
1. Under **Device ID**, enter a name for the device. Ensure that **Autogenerate keys** checkbox is selected.
53-
1. Select **Save**.
41+
1. Select **Save**. The device appears in the list on the **Devices** page.
5442

5543
### Create a module identity
5644

57-
After you register the device, create a module identity. Modules are independent identities for components that exist on an IoT device, which allow for finer granularity when an IoT device runs multiple processes.
45+
After you register the device, create a module identity. Modules are independent identities for IoT device components, which allow for finer granularity when the device runs multiple processes.
5846

59-
For this tutorial, you create a module identity for the Device Update agent that runs on the IoT device. For more information, see [Understand and use module twins in IoT Hub](../iot-hub/iot-hub-devguide-module-twins.md).
47+
For this tutorial, you create a module identity for the Device Update agent that runs on the device. For more information, see [Understand and use module twins in IoT Hub](../iot-hub/iot-hub-devguide-module-twins.md).
6048

6149
1. On the **Devices** page, select the device you registered.
6250
1. On the device page, select **Add Module Identity**.
63-
1. On the **Add Module Identity** page, under **Module Identity Name**, enter a name for the module such as **DeviceUpdateAgent**.
64-
1. Select **Save**. The new module identity appears under **Module Identities**.
51+
1. On the **Add Module Identity** page, under **Module Identity Name**, enter a name for the module such as *DeviceUpdateAgent*.
52+
1. Select **Save**. The new module identity appears on the device page under **Module Identities**.
6553
1. Select the module name, and on the **Module Identity Details** page, select the **Copy** icon next to **Connection string (primary key)**. Save this *module connection string* to use when you configure the Device Update agent.
6654

6755
### Add a tag to your module twin
6856

69-
Every device that's managed by Device Update needs a reserved tag that assigns the device to a Device Update group. The tag can be in the device twin or in a module twin, as shown here. Each device can be assigned to only one Device Update group.
57+
You can assign a tag to any device that's managed by Device Update to assign the device to a Device Update group. The tag can be in the device twin or in the module twin as in this tutorial. Each device can be assigned to only one Device Update group.
7058

7159
1. On the **Module Identity Details** page, select **Module Identity Twin**.
72-
1. On the **Module Identity Twin** page, add a new Device Update tag to the JSON code at the same level as `modelId` and `version`, as follows:
60+
1. On the **Module Identity Twin** page, add a new `DeviceUpdateGroup` tag to the JSON code at the same level as `modelId` and `version`, as follows:
7361

7462
```json
7563
"tags": {
@@ -81,9 +69,9 @@ Every device that's managed by Device Update needs a reserved tag that assigns t
8169

8270
## Install and configure the Device Update agent
8371

84-
The Device Update agent runs on every device that Device Update manages. In this tutorial, you configure the Device Update agent to run as a simulator on your device, demonstrating how you can apply an update to a device without changing the device configuration.
72+
The Device Update agent runs on every device that Device Update manages. In this tutorial, you install the Device Update agent on your device and configure it to run as a simulator, demonstrating how you can apply an update to a device without changing the device configuration.
8573

86-
1. On your IoT device, add the Microsoft package repository, and then add the Microsoft package signing key to your list of trusted keys.
74+
1. Add the Microsoft package repository, and then add the Microsoft package signing key to your list of trusted keys.
8775

8876
```bash
8977
wget https://packages.microsoft.com/config/ubuntu/18.04/multiarch/packages-microsoft-prod.deb -O packages-microsoft-prod.deb
@@ -104,53 +92,62 @@ The Device Update agent runs on every device that Device Update manages. In this
10492
sudo nano /etc/adu/du-config.json
10593
```
10694

107-
1. Update *du-config.json* with the following example values:
95+
1. Update *du-config.json* with the following example values. Replace the `<connection string>` placeholder with the connection string you copied from the module identity. For more information about the parameters, see [Device Update configuration file](device-update-configuration-file.md).
10896

10997
- `manufacturer: "contoso"`
11098
- `model: "video"`
11199
- `agents.name: "aduagent"`
112-
- `agents.connectionData: <connection string>` - Replace this placeholder with the connection string you copied from the module identity.
100+
- `agents.connectionData: <connection string>`
113101
- `agents.manufacturer: "contoso"`
114102
- `agents.model: "video"`
115103

116-
For more information about these parameters, see [Device Update configuration file](device-update-configuration-file.md).
117-
118-
The edited *du-config.json* file should look like this:
119-
120-
```json
121-
{
122-
"schemaVersion": "1.0",
123-
"aduShellTrustedUsers": [
124-
"adu",
125-
"do"
126-
],
127-
"manufacturer": "contoso",
128-
"model": "video",
129-
"agents": [
130-
{
131-
"name": "aduagent",
132-
"runas": "adu",
133-
"connectionSource": {
134-
"connectionType": "string",
135-
"connectionData": <connection string>
136-
},
104+
The edited *du-config.json* file should look like this:
105+
106+
```json
107+
{
108+
"schemaVersion": "1.0",
109+
"aduShellTrustedUsers": [
110+
"adu",
111+
"do"
112+
],
137113
"manufacturer": "contoso",
138-
"model": "video"
139-
}
140-
]
141-
}```
114+
"model": "video",
115+
"agents": [
116+
{
117+
"name": "aduagent",
118+
"runas": "adu",
119+
"connectionSource": {
120+
"connectionType": "string",
121+
"connectionData": <connection string>
122+
},
123+
"manufacturer": "contoso",
124+
"model": "video"
125+
}
126+
]
127+
}
128+
```
142129

143-
1. Press **Ctrl+X** to exit the editor, and **y** to save your changes.
130+
1. Press **Ctrl**+**X** to exit the editor, and enter *y* to save your changes.
144131

145132
>[!NOTE]
146133
>You can also use the Azure IoT Identity Service to provision the device. To do that, [install the Azure IoT Identity Service](https://azure.github.io/iot-identity-service/installation.html) before installing the Device Update agent. Then configure the Device Update agent with `"connectionType": "AIS"` and leave `connectionData` as a blank string in the configuration file.
147134
148-
1. To set up the agent to run as a simulator, run the following command on the IoT device. The Device Update agent invokes the simulator handler to process a package update with the Microsoft SWUpdate extension.
135+
1. To set up the agent to run as a simulator, run the following command on the IoT device. The Device Update agent invokes the simulator handler to process updates that use the Microsoft SWUpdate extension.
149136

150137
```bash
151138
sudo /usr/bin/AducIotAgent --extension-type updateContentHandler --extension-id 'microsoft/swupdate:1' --register-extension /var/lib/adu/extensions/sources/libmicrosoft_simulator_1.so
152139
```
153140

141+
### Get the simulator files
142+
143+
1. Download and extract the *Tutorial_Simulator.zip* archive from the [GitHub Device Update Releases](https://github.com/Azure/iot-hub-device-update/releases) latest release **Assets** section. If your test device and development machine are separate devices, download and extract the ZIP file onto both devices.
144+
145+
You can use `wget` to download the ZIP file. Replace `<release_version>` with the latest release, for example `1.0.0`.
146+
147+
```bash
148+
wget https://github.com/Azure/iot-hub-device-update/releases/download/<release_version>/Tutorial_Simulator.zip
149+
```
150+
154151
1. Copy the *sample-du-simulator-data.json* file from the extracted *Tutorial_Simulator* folder to the *tmp* folder.
155152

156153
```bash
@@ -183,15 +180,15 @@ The edited *du-config.json* file should look like this:
183180

184181
This section uses the *TutorialImportManifest_Sim.importmanifest.json* and *adu-update-image-raspberrypi3.swu* files from the downloaded *Tutorial_Simulator* folder. The update file is the same one as in the [Raspberry Pi tutorial](device-update-raspberry-pi.md). Because the update in this tutorial is simulated, the specific file content doesn't matter.
185182

186-
1. From your development machine, 1. In the [Azure portal](https://portal.azure.com), open the IoT hub page associated with your Device Update instance.
187-
sign in to the [Azure portal](https://portal.azure.com/) and go to your IoT hub that is configured with Device Update.
183+
1. On your development machine, sign in to the [Azure portal](https://portal.azure.com/) and go to the IoT hub configured with your Device Update instance.
188184
1. In the navigation pane, select **Device Management** > **Updates**.
189185
1. On the **Updates** page, select **Import a new update**.
190186
1. On the **Import update** page, select **Select from storage container**.
191-
1. Select an existing storage account, or create a new account by selecting **+ Storage account**. Then, select an existing container or create a new container by selecting **+ Container**. This container is used to stage the update files for importing.
187+
1. Select an existing storage account, or create a new account by selecting **+ Storage account**.
188+
1. Select an existing container, or create a new container by selecting **+ Container**. This container is used to stage the update files for importing.
192189

193190
> [!NOTE]
194-
> To avoid accidentally importing files from previous updates, it's best to use a new container each time you import an update. If you don't use a new container, be sure to delete any files from the existing container.
191+
> To avoid accidentally importing files from previous updates, use a new container each time you import an update. If you don't use a new container, be sure to delete any files from the existing container.
195192
196193
1. On the container page, select **Upload**, browse to and select the *TutorialImportManifest_Sim.importmanifest.json* and *adu-update-image-raspberrypi3.swu* files, and then select **Upload**.
197194

@@ -211,21 +208,19 @@ The imported update now appears on the **Updates** page.
211208

212209
For more information about the import process, see [Import an update to Device Update for IoT Hub](import-update.md).
213210

214-
## View device groups
211+
### View device groups
215212

216-
Device Update uses groups to organize devices. Device Update automatically sorts devices into groups based on their assigned tags and compatibility properties. Each device belongs to only one group, but groups can have multiple subgroups to sort different device classes.
213+
Device Update uses groups to organize devices, and automatically sorts devices into groups based on their assigned tags and compatibility properties. Each device belongs to only one group, but groups can have multiple subgroups to sort different device classes.
217214

218215
On the **Updates** page for your IoT hub, select the **Groups and Deployments** tab to view the list of groups and the update compliance chart. The update compliance chart shows the count of devices in various states of compliance: **On latest update**, **New updates available**, and **Updates in progress**. For more information, see [Device Update compliance](device-update-compliance.md).
219216

220217
:::image type="content" source="media/device-update-simulator/groups-and-deployments.png" alt-text="Screenshot that shows the update compliance view." lightbox="media/create-update-group/updated-view.png":::
221218

222-
You should see a device group that contains the simulated device you set up in this tutorial, along with any available updates for the devices in the group. If there are devices that don't meet the device class requirements of the group, they appeaer in a corresponding invalid group.
223-
224-
For more information about tags and groups, see [Manage device groups](create-update-group.md).
219+
You should see a device group that contains the simulated device you set up in this tutorial, along with any available updates for the devices in the group. Any devices that don't meet the group device class requirements appear in a corresponding invalid group. For more information about tags and groups, see [Manage device groups](create-update-group.md).
225220

226221
## Deploy the update
227222

228-
1. On the **Groups and Deployments** tab, you should see the new update available for your device group, with a link to the update under **Status**. You might need to refresh the page.
223+
On the **Groups and Deployments** tab, you should see the new update available for your device group, with a link to the update under **Status**. You might need to refresh the page.
229224

230225
1. Select the group name to view its details.
231226

@@ -247,8 +242,6 @@ On the group details page, navigate to the **Current updates** tab. Under **Depl
247242

248243
:::image type="content" source="media/device-update-simulator/view-deployment-details.png" alt-text="Screenshot that shows Deployment details." lightbox="media/deploy-update/deployment-details.png":::
249244

250-
You successfully completed an end-to-end image-based update for Device Update for IoT Hub that used an Ubuntu 18.04 x64 simulator agent.
251-
252245
## Clean up resources
253246

254247
When you no longer need the resources you created for this tutorial, you can delete them.
@@ -257,9 +250,7 @@ When you no longer need the resources you created for this tutorial, you can del
257250
1. If you want to delete all the resources in the group, select **Delete resource group**.
258251
1. If you want to delete only some of the resources, use the check boxes to select the resources and then select **Delete**.
259252

260-
## Next steps
261-
262-
In this tutorial, you learned how to import and deploy an image update. Next, learn how to update device packages.
253+
## Related content
263254

264-
> [!div class="nextstepaction"]
265-
> [Device Update using the package agent](device-update-ubuntu-agent.md)
255+
- [Device Update for IoT Hub using a Raspberry Pi image](device-update-raspberry-pi.md)
256+
- [Device Update for IoT Hub using the Ubuntu package agent](device-update-ubuntu-agent.md)

0 commit comments

Comments
 (0)