Merge pull request #249991 from dominicbetts/central-device-status

IoT Central: Update device status information

Author: prmerger-automator[bot]

articles/iot-central/core/howto-manage-devices-individually.md

@@ -51,24 +51,34 @@ The following video walks you through monitoring device connectivity status:
 
 ### Device status values
 
-When a device connects to your IoT Central application, its device status changes as follows:
+Every device has a single status value in the UI. The device status can be one of:
 
-1. The device status is first **Registered**. This status means the device is created in IoT Central, and has a device ID. A device is registered when:
-    - A new real device is added on the **Devices** page.
-    - A set of devices is added using **Import** on the **Devices** page.
+- The device status is first **Registered**. This status means the device is created in IoT Central, and has a device ID. A device is registered when:
 
-1. The device status changes to **Provisioned** when the device that connected to your IoT Central application with valid credentials completes the provisioning step. In this step, the device uses DPS. The *Device ID* that was used to register the device. Either a SAS key or X.509 certificatTo find these values: to automatically retrieve a connection string from the IoT Hub used by your IoT Central application. The device can now connect to IoT Central and start sending data.
+  - A new real device is added on the **Devices** page.
+  - A set of devices is added using **Import** on the **Devices** page.
 
-1. An operator can block a device. When a device is blocked, it can't send data to your IoT Central application. Blocked devices have a status of **Blocked**. An operator must reset the device before it can resume sending data. When an operator unblocks a device the status returns to its previous value, **Registered** or **Provisioned**.
+- The device status changes to **Provisioned** when a registered device completes the provisioning step by using DPS. To complete the provisioning process, the device needs the *Device ID* that was used to register the device, either a SAS key or X.509 certificate, and the *ID scope*. After provisioning, the device can connect to your IoT Central application and start sending data.
 
-1. If the device status is **Waiting for Approval**, it means the **Auto approve** option is disabled. An operator must explicitly approve a device before it starts sending data. Devices not registered manually on the **Devices** page, but connected with valid credentials have the device status **Waiting for Approval**. Operators can approve these devices from the **Devices** page using the **Approve** button.
+- Blocked devices have a status of **Blocked**. An operator can block and unblock devices. When a device is blocked, it can't send data to your IoT Central application. An operator must unblock the device before it can resume sending data. When an operator unblocks a device the status returns to its previous value, **Registered** or **Provisioned**.
 
-1. If the device status is **Unassigned**, it means the device connecting to IoT Central isn't assigned to a device template. This situation typically happens in the following scenarios:
+- If the device status is **Waiting for Approval**, it means the **Auto approve** option is disabled on the **Device connection groups** page. An operator must explicitly approve a device before it can be provisioned and sending data. Devices not registered manually on the **Devices** page, but connected with valid credentials have the device status **Waiting for Approval**. Operators can approve these devices from the **Devices** page using the **Approve** button.
 
-    - A set of devices is added using **Import** on the **Devices** page without specifying the device template.
-    - A device was registered manually on the **Devices** page without specifying the device template. The device then connected with valid credentials.  
+The following table shows how the status value for a device in the UI maps to the values used by the REST API to interact with devices:
 
-    An operator can assign a device to a device template from the **Devices** page using the **Migrate** button.
+| UI Device status | Notes | REST API Get |
+| ---------------- | ----- | ------------ |
+| Waiting for approval | The auto-approve option is disabled in the device connection group and the device was not added through the UI. <br/> A user must manually approve the device through the UI before it can be used. | `Provisioned: false` <br/> `Enabled: false` |
+| Registered | A device has been approved either automatically or manually. | `Provisioned: false` <br/> `Enabled: true` |
+| Provisioned | The device has been provisioned and can connect to your IoT Central application. | `Provisioned: true` <br/> `Enabled: true` |
+| Blocked | The device is not allowed to connect to your IoT Central application. You can block a device that is in any of the other states. | `Provisioned:` depends on `Waiting for approval`/`Registered`/`Provisioned status` <br/> `Enabled: false` |
+
+A device can also have a status of **Unassigned**. This status isn't shown in the **Device status** field in the UI, it is shown in the **Device template** field in the UI. However, you can filter the device list for devices with the **Unassigned** status. If the device status is **Unassigned**, the device connecting to IoT Central isn't assigned to a device template. This situation typically happens in the following scenarios:
+
+- A set of devices is added using **Import** on the **Devices** page without specifying the device template.
+- A device was registered manually on the **Devices** page without specifying the device template. The device then connected with valid credentials.  
+
+An operator can assign a device to a device template from the **Devices** page by using the **Migrate** button.
 
 ### Device connection status
 

articles/iot-central/core/howto-manage-devices-with-rest-api.md

@@ -100,6 +100,15 @@ The response to this request looks like the following example:
 }
 ```
 
+The following table shows how the status value for a device in the UI maps to the values used by the REST API to interact with devices:
+
+| UI Device status | Notes | REST API Get |
+| ---------------- | ----- | ------------ |
+| Waiting for approval | The auto-approve option is disabled in the device connection group and the device was not added through the UI. <br/> A user must manually approve the device through the UI before it can be used. | `Provisioned: false` <br/> `Enabled: false` |
+| Registered | A device has been approved either automatically or manually. | `Provisioned: false` <br/> `Enabled: true` |
+| Provisioned | The device has been provisioned and can connect to your IoT Central application. | `Provisioned: true` <br/> `Enabled: true` |
+| Blocked | The device is not allowed to connect to your IoT Central application. You can block a device that is in any of the other states. | `Provisioned:` depends on `Waiting for approval`/`Registered`/`Provisioned status` <br/> `Enabled: false` |
+
 ### Get device credentials
 
 Use the following request to retrieve credentials of a device from your application:

articles/iot-central/core/troubleshoot-connection.md

@@ -135,7 +135,7 @@ https://aka.ms/iotcentral-docs-dps-SAS",
 | Unapproved | The device isn't approved. | Device isn't approved to connect to the IoT Central application. Approve the device in IoT Central and retry. To learn more, see [Device status values](howto-manage-devices-individually.md#device-status-values) |
 | Unassigned | The device isn't assigned to a device template. | Assign the device to a device template so that IoT Central knows how to parse the data. |
 
-Learn more about [Device status values](howto-manage-devices-individually.md#device-status-values).
+Learn more about [Device status values in the UI](howto-manage-devices-individually.md#device-status-values) and [Device status values in the REST API](howto-manage-devices-with-rest-api.md#get-a-device).
 
 ### Error codes