Skip to content

Commit 12695e6

Browse files
roygararoygara
committed
Merge branch 'main' of https://github.com/MicrosoftDocs/azure-docs-pr into linuxResize
2 parents b8c4a16 + aaa0430 commit 12695e6

16 files changed

+170
-103
lines changed

‎articles/iot-edge/how-to-provision-single-device-linux-symmetric.md

Lines changed: 88 additions & 45 deletions
Original file line numberDiff line numberDiff line change
@@ -13,11 +13,15 @@ ms.author: patricka
1313

1414
[!INCLUDE [iot-edge-version-1.1-or-1.4](includes/iot-edge-version-1.1-or-1.4.md)]
1515

16-
This article provides end-to-end instructions for registering and provisioning a Linux IoT Edge device, including installing IoT Edge.
16+
This article provides end-to-end instructions for registering and provisioning a Linux IoT Edge device, which includes installing IoT Edge.
1717

18-
Every device that connects to an IoT hub has a device ID that's used to track cloud-to-device or device-to-cloud communications. You configure a device with its connection information, which includes the IoT hub hostname, the device ID, and the information the device uses to authenticate to IoT Hub.
18+
Each device that connects to an [IoT hub](../iot-hub/index.yml) has a device ID that's used to track [cloud-to-device](../iot-hub/iot-hub-devguide-c2d-guidance.md) or [device-to-cloud](../iot-hub/iot-hub-devguide-d2c-guidance.md) communications. You configure a device with its connection information, which includes:
1919

20-
The steps in this article walk through a process called manual provisioning, where you connect a single device to its IoT hub. For manual provisioning, you have two options for authenticating IoT Edge devices:
20+
* IoT hub hostname
21+
* Device ID
22+
* Authentication details to connect to IoT Hub
23+
24+
The steps in this article walk through a process called *manual provisioning*, where you connect a single device to its IoT hub. For manual provisioning, you have two options for authenticating IoT Edge devices:
2125

2226
* **Symmetric keys**: When you create a new device identity in IoT Hub, the service creates two keys. You place one of the keys on the device, and it presents the key to IoT Hub when authenticating.
2327

@@ -38,14 +42,27 @@ This article covers using symmetric keys as your authentication method. If you w
3842
3943
## Prerequisites
4044

41-
This article covers registering your IoT Edge device and installing IoT Edge on it. These tasks have different prerequisites and utilities used to accomplish them. Make sure you have all the prerequisites covered before proceeding.
45+
This article shows how to register your IoT Edge device and install IoT Edge (also called IoT Edge runtime) on your device. Make sure you have the device management tool of your choice, for example Azure CLI, and device requirements before you register and install your device.
4246

4347
<!-- Device registration prerequisites H3 and content -->
4448
[!INCLUDE [iot-edge-prerequisites-register-device.md](includes/iot-edge-prerequisites-register-device.md)]
4549

4650
<!-- Device requirements H3 and content -->
4751
[!INCLUDE [iot-edge-prerequisites-device-requirements-linux.md](includes/iot-edge-prerequisites-device-requirements-linux.md)]
4852

53+
<!-- Azure IoT extensions for Visual Studio Code-->
54+
### Visual Studio Code extensions
55+
56+
If you are using Visual Studio Code, there are helpful Azure IoT extensions that will make the device creation and management process easier.
57+
58+
Install both the Azure IoT Edge and Azure IoT Hub extensions:
59+
60+
* [Azure IoT Edge](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-edge)
61+
62+
* [Azure IoT Hub](https://marketplace.visualstudio.com/items?itemName=vsciot-vscode.azure-iot-toolkit)
63+
64+
<!-- Prerequisites end -->
65+
4966
<!-- Register your device and View provisioning information H2s and content -->
5067
[!INCLUDE [iot-edge-register-device-symmetric.md](includes/iot-edge-register-device-symmetric.md)]
5168

@@ -54,7 +71,7 @@ This article covers registering your IoT Edge device and installing IoT Edge on
5471

5572
## Provision the device with its cloud identity
5673

57-
Now that the container engine and the IoT Edge runtime are installed on your device, you're ready for the next step, which is to set up the device with its cloud identity and authentication information.
74+
Now that the container engine and the IoT Edge runtime are installed on your device, you're ready to set up the device with its cloud identity and authentication information.
5875

5976
<!-- 1.1 -->
6077
::: moniker range="iotedge-2018-06"
@@ -94,112 +111,138 @@ After entering the provisioning information in the configuration file, restart t
94111
<!-- iotedge-2020-11 -->
95112
::: moniker range=">=iotedge-2020-11"
96113

97-
You can quickly configure your IoT Edge device with symmetric key authentication using the following command:
114+
1. You can quickly configure your IoT Edge device with symmetric key authentication using the following command. Replace `PASTE_DEVICE_CONNECTION_STRING_HERE` with your own connection string.
98115

99116
```bash
100-
sudo iotedge config mp --connection-string 'PASTE_DEVICE_CONNECTION_STRING_HERE'
117+
sudo iotedge config mp --connection-string `PASTE_DEVICE_CONNECTION_STRING_HERE`
101118
```
102119

103-
The `iotedge config mp` command creates a configuration file on the device and enters your connection string in the file.
120+
This `iotedge config mp` command creates a configuration file on the device and enters your connection string in the configuration file.
104121

105-
Apply the configuration changes.
122+
1. Apply the configuration changes.
106123

107124
```bash
108125
sudo iotedge config apply
109126
```
110127

111-
If you want to see the configuration file, you can open it:
128+
1. To view the configuration file, you can open it:
112129

113130
```bash
114131
sudo nano /etc/aziot/config.toml
115132
```
116-
133+
Verify successful configuration
117134
<!-- end iotedge-2020-11 -->
118135
::: moniker-end
119136

137+
## Deploy modules
138+
139+
To deploy your IoT Edge modules, go to your IoT hub in the Azure portal, then:
140+
141+
1. Select **Devices** from the IoT Hub menu.
142+
143+
1. Select your device to open its page.
144+
145+
1. Select the **Set Modules** tab.
146+
147+
1. Since we want to deploy the IoT Edge default modules (edgeAgent and edgeHub), we don't need to add any modules to this pane, so select **Review + create** at the bottom.
148+
149+
1. You see the JSON confirmation of your modules. Select **Create** to deploy the modules.<br>
150+
151+
For more information, see [Deploy a module](quickstart-linux.md#deploy-a-module).
152+
120153
## Verify successful configuration
121154

122155
Verify that the runtime was successfully installed and configured on your IoT Edge device.
123156

124-
>[!TIP]
125-
>You need elevated privileges to run `iotedge` commands. Once you sign out of your machine and sign back in the first time after installing the IoT Edge runtime, your permissions are automatically updated. Until then, use `sudo` in front of the commands.
157+
> [!TIP]
158+
> You need elevated privileges to run `iotedge` commands. Once you sign out of your machine and sign back in the first time after installing the IoT Edge runtime, your permissions are automatically updated. Until then, use `sudo` in front of the commands.
126159
127-
Check to see that the IoT Edge system service is running.
160+
1. Check to see that the IoT Edge system service is running.
128161

129-
<!-- 1.1 -->
130-
::: moniker range="iotedge-2018-06"
162+
<!-- 1.1 -->
163+
::: moniker range="iotedge-2018-06"
131164

132165
```bash
133166
sudo systemctl status iotedge
134167
```
135168

136-
::: moniker-end
169+
::: moniker-end
137170

138-
<!-- iotedge-2020-11 -->
139-
::: moniker range=">=iotedge-2020-11"
171+
<!-- iotedge-2020-11 -->
172+
::: moniker range=">=iotedge-2020-11"
140173

141174
```bash
142175
sudo iotedge system status
143176
```
144177

145-
A successful status response is `Ok`.
178+
A successful status response shows the `aziot` services as running or ready.
146179

147-
::: moniker-end
180+
::: moniker-end
148181

149-
If you need to troubleshoot the service, retrieve the service logs.
182+
1. To troubleshoot the service, retrieve the service logs.
150183

151-
<!-- 1.1 -->
152-
::: moniker range="iotedge-2018-06"
184+
<!-- 1.1 -->
185+
::: moniker range="iotedge-2018-06"
153186

154187
```bash
155188
journalctl -u iotedge
156189
```
157190

158-
::: moniker-end
191+
::: moniker-end
159192

160-
<!-- iotedge-2020-11 -->
161-
::: moniker range=">=iotedge-2020-11"
193+
<!-- iotedge-2020-11 -->
194+
::: moniker range=">=iotedge-2020-11"
162195

163196
```bash
164197
sudo iotedge system logs
165198
```
166199

167-
::: moniker-end
200+
::: moniker-end
168201

169-
Use the `check` tool to verify configuration and connection status of the device.
202+
1. Use the `check` tool to verify configuration and connection status of the device.
170203

171204
```bash
172205
sudo iotedge check
173206
```
174207

175-
>[!TIP]
176-
>Always use `sudo` to run the check tool, even after your permissions are updated. The tool needs elevated privileges to access the config file to verify configuration status.
208+
You can expect a range of responses that may include **OK** (green), **Warning** (yellow), or **Error** (red).
177209

178-
>[!NOTE]
179-
>On a newly provisioned device, you may see an error related to IoT Edge Hub:
180-
>
181-
>**× production readiness: Edge Hub's storage directory is persisted on the host filesystem - Error**
182-
>
183-
>**Could not check current state of edgeHub container**
184-
>
185-
>This error is expected on a newly provisioned device because the IoT Edge Hub module isn't running. To resolve the error, in IoT Hub, set the modules for the device and create a deployment. Creating a deployment for the device starts the modules on the device including the IoT Edge Hub module.
210+
:::image type="content" source="media/how-to-provision-single-device-linux-symmetric/config-checks.png" alt-text="Screenshot of sample responses from the check command." lightbox="media/how-to-provision-single-device-linux-symmetric/config-checks.png":::
211+
212+
>[!TIP]
213+
>Always use `sudo` to run the check tool, even after your permissions are updated. The tool needs elevated privileges to access the config file to verify configuration status.
214+
215+
>[!NOTE]
216+
>On a newly provisioned device, you may see an error related to IoT Edge Hub:
217+
>
218+
>**× production readiness: Edge Hub's storage directory is persisted on the host filesystem - Error**
219+
>**Could not check current state of edgeHub container**
220+
>
221+
>This error is expected on a newly provisioned device because the IoT Edge Hub module is not yet running. Be sure your IoT Edge modules were deployed in the previous steps. Deployment resolves this error.
222+
>
223+
>Alternatively, you may see a status code as `417 -- The device's deployment configuration is not set`. Once your modules are deployed, this status will change.
224+
>
186225
187-
View all the modules running on your IoT Edge device. When the service starts for the first time, you should only see the **edgeAgent** module running. The edgeAgent module runs by default and helps to install and start any additional modules that you deploy to your device.
226+
1. When the service starts for the first time, you should only see the **edgeAgent** module running. The edgeAgent module runs by default and helps to install and start any additional modules that you deploy to your device.
227+
228+
Check that your device and modules are deployed and running, by viewing your device page in the Azure portal.
229+
230+
:::image type="content" source="media/how-to-provision-single-device-linux-symmetric/modules-deployed.png" alt-text="Screenshot of IoT Edge modules deployed and running confirmation in the Azure portal.":::
231+
232+
Once your modules are deployed and running, list them in your device or virtual machine with the following command:
188233

189234
```bash
190235
sudo iotedge list
191236
```
192237

193-
When you create a new IoT Edge device, it will display the status code `417 -- The device's deployment configuration is not set` in the Azure portal. This status is normal, and means that the device is ready to receive a module deployment.
194-
195238
## Offline or specific version installation (optional)
196239

197240
The steps in this section are for scenarios not covered by the standard installation steps. This may include:
198241

199-
* Install IoT Edge while offline
200-
* Install a release candidate version
242+
* Installing IoT Edge while offline
243+
* Installing a release candidate version
201244

202-
Use the steps in this section if you want to install a specific version of the Azure IoT Edge runtime that isn't available through your package manager. The Microsoft package list only contains a limited set of recent versions and their sub-versions, so these steps are for anyone who wants to install an older version or a release candidate version.
245+
Use the steps in this section if you want to install a [specific version of the Azure IoT Edge runtime](version-history.md) that isn't available through your package manager. The Microsoft package list only contains a limited set of recent versions and their sub-versions, so these steps are for anyone who wants to install an older version or a release candidate version.
203246

204247
Using curl commands, you can target the component files directly from the IoT Edge GitHub repository.
205248

0 commit comments

Comments
 (0)