Skip to content

Commit 8035cd0

Browse files
ttorblettorble
authored
Merge pull request #213944 from dominicbetts/central-iot-edge-updates
IoT Central: deployment manifest updates
2 parents 12ed456 + daabced commit 8035cd0

38 files changed

+286
-147
lines changed

‎articles/iot-central/TOC.yml

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -141,6 +141,8 @@
141141
href: core/howto-use-commands.md
142142
- name: Connect devices that use X.509
143143
href: core/how-to-connect-devices-x509.md
144+
- name: Manage IoT Edge deployment manifests
145+
href: core/howto-manage-deployment-manifests.md
144146
- name: Connect devices through an IoT Edge transparent gateway
145147
href: core/how-to-connect-iot-edge-transparent-gateway.md
146148
- name: Prepare and connect an IoT Edge for Linux on Windows device

‎articles/iot-central/core/concepts-iot-edge.md

Lines changed: 43 additions & 106 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Azure IoT Edge and Azure IoT Central | Microsoft Docs
33
description: Understand how to use Azure IoT Edge with an IoT Central application.
44
author: dominicbetts
55
ms.author: dobett
6-
ms.date: 06/08/2022
6+
ms.date: 10/11/2022
77
ms.topic: conceptual
88
ms.service: iot-central
99
services: iot-central
@@ -30,18 +30,17 @@ To learn more about IoT Edge, see [What is Azure IoT Edge?](../../iot-edge/about
3030

3131
IoT Edge is made up of three components:
3232

33-
* *IoT Edge modules* are containers that run Azure services, partner services, or your own code. Modules are deployed to IoT Edge devices, and run locally on those devices. To learn more, see [Understand Azure IoT Edge modules](../../iot-edge/iot-edge-modules.md).
34-
* The *IoT Edge runtime* runs on each IoT Edge device, and manages the modules deployed to each device. The runtime consists of two IoT Edge modules: *IoT Edge agent* and *IoT Edge hub*. To learn more, see [Understand the Azure IoT Edge runtime and its architecture](../../iot-edge/iot-edge-runtime.md).
33+
* [IoT Edge modules](../../iot-edge/iot-edge-modules.md) are containers that run Azure services, partner services, or your own code. Modules are deployed to IoT Edge devices, and run locally on those devices. A [deployment manifest](../../iot-edge/module-composition.md) specifies the modules to deploy to an IoT Edge device.
34+
* The [IoT Edge runtime](../../iot-edge/iot-edge-runtime.md) runs on each IoT Edge device, and manages the modules deployed to each device. The runtime consists of two IoT Edge modules: [IoT Edge agent and IoT Edge hub](../../iot-edge/module-edgeagent-edgehub.md).
3535
* A *cloud-based interface* enables you to remotely monitor and manage IoT Edge devices. IoT Central is an example of a cloud interface.
3636

3737
IoT Central enables the following capabilities to for IoT Edge devices:
3838

39+
* Deployment manifest management. An IoT Central application can manage a collection of deployment manifests and assign them to devices.
3940
* Device templates to describe the capabilities of an IoT Edge device, such as:
40-
* Deployment manifest upload capability, which helps you manage a manifest for a fleet of devices.
41-
* Modules that run on the IoT Edge device.
42-
* The telemetry each module sends.
43-
* The properties each module reports.
44-
* The commands each module responds to.
41+
* The telemetry each IoT Edge module sends.
42+
* The properties each IoT Edge module reports.
43+
* The commands each IoT Edge module responds to.
4544
* The relationships between an IoT Edge gateway device and downstream device.
4645
* Cloud properties that aren't stored on the IoT Edge device.
4746
* Device views and forms.
@@ -59,34 +58,20 @@ An IoT Edge device can be:
5958

6059
IoT Edge devices can use *shared access signature* tokens or X.509 certificates to authenticate with IoT Central. You can manually register your IoT Edge devices in IoT Central before they connect for the first time, or use the Device Provisioning Service to handle the registration. To learn more, see [How devices connect](overview-iot-central-developer.md#how-devices-connect).
6160

62-
IoT Central uses [device templates](concepts-device-templates.md) to define how IoT Central interacts with a device. For example, a device template specifies:
61+
IoT Central optionally uses [device templates](concepts-device-templates.md) to define how IoT Central interacts with an IoT Edge device. For example, a device template specifies:
6362

64-
* The types of telemetry and properties a device sends so that IoT Central can interpret them and create visualizations.
65-
* The commands a device responds to so that IoT Central can display a UI for an operator to use to call the commands.
63+
* The types of telemetry and properties an IoT Edge device sends so that IoT Central can interpret them and create visualizations.
64+
* The commands an IoT Edge device responds to so that IoT Central can display a UI for an operator to use to call the commands.
6665

67-
An IoT Edge device can send telemetry, synchronize property values, and respond to commands in the same way as a standard device. So, an IoT Edge device needs a device template in IoT Central.
66+
If there's no device template associated with a device, telemetry and property values display as *unmodeled* data. However, you can still use IoT Central data export capabilities to forward telemetry and property values to other backend services.
6867

69-
### IoT Edge device templates
70-
71-
IoT Central device templates use models to describe the capabilities of devices. The following diagram shows the structure of the model for an IoT Edge device:
72-
73-
:::image type="content" source="media/concepts-iot-edge/iot-edge-model.png" alt-text="Structure of model for IoT Edge device connected to IoT Central" border="false":::
74-
75-
IoT Central models an IoT Edge device as follows:
76-
77-
* Every IoT Edge device template has a capability model.
78-
* For every custom module listed in the deployment manifest, a module capability model is generated.
79-
* A relationship is established between each module capability model and a device model.
80-
* A module capability model implements one or more module interfaces.
81-
* Each module interface contains telemetry, properties, and commands.
82-
83-
### IoT Edge deployment manifests and IoT Central device templates
68+
## IoT Edge deployment manifests
8469

8570
In IoT Edge, you deploy and manage business logic in the form of modules. IoT Edge modules are the smallest unit of computation managed by IoT Edge, and can contain Azure services such as Azure Stream Analytics, or your own solution-specific code.
8671

87-
An IoT Edge *deployment manifest* lists the IoT Edge modules to deploy on the device and how to configure them. To learn more, see [Learn how to deploy modules and establish routes in IoT Edge](../../iot-edge/module-composition.md).
72+
An IoT Edge [deployment manifest](../../iot-edge/module-composition.md) lists the IoT Edge modules to deploy on the device and how to configure them.
8873

89-
In Azure IoT Central, you import a deployment manifest to create a device template for the IoT Edge device.
74+
In Azure IoT Central, navigate to **Edge manifests** to import and manage the deployment manifests for the IoT Edge devices in your solution.
9075

9176
The following code snippet shows an example IoT Edge deployment manifest:
9277

@@ -161,92 +146,44 @@ In the previous snippet, you can see:
161146

162147
* There are three modules. The *IoT Edge agent* and *IoT Edge hub* system modules that are present in every deployment manifest. The custom **SimulatedTemperatureSensor** module.
163148
* The public module images are pulled from an Azure Container Registry repository that doesn't require any credentials to connect. For private module images, set the container registry credentials to use in the `registryCredentials` setting for the *IoT Edge agent* module.
164-
* The custom **SimulatedTemperatureSensor** module has two properties `"SendData": true` and `"SendInterval": 10`.
149+
* The custom **SimulatedTemperatureSensor** module has two writable properties `"SendData": true` and `"SendInterval": 10`.
165150

166-
When you import this deployment manifest into an IoT Central application, it generates the following device template:
151+
The following screenshot shows this deployment manifest imported into IoT Central:
167152

168-
:::image type="content" source="media/concepts-iot-edge/device-template.png" alt-text="Screenshot showing the device template created from the deployment manifest.":::
153+
:::image type="content" source="media/concepts-iot-edge/imported-deployment-manifest.png" alt-text="Screenshot that shows the imported Environmental sensor deployment manifest.":::
169154

170-
In the previous screenshot you can see:
155+
If your application uses [organizations](howto-create-organizations.md), you can assign your deployment manifests to specific organizations. The previous screenshot shows the deployment manifest assigned to the **Store Manager / Americas** organization.
171156

172-
* A module called **SimulatedTemperatureSensor**. The *IoT Edge agent* and *IoT Edge hub* system modules don't appear in the template.
173-
* An interface called **management** that includes two writable properties called **SendData** and **SendInterval**.
157+
To learn how to use the **Edge manifests** page and assign deployment manifests to IoT Edge devices, see [Manage IoT Edge deployment manifests in your IoT Central application](howto-manage-deployment-manifests.md).
174158

175-
The deployment manifest doesn't include information about the telemetry the **SimulatedTemperatureSensor** module sends or the commands it responds to. Add these definitions to the device template manually before you publish it.
159+
### Manage an unassigned device
176160

177-
To learn more, see [Tutorial: Add an Azure IoT Edge device to your Azure IoT Central application](/training/modules/connect-iot-edge-device-to-iot-central/).
161+
An IoT Edge device that doesn't have an associated device template is known as an *unassigned* device. You can't use IoT Central features such as dashboards, device groups, analytics, rules, and jobs with unassigned devices. However, you can use the following capabilities with unassigned devices:
178162

179-
### Update a deployment manifest
163+
* View raw data such as telemetry and properties.
164+
* Call device commands.
165+
* Read and write properties.
180166

181-
When you replace the deployment manifest, any connected IoT Edge devices download the new manifest and update their modules. However, IoT Central doesn't update the interfaces in the device template with any changes to the module configuration. For example, if you replace the manifest shown in the previous snippet with the following manifest, you don't automatically see the **SendUnits** property in the **management** interface in the device template. Manually add the new property to the **management** interface for IoT Central to recognize it:
167+
:::image type="content" source="media/concepts-iot-edge/unassigned-device-capabilities.png" alt-text="Screenshot that shows unassigned device capabilities.":::
182168

183-
```json
184-
{
185-
"modulesContent": {
186-
"$edgeAgent": {
187-
"properties.desired": {
188-
"schemaVersion": "1.0",
189-
"runtime": {
190-
"type": "docker",
191-
"settings": {
192-
"minDockerVersion": "v1.25",
193-
"loggingOptions": "",
194-
"registryCredentials": {}
195-
}
196-
},
197-
"systemModules": {
198-
"edgeAgent": {
199-
"type": "docker",
200-
"settings": {
201-
"image": "mcr.microsoft.com/azureiotedge-agent:1.0.9",
202-
"createOptions": "{}"
203-
}
204-
},
205-
"edgeHub": {
206-
"type": "docker",
207-
"status": "running",
208-
"restartPolicy": "always",
209-
"settings": {
210-
"image": "mcr.microsoft.com/azureiotedge-hub:1.0.9",
211-
"createOptions": "{}"
212-
}
213-
}
214-
},
215-
"modules": {
216-
"SimulatedTemperatureSensor": {
217-
"version": "1.0",
218-
"type": "docker",
219-
"status": "running",
220-
"restartPolicy": "always",
221-
"settings": {
222-
"image": "mcr.microsoft.com/azureiotedge-simulated-temperature-sensor:1.0",
223-
"createOptions": "{}"
224-
}
225-
}
226-
}
227-
}
228-
},
229-
"$edgeHub": {
230-
"properties.desired": {
231-
"schemaVersion": "1.0",
232-
"routes": {
233-
"route": "FROM /* INTO $upstream"
234-
},
235-
"storeAndForwardConfiguration": {
236-
"timeToLiveSecs": 7200
237-
}
238-
}
239-
},
240-
"SimulatedTemperatureSensor": {
241-
"properties.desired": {
242-
"SendData": true,
243-
"SendInterval": 10,
244-
"SendUnits": "Celsius"
245-
}
246-
}
247-
}
248-
}
249-
```
169+
You can also manage individual modules on unassigned devices:
170+
171+
:::image type="content" source="media/concepts-iot-edge/unassigned-module-capabilities.png" alt-text="Screenshot that shows the options for managing modules on unassigned devices.":::
172+
173+
## IoT Edge device templates
174+
175+
IoT Central device templates use models to describe the capabilities of IoT Edge devices. Device templates are optional for IoT Edge devices. The device template enables you to interact with telemetry, properties, and commands using IoT Central capabilities such as dashboards and analytics. The following diagram shows the structure of the model for an IoT Edge device:
176+
177+
:::image type="content" source="media/concepts-iot-edge/iot-edge-model.png" alt-text="Diagram that shows the model structure for an IoT Edge device connected to IoT Central." border="false":::
178+
179+
IoT Central models an IoT Edge device as follows:
180+
181+
* Every IoT Edge device template has a capability model.
182+
* For every custom module listed in the deployment manifest, add a module definition if you want to use IoT Central to interact with that module.
183+
* A module capability model implements one or more module interfaces.
184+
* Each module interface contains telemetry, properties, and commands.
185+
186+
You can generate the basic capability model based on the modules and properties defined in the device manifest. To learn more, see [Add modules and properties to device templates](howto-manage-deployment-manifests.md#add-modules-and-properties-to-device-templates).
250187

251188
## IoT Edge gateway patterns
252189

‎articles/iot-central/core/how-to-connect-devices-x509.md

Lines changed: 1 addition & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -361,7 +361,7 @@ You can repeat the above steps for _mytestselfcertsecondary_ certificate as well
361361
This section assumes you're using a group enrollment to connect your IoT Edge device. Follow the steps in the previous sections to:
362362
363363
- [Generate root and device certificates](#generate-root-and-device-certificates)
364-
- [Create a group enrollment](#create-a-group-enrollment) <!-- No slightly different type of enrollment group - UPDATE!! -->
364+
- [Create a group enrollment](#create-a-group-enrollment)
365365
366366
To connect the IoT Edge device to IoT Central using the X.509 device certificate:
367367

‎articles/iot-central/core/how-to-connect-iot-edge-transparent-gateway.md

Lines changed: 20 additions & 5 deletions
Original file line numberDiff line numberDiff line change
@@ -3,7 +3,7 @@ title: Connect an IoT Edge transparent gateway to an Azure IoT Central applicati
33
description: How to connect devices through an IoT Edge transparent gateway to an IoT Central application. The article shows how to use both the IoT Edge 1.1 and 1.2 runtimes.
44
author: dominicbetts
55
ms.author: dobett
6-
ms.date: 05/08/2022
6+
ms.date: 10/11/2022
77
ms.topic: how-to
88
ms.service: iot-central
99
services: iot-central
@@ -51,6 +51,16 @@ To follow the steps in this article, download the following files to your comput
5151

5252
---
5353

54+
## Import deployment manifest
55+
56+
Every IoT Edge device needs a deployment manifest to configure the IoT Edge runtime. To import a deployment manifest for the IoT Edge transparent gateway:
57+
58+
1. Navigate to **Edge manifests**.
59+
60+
1. Select **+ New**, enter a name for the deployment manifest such as *Transparent gateway* and then upload the *EdgeTransparentGatewayManifest.json* file you downloaded previously.
61+
62+
1. Select **Create** to save the deployment manifest in your application.
63+
5464
## Add device templates
5565

5666
Both the downstream devices and the gateway device can use device templates in IoT Central. IoT Central lets you model the relationship between your downstream devices and your gateway so you can view and manage them after they're connected. A device template isn't required to attach a downstream device to a gateway.
@@ -75,9 +85,11 @@ To create a device template for an IoT Edge transparent gateway device:
7585

7686
1. On the **Customize** page of the wizard, enter a name such as *Edge Gateway* for the device template.
7787

78-
1. On the **Customize** page of the wizard, check **Gateway device with downstream devices**.
88+
1. On the **Customize** page of the wizard, check **This is a gateway device**.
89+
90+
1. On the **Review** page, select **Create**.
7991

80-
1. On the **Customize** page of the wizard, select **Browse**. Upload the *EdgeTransparentGatewayManifest.json* file you downloaded previously.
92+
1. On the **Create a model** page, select **Custom model**.
8193

8294
1. Add an entry in **Relationships** to the downstream device template.
8395

@@ -97,7 +109,7 @@ To add the devices:
97109

98110
1. Navigate to the devices page in your IoT Central application.
99111

100-
1. Add an instance of the transparent gateway IoT Edge device. In this article, the gateway device ID is `edgegateway`.
112+
1. Add an instance of the transparent gateway IoT Edge device. When you add the device, make sure that you select the **Transparent gateway** deployment manifest. In this article, the gateway device ID is `edgegateway`.
101113

102114
1. Add one or more instances of the downstream device. In this article, the downstream devices are thermostats with IDs `thermostat1` and `thermostat2`.
103115

@@ -260,7 +272,7 @@ Your transparent gateway is now configured and ready to start forwarding telemet
260272
sudo nano /etc/aziot/config.toml
261273
```
262274

263-
1. Locate the `Certificate settings` settings. Add the certificate settings as follows:
275+
1. Locate the following settings in the configuration file. Add the certificate settings as follows:
264276

265277
```text
266278
trust_bundle_cert = "file:///home/AzureUser/certs/certs/azure-iot-test-only.root.ca.cert.pem"
@@ -373,6 +385,9 @@ To run the thermostat simulator on the `leafdevice` virtual machine:
373385
...
374386
```
375387
388+
> [!TIP]
389+
> If you see an error when the downstream device tries to connect. Try re-running the device provisioning steps above.
390+
376391
1. To see the telemetry in IoT Central, navigate to the **Overview** page for the **thermostat1** device:
377392
378393
:::image type="content" source="media/how-to-connect-iot-edge-transparent-gateway/downstream-device-telemetry.png" alt-text="Screenshot showing telemetry from the downstream device." lightbox="media/how-to-connect-iot-edge-transparent-gateway/downstream-device-telemetry.png":::

0 commit comments

Comments
 (0)