Merge pull request #93974 from chrissie926/master

Add how-to-send-additional-data

Author: Ja-Dunn

articles/iot-dps/how-to-send-additional-data.md

@@ -0,0 +1,56 @@
+---
+title: How to transfer additional data between device and Azure Device Provisioning Service
+description: This document describes how to transfer additional data between device and DPS
+author: menchi
+ms.author: menchi
+ms.date: 10/29/2019
+ms.topic: conceptual
+ms.service: iot-dps
+services: iot-dps
+---
+
+# How to transfer additional data between device and DPS
+Sometimes DPS needs more data from devices to properly provision them to the right IoT Hub, and that data needs to be provided by the device. Vice versa, DPS can return data to the device to facilitate client side logics. 
+
+## When to use it
+This feature can be used as an enhancement for [custom allocation](https://docs.microsoft.com/azure/iot-dps/how-to-use-custom-allocation-policies). For instance, you want to allocate your devices based on the device model without human intervention. In this case, you will use [custom allocation](https://docs.microsoft.com/azure/iot-dps/how-to-use-custom-allocation-policies). You can configure the device to report the model information as part of the [register device call](https://docs.microsoft.com/rest/api/iot-dps/runtimeregistration/registerdevice). DPS will pass the device’s information into to the custom allocation webhook. And your function can decide which IoT Hub this device will go to when it receives device model information. Similarly, if the webhook wishes to return some data to the device, it will pass the data back as a string in the webhook response.  
+
+## Device sends data to DPS
+When your device is sending a [register device call](https://docs.microsoft.com/rest/api/iot-dps/runtimeregistration/registerdevice) to DPS. The register call can be enhanced to take other fields in the body. The body looks like the following: 
+   ```
+   { 
+       “registrationId”: “mydevice”, 
+       “tpm”:				 
+       { 
+           “endorsementKey”: “stuff”, 
+           “storageRootKey”: “things” 
+       }, 
+       “interfaces”: “TODO: get how interfaces are reported by devices from PnP folks.”, 
+       “data”: “your additional data goes here. It can be nested JSON.” 
+    } 
+   ```
+
+## DPS returns data to the device
+If the custom allocation policy webhook wishes to return some data to the device, it will pass the data back as a string in the webhook response. The change is in the returnData section below. 
+   ```
+   { 
+       "iotHubHostName": "sample-iot-hub-1.azure-devices.net", 
+       "initialTwin": { 
+           "tags": { 
+               "tag1": true 
+               }, 
+               "properties": { 
+                   "desired": { 
+                       "tag2": true 
+                    } 
+                } 
+            }, 
+        "returnData": "whatever is returned by the webhook" 
+    } 
+   ```
+
+## SDK support
+This feature is available in C, C#, JAVA and Node.js [client SDKs](https://docs.microsoft.com/azure/iot-dps/).  
+
+## Next steps
+* Develop using the [Azure IoT SDK]( https://github.com/Azure/azure-iot-sdks) for Azure IoT Hub and Azure IoT Hub Device Provisioning Service

articles/iot-dps/toc.yml

@@ -142,6 +142,8 @@
     href: how-to-legacy-device-symm-key.md
   - name: Use SDK tools for development
     href: how-to-use-sdk-tools.md
+  - name: How to send additional data from devices
+    href: how-to-send-additional-data.md
   - name: Troubleshooting
     href: how-to-troubleshoot-dps.md 
 - name: Reference