first round of feedback revisions

Author: v-steveadams

articles/iot-dps/concepts-deploy-at-scale.md

@@ -11,7 +11,7 @@ ms.custom: template-concept
 
 # Best practices for large-scale IoT device deployments
 
-Scaling an IoT solution to millions of devices can be challenging. Large-scale solutions often need to be designed in accordance with service and subscription limits. When customers use Azure IoT Device Provisioning Service, they use it in combination with other Azure IoT platform services and components, such as IoT Hub and many times with   an Azure IoT device SDK. This article describes best practices, patterns, and sample code you can incorporate in your design to take advantage of these services and allow your deployments to scale out. By following these simple patterns and practices right from the design phase of the project, you can maximize the performance of your IoT devices.
+Scaling an IoT solution to millions of devices can be challenging. Large-scale solutions often need to be designed in accordance with service and subscription limits. When customers use Azure IoT Device Provisioning Service, they use it in combination with other Azure IoT platform services and components, such as IoT Hub and Azure IoT device SDKs. This article describes best practices, patterns, and sample code you can incorporate in your design to take advantage of these services and allow your deployments to scale out. By following these simple patterns and practices right from the design phase of the project, you can maximize the performance of your IoT devices.
 
 ## First-time device provisioning
 
@@ -37,53 +37,30 @@ Where `<load>` is a configurable factor with values > 0  (indicates that the loa
 
 For more information on the timing of retry operations, see [Retry timing](https://github.com/Azure/azure-sdk-for-c/blob/main/sdk/docs/iot/mqtt_state_machine.md#retry-timing).
 
-## Hub connectivity considerations when using DPS
-
-- If you plan to have more than a million devices, the recommended path to scaling is to cap the number of devices to 1 million per hub and add hubs as needed when increasing the scale of your deployment.
-- If you have plans for more than a million devices and you need to support them in a specific region (such as in an EU region for data residency requirements), you can [contact us](../iot-fundamentals/iot-support-help.md) to ensure that the region you're deploying to has the capacity to support your current and future scale.
-
-Recommended device logic when connecting to IoT Hub via DPS:
-
-- On first boot, devices should go use the [DPS registration API](/rest/api/iot-dps/device/runtime-registration/register-device) to register.
-- On subsequent boots, devices should:
-  - If possible, cache their provisioning details and connect using this information from this cache.
-  - If they can't cache IoT hub connection information, use the [Device Registration Status Lookup API](/rest/api/iot-dps/device/runtime-registration/device-registration-status-lookup) to return connection information once registration has been done. This API call is a much lighter weight operation for DPS than a full device registration operation.
-  - For devices in either case described above, devices should use the following logic in response to error codes when connecting:
-    - When receiving any of the 500-series of server error responses, retry the connection using either cached credentials or the results of a Device Registration Status Lookup API call.
-    - When receiving `401, Unauthorized` or `403, Forbidden` or `404, Not Found`, perform a full re-registration by calling the [DPS registration API](/rest/api/iot-dps/device/runtime-registration/register-device).
-- At any time, devices should be capable of responding to a user-initiated reprovisioning command.
-
-Other IoT Hub scenarios when using DPS:
-
-- IoT Hub failover: Devices should continue to work as connection information shouldn't change and logic is in place to retry the connection once the hub is available again.
-- Change of IoT Hub: Assigning devices to a different IoT Hub should be done by using a [custom allocation policy](tutorial-custom-allocation-policies.md).
-- Retry IoT Hub connection: You shouldn't use an aggressive retry strategy, instead allowing a gap of at least a minute before a retry.
-- IoT Hub partitions: If your device strategy leans heavily on telemetry, the number of device-to-cloud partitions should be increased.
-
 ## Reprovisioning devices
 
 Reprovisioning is the process where the device needs to be provisioned to an IoT Hub after having been successfully connected previously. There can be many reasons that result in a need for device to reconnect to an IoT Hub, such as:
 
-- A device reboot could happen due to reasons like power outage, loss in network connectivity, geo-relocation, firmware updates, factory reset, and certificate key rotation.
-- The Hub instance could be unavailable due to an unplanned Hub outage.
+- A device could reboot due to power outage, loss in network connectivity, geo-relocation, firmware updates, factory reset, or certificate key rotation.
+- The IoT Hub instance could be unavailable due to an unplanned IoT Hub outage.
 
-You shouldn't need to provision every time the device reboots. Upon successful reboot and provisioning, the device would be connected to the same IoT Hub in most scenarios and so fresh provisioning isn't necessary. The information about the IoT Hub that has been cached from a previous successful connection must be used to directly connect to the hub as opposed to going through the extensive reprovisioning process.
+You shouldn't need to provision every time the device reboots. Most devices that are reprovisioned end up connected to the same IoT hub in most scenarios. Instead, the device should attempt to directly connect to its IoT hub using the information that was cached from a previous successful connection.
 
 ### Devices that can store a connection string
 
-If the devices have the ability to store the connection string to the previously provisioned and connected hub, use the same string to skip the entire reprovisioning process and directly connect to the hub. This reduces the latency in successfully connecting to the appropriate hub. There are two possible cases here:
+If the devices have the ability to store the connection string to the previously provisioned and connected IoT Hub, use the same string to skip the entire reprovisioning process and directly connect to the IoT Hub. This reduces the latency in successfully connecting to the appropriate IoT Hub. There are two possible cases here:
 
-- The IoT Hub to connect upon device reboot is the same as the previously connected hub.
+- The IoT Hub to connect upon device reboot is the same as the previously connected IoT Hub.
 
   The connection string retrieved from the cache should work fine and the device must attempt to reconnect to the same endpoint. No need for a fresh start for the provisioning process.
 
-- The IoT Hub to connect upon device reboot is different from the previously connected hub.
+- The IoT Hub to connect upon device reboot is different from the previously connected IoT Hub.
 
-  The connection string stored in memory is inaccurate, attempting to connect to the same endpoint won't be successful, and then the retry mechanism for the Hub connection is triggered. Once the threshold for the hub connection failure is reached, the retry mechanism automatically triggers a fresh start to the provisioning process.
+  The connection string stored in memory is inaccurate. Attempting to connect to the same endpoint won't be successful and so the retry mechanism for the IoT Hub connection is triggered. Once the threshold for the IoT Hub connection failure is reached, the retry mechanism automatically triggers a fresh start to the provisioning process.
 
 ### Devices that can't store a connection string
 
-In certain scenarios, devices don't have a large enough footprint or memory to accommodate caching of the connection string from a past successful IoT Hub connection. You can use the [Device Registration Status Lookup API](/rest/api/iot-dps/device/runtime-registration/device-registration-status-lookup) to retrieve the connection string from the previous time the device was provisioned and then attempt a connection to that IoT Hub. At every device reboot, that API needs to be invoked to get the device registration status. If data related to a previously connected hub was returned by the API call, you can connect to the same hub. If the API returns a null payload, then there's no previous connection available and the reprovisioning process through DPS is automatically triggered.
+In certain scenarios, devices don't have a large enough footprint or memory to accommodate caching of the connection string from a past successful IoT Hub connection. You can use the [Device Registration Status Lookup API](/rest/api/iot-dps/device/runtime-registration/device-registration-status-lookup) to retrieve the connection string from the previous time the device was provisioned and then attempt a connection to that IoT Hub. At every device reboot, that API needs to be invoked to get the device registration status. If data related to a previously connected IoT Hub was returned by the API call, you can connect to the same IoT Hub. If the API returns a null payload, then there's no previous connection available and the reprovisioning process through DPS is automatically triggered.
 
 ### Reprovisioning sample
 
@@ -156,10 +133,10 @@ if(provisioningDetails == null)
   provisioningDetailCache.SetProvisioningDetailResponse(registrationId, provisioningDetails);
 }
 
-// If there was Hub info from previous provisioning in the cache, try connecting to the hub directly
-// If trying to connect to the Hub returns status 429, make sure to retry operation honoring
+// If there was IoT Hub info from previous provisioning in the cache, try connecting to the IoT Hub directly
+// If trying to connect to the IoT Hub returns status 429, make sure to retry operation honoring
 //   the retry-after header
-// If trying to connect to the Hub returns a 500-series server error, have an exponential backoff with
+// If trying to connect to the IoT Hub returns a 500-series server error, have an exponential backoff with
 //   at least 5 seconds of wait-time
 // For all response codes 429 and 5xx, reprovision through DPS
 // Ideally, you should also support a method to manually trigger provisioning on demand
@@ -188,14 +165,37 @@ if (provisioningDetails != null)
 }
 ```
 
+## IoT Hub connectivity considerations
+
+- Any single IoT hub is limited to 1 million devices plus modules. If you plan to have more than a million devices, cap the number of devices to 1 million per hub and add hubs as needed when increasing the scale of your deployment. For more information, see [IoT Hub quotas](../iot-hub/iot-hub-devguide-quotas-and-throttling.md).
+- If you have plans for more than a million devices and you need to support them in a specific region (such as in an EU region for data residency requirements), you can [contact us](../iot-fundamentals/iot-support-help.md) to ensure that the region you're deploying to has the capacity to support your current and future scale.
+
+Recommended device logic when connecting to IoT Hub via DPS:
+
+- On first boot, devices should go use the [DPS registration API](/rest/api/iot-dps/device/runtime-registration/register-device) to register.
+- On subsequent boots, devices should:
+  - If possible, cache their provisioning details and connect using this information from this cache.
+  - If they can't cache IoT hub connection information, use the [Device Registration Status Lookup API](/rest/api/iot-dps/device/runtime-registration/device-registration-status-lookup) to return connection information once registration has been done. This API call is a much lighter weight operation for DPS than a full device registration operation.
+  - For devices in either case described above, devices should use the following logic in response to error codes when connecting:
+    - When receiving any of the 500-series of server error responses, retry the connection using either cached credentials or the results of a Device Registration Status Lookup API call.
+    - When receiving `401, Unauthorized` or `403, Forbidden` or `404, Not Found`, perform a full re-registration by calling the [DPS registration API](/rest/api/iot-dps/device/runtime-registration/register-device).
+- At any time, devices should be capable of responding to a user-initiated reprovisioning command.
+
+Other IoT Hub scenarios when using DPS:
+
+- IoT Hub failover: Devices should continue to work as connection information shouldn't change and logic is in place to retry the connection once the hub is available again.
+- Change of IoT Hub: Assigning devices to a different IoT Hub should be done by using a [custom allocation policy](tutorial-custom-allocation-policies.md).
+- Retry IoT Hub connection: You shouldn't use an aggressive retry strategy, instead allowing a gap of at least a minute before a retry.
+- IoT Hub partitions: If your device strategy leans heavily on telemetry, the number of device-to-cloud partitions should be increased.
+
 ## Monitoring devices
 
 An important part of the overall deployment is monitoring the solution end-to-end to make sure that the system is performing appropriately. There are several ways to monitor the health of a service for large-scale deployment of IoT devices. The following patterns have proven effective in monitoring the service:
 
-- Create an application to query each enrollment group on a DPS, get the total devices registered to that group, and then aggregate the numbers from across various enrollment groups. This number provides an exact count of the devices that are currently registered via a DPS and can be used to monitor the state of the service.
-- Monitor device registrations over a specific period. For instance, monitor registration rates for a DPS over the prior five days. Note that this approach only provides an approximate figure and is also capped to a time period.
+- Create an application to query each enrollment group on a DPS instance, get the total devices registered to that group, and then aggregate the numbers from across various enrollment groups. This number provides an exact count of the devices that are currently registered via DPS and can be used to monitor the state of the service.
+- Monitor device registrations over a specific period. For instance, monitor registration rates for a DPS instance over the prior five days. Note that this approach only provides an approximate figure and is also capped to a time period.
 
 ## Next steps
 
-- [Provision devices across load-balanced IoT hubs](tutorial-provision-multiple-hubs.md)
+- [Provision devices across load-balanced IoT Hubs](tutorial-provision-multiple-hubs.md)
 - [Retry timing](https://github.com/Azure/azure-sdk-for-c/blob/main/sdk/docs/iot/mqtt_state_machine.md#retry-timing) when retrying operations