Dps sample/documentation

sdk/samples/iot/hub/README.md

@@ -11,30 +11,30 @@ urlFragment: iot-hub-samples
 
 # Azure IoT Hub Samples
 
-This document explains samples for the Azure SDK for Embedded C IoT Hub Client and how to use them. 
+This document explains samples for the Azure SDK for Embedded C IoT Hub Client and how to use them.
 
 For step-by-step guides starting from scratch, you may refer to these documents:
   - Linux: [How to setup and run Azure SDK for Embedded C IoT Hub Samples on Linux](./linux/how_to_iot_hub_samples_linux.md)
   - Windows: [How to setup and run Azure SDK for Embedded C IoT Hub Samples on Microsoft Windows](./windows/how_to_iot_hub_samples_windows.md).
   - ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](./aziot_esp8266/how_to_esp8266_nodemcu.md)
 
-  **Note**: While Windows and Linux devices are not likely to be considered as constrained ones, these samples were created to make it simpler to test the Azure SDK for Embedded C libraries, even without a real device. 
+  **Note**: While Windows and Linux devices are not likely to be considered as constrained ones, these samples were created to make it simpler to test the Azure SDK for Embedded C libraries, even without a real device.
 
 
 ## Key Concepts
 
-Key concepts are explained in detail [here][SDK_README_KEY_CONCEPTS].
+Key concepts are explained in detail [here][sdk_readme_key_concepts].
 
 ## Prerequisites
 
 - To generate the device certificate, the provided script uses [OpenSSL 1.1.1 LTS](https://www.openssl.org/source/). Please
 install the OpenSSL command line utility prior to using the script.
-  - Note: for Linux based systems, manual installation from source can be risky ([details here](https://github.com/openssl/openssl/issues/11227#issuecomment-616445289)). We recommend installing for Linux via apt:  
+  - Note: for Linux based systems, manual installation from source can be risky ([details here](https://github.com/openssl/openssl/issues/11227#issuecomment-616445289)). We recommend installing for Linux via apt:
   ```bash
   sudo apt-get install libssl-dev
   ```
 - To use the samples, we use [Eclipse Paho MQTT C client][Eclipse_Paho]. You can use the directions
-[here][VCPKG_DIRECTIONS] to set up VCPKG to download and manage linking the dependency.
+[here][vcpkg_directions] to set up VCPKG to download and manage linking the dependency.
 
 ## Getting Started
 
@@ -64,7 +64,7 @@ For all of these samples, the following environment variables will need to be se
 
 **NOTE**: These need to be set before running the cmake commands.
 
-- `VCPKG_DEFAULT_TRIPLET`: The triplet created using the instructions [here][VCPKG_DIRECTIONS].
+- `VCPKG_DEFAULT_TRIPLET`: The triplet created using the instructions [here][vcpkg_directions].
 - `VCPKG_ROOT`: The full path to the VCPKG directory used to generate the triplet.
 - `AZ_IOT_DEVICE_ID`: Your device id.
 - `AZ_IOT_HUB_HOSTNAME`: The hostname of your IoT Hub.
@@ -99,11 +99,11 @@ Send 5 telemetry messages using the IoT Hub Client with certificate authenticati
 Use device twin features such as receiving the twin document, updating reported properties, and sending desired properties using the Azure IoT Hub Client.
 This sample uses a property named `device_count`, which records the number of times the device sends a reported property message to the service.
 
-* To initiate a GET response request from the device, you will use the command `g`. 
+* To initiate a GET response request from the device, you will use the command `g`.
 
 * To initiate a reported property message from the device, you will use the command `r`.
 
-* To send a device twin desired property message from the service to the device, open the device twin document in your Azure IoT Hub.  Add the property `device_count` along with a corresponding value to the `desired` section of the JSON.  
+* To send a device twin desired property message from the service to the device, open the device twin document in your Azure IoT Hub.  Add the property `device_count` along with a corresponding value to the `desired` section of the JSON.
 ```json
 {
   "properties": {
@@ -131,7 +131,7 @@ Receive and view incoming C2D messages using the IoT Hub Client.
 ### [IoT Hub PnP (Certificates)][pnp_sample]
 Connect a PnP enabled device with the Digital Twin Model ID (DTMI) detailed [here](https://github.com/Azure/opendigitaltwins-dtdl/blob/master/DTDL/v2/samples/Thermostat.json).
 In short, the capabilities are listed here:
-- **Methods**: Invoke a method called `getMaxMinReport` with JSON payload value `"since"` with an [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) value for start time for the report. The method sends a response containing the following JSON payload:  
+- **Methods**: Invoke a method called `getMaxMinReport` with JSON payload value `"since"` with an [ISO8601](https://en.wikipedia.org/wiki/ISO_8601) value for start time for the report. The method sends a response containing the following JSON payload:
 ```json
 {
   "maxTemp": 20,
@@ -151,23 +151,27 @@ When interacting with the Azure IoT Hub using this C client library, errors are
 
 ## Next Steps
 
-Start using the IoT Hub Client in your solutions. More SDK details can be found in [SDK README][IOT_CLIENT_README].
+Start using the IoT Hub Client in your solutions. More SDK details can be found in [SDK README][iot_client_readme].
 
 ### Additional Documentation
 
 For extensive documentation on Azure IoT Hub, see the [API reference documentation][iot_hub_mqtt].
 
+## Contributing
+
+This project welcomes contributions and suggestions. Find [more contributing][sdk_readme_contributing] details here.
+
 <!-- LINKS -->
-[IOT_CLIENT_README]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients
-[SDK_README_GETTING_STARTED]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#getting-started
-[SDK_README_KEY_CONCEPTS]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients
-[VCPKG_DIRECTIONS]:https://github.com/Azure/azure-sdk-for-c#development-environment
+[iot_client_readme]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients
+[sdk_readme_key_concepts]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients
+[vcpkg_directions]:https://github.com/Azure/azure-sdk-for-c#development-environment
 [c2d_sample]: src/paho_iot_hub_c2d_example.c
 [methods_sample]: src/paho_iot_hub_methods_example.c
 [telemetry_sample_sas]: src/paho_iot_hub_sas_telemetry_example.c
 [telemetry_sample_cert]: src/paho_iot_hub_telemetry_example.c
 [twin_sample]: src/paho_iot_hub_twin_example.c
 [pnp_sample]: src/paho_iot_hub_pnp_example.c
-[iot_hub_mqtt]: https://docs.microsoft.com/en-us/azure/iot-dps/iot-dps-mqtt-support
+[iot_hub_mqtt]: https://docs.microsoft.com/en-us/azure/iot-hub/about-iot-hub
 [error_codes]: ../../../../sdk/docs/iot/mqtt_state_machine.md#iot-service-errors
 [Eclipse_Paho]: https://www.eclipse.org/paho/clients/c/
+[sdk_readme_contributing]: https://github.com/Azure/azure-sdk-for-c/tree/master#contributing

sdk/samples/iot/provisioning/README.md

@@ -11,50 +11,130 @@ urlFragment: iot-provisioning-samples
 
 # Azure IoT Device Provisioning Service Sample
 
-This document explains samples for the Azure Embedded C SDK IoT Provisioning Client and how to use them.
+## Introduction
+This document explains samples for the Azure Embedded C SDK IoT Device Provisioning Client and how to use them.
 
-## Key Concepts
+Samples are designed to highlight the function calls required to connect with the Device Provisioning Service (DPS). These calls illustrate the happy path of the [mqtt state machine](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md). As a result,  **these samples are NOT designed to be used as production-level code**. Production code needs to incorporate other elements, such as connection retries and more extensive error-handling, which these samples do not include.  These samples also utilizes OpenSSL, which is **NOT recommended to use in production code on Windows or macOS**.
 
-Key concepts are explained in detail [here][SDK_README_KEY_CONCEPTS].
+The samples' instructions include specifics for both Windows and Linux based systems.  For Windows, the command line examples are based on the Command Prompt and not PowerShell.  The Linux examples are tailored to Debian/Ubuntu environments.  Samples are also designed to work on macOS systems, but the instructions do not yet include specific command line examples for this environment.
 
-## Samples for Azure IoT Provisioning Client APIs
+## Key Concepts
 
-This document describes how to use samples and what is done in each sample.
+Further background on the Azure IoT Client library and key concepts are explained in detail in the [Azure IoT Client README](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients).
+
+## Prerequisites
+
+* Have an [Azure account](https://azure.microsoft.com/en-us/) created.
+* Have an [Azure IoT Hub](https://docs.microsoft.com/en-us/azure/iot-hub/iot-hub-create-through-portal) created.
+* Have an [Azure IoT Hub Device Provisioning Service (DPS)](https://docs.microsoft.com/en-us/azure/iot-dps/quick-setup-auto-provision) created.
+* Have [git](https://git-scm.com/download) installed.
+* Have [OpenSSL](https://www.openssl.org/source/) installed:
+  * For Linux based systems, we recommend:
+	 ```bash
+	  sudo apt-get install libssl-dev
+	```
+  * For non-Linux based systems, download the [OpenSSL 1.1.1 LTS](https://www.openssl.org/source/openssl-1.1.1g.tar.gz) command line utility and follow the downloaded INSTALL document.
+* Have the following build setup:
+	* For Linux based systems, have make installed:
+	  ```bash
+	  sudo apt-get install build-essential
+	  ```
+	 * For Windows systems, have [Microsoft Visual Studio](https://visualstudio.microsoft.com/downloads/) installed.
+	 * For all systems, have the latest version of [CMake](https://cmake.org/download) installed.
+* Have Microsoft [VCPKG](https://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/) installed.  Use the directions [here](https://github.com/Azure/azure-sdk-for-c#development-environment) to download VCPKG and install Paho MQTT.
 
 ## Getting Started
 
-Getting started explained in detail [here][SDK_README_GETTING_STARTED].
-
-## Examples
-
-   Following section document various examples.
-
-1. [IoT Provisioning using Paho][samples_paho]: Register a device using the IoT Provisioning client and the [Eclipse Paho MQTT C client][Eclipse_Paho].
+All samples require either x509 certification or SAS symmetric key authentication to connect to Azure IoT Hub Device Provisioning Service (DPS).  To easily run this sample, we have provided a script to generate a self-signed device certification used for device authentication.  Three different `.pem` files will be produced.  **This script is intended for sample use only and not to be used in production code**.
+1. Enter the directory `/azure-sdk-for-c/sdk/samples/iot/provisioning/src/` and run the script using the following form:
+
+    Linux:
+    ```bash
+    ./generate_certificate.sh
+    ```
+    Windows:
+    ```cmd
+    generate_certificate.cmd
+    ```
+
+2. For Windows (or if required on your OS), set the environment variable `AZ_IOT_DEVICE_X509_TRUST_PEM_FILE` to the path of the BaltimoreCyberTrustRoot.crt.pem file noted near the bottom of the output. You must [download this pem file](https://cacerts.digicert.com/BaltimoreCyberTrustRoot.crt.pem) and store it in the location specified by that filepath.
+
+3. The remaining output will be used in the next steps.
+### #Paho IoT Provisioning (Certificates)
+**Executable:** paho_iot_provisioning_sample
+
+This [sample](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/provisioning/src/paho_iot_provisioning_example.c) uses x509 authentication to connect to Azure IoT Hub Device Provisioning Service (DPS).
+1. Set the environment variable `AZ_IOT_DEVICE_X509_CERT_PEM_FILE` to the path of the generated .pem file noted at the bottom of the output.
+
+2. In your Azure DPS, add a new individual device enrollment using the recently generated `device_ec_cert.pem` file.  See [here](https://docs.microsoft.com/en-us/azure/iot-dps/quick-create-simulated-device-x509#create-a-device-enrollment-entry-in-the-portal) for further instruction.  After creation, the Registration ID of your device should appear as `paho-sample-device1` in the Individual Enrollments tab.
+
+### Paho IoT Provisioning (SAS)
+**Executable:** paho_iot_provisioning_sas_sample
+
+This [sample](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/provisioning/src/paho_iot_provisioning_sas_example.c) uses SAS symmetric key authentication to connect to Azure IoT Hub Device Provisioning Service (DPS).
+
+* In your Azure DPS, add a new individual device enrollment using SAS. See [here](https://docs.microsoft.com/en-us/azure/iot-dps/quick-create-simulated-device-symm-key#create-a-device-enrollment-entry-in-the-portal) for further instruction, with one exception--for the Primary Key, **you must use** the fingerprint noted in the output.  **Do NOT use** the *Auto-generate keys* option. After creation, the Registration ID of your device will appear in the Individual Enrollments tab.
+
+## Build and Run the Sample
+
+1. Set the remaining environment variables.  Setting a variable will take the following form:
+
+	  Linux:
+	  ```bash
+	  export ENV_VARIABLE_NAME=VALUE
+	  ```
+	  Windows:
+	  ```cmd
+	  set "ENV_VARIABLE_NAME=VALUE"
+	  ```
+	#### Paho IoT Provisioning (Certificates)
+  * `VCPKG_DEFAULT_TRIPLET` and `VCPKG_ROOT`: These should already be set per these [directions](https://github.com/Azure/azure-sdk-for-c#development-environment).
+  * `AZ_IOT_DEVICE_X509_CERT_PEM_FILE`: This should already be set per directions above.
+  * `AZ_IOT_ID_SCOPE`: Copy this value from the Overview tab in your Azure DPS.
+  * `AZ_IOT_REGISTRATION_ID`: This should be `paho-sample-device1`.
+	#### Paho IoT Provisioning (SAS)
+  * `VCPKG_DEFAULT_TRIPLET` and `VCPKG_ROOT`: These should already be set per these [directions](https://github.com/Azure/azure-sdk-for-c#development-environment).
+  * `AZ_IOT_PROVISIONING_SAS_KEY`: Select your enrolled device from the Individual Enrollments tab and copy its Primary Key.
+  * `AZ_IOT_ID_SCOPE`: Copy this value from the Overview tab in your Azure DPS.
+  * `AZ_IOT_REGISTRATION_ID_SAS`: Copy the Registration Id of your SAS device from the Individual Enrollments tab.
+
+2. Compile the code:
+  * Enter the directory `/azure-sdk-for-c/cmake`.  If it does not exist, please create it.
+  * Build the directory structure and the samples:
+
+    ```bash
+    cmake -DTRANSPORT_PAHO=ON ..
+    cmake --build .
+    ```
+3. From within the cmake directory, run the sample:
+
+    Linux:
+    ```bash
+    ./sdk/samples/iot/provisioning/<sample executable here>
+    ```
+    Windows:
+    ```cmd
+    az.sln
+    ```
+	Once the Windows solution opens in Visual Studio:
+    * Navigate on the Solution Explorer panel to the sample project you would like to run.
+    * Make it the default startup project (right-click on the sample project, then click on Set as Startup Project).
+    * Build and run the project (F5 on most installations).
 
 ## Troubleshooting
 
-When interacting with the Azure Device Provisioning Service using this C client library, errors are documented within the [MQTT State Machine][error_codes] requests.
+The error policy in using the Embedded C SDK client library is documented [here](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#error-policy).
 
-## Next Steps
+## Next Steps and Additional Documentation
 
-Start using the IoT Provisioning Client in your solutions. Our SDK details can be found at [SDK README][IOT_CLIENT_README].
+Start using the IoT Provisioning Client in your solutions!
 
-### Additional Documentation
+* A general overivew of the Embedded C SDK and additional background on running samples can be found in the [Azure SDK for Embedded C README](https://github.com/Azure/azure-sdk-for-c#azure-sdk-for-embedded-c).
+* More SDK details pertaining to IoT Client can be found in the [Azure IoT Client README](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients).
+* The [Azure IoT Client MQTT State Machine](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md) provides a high-level architecture and API information.
+* For extensive documentation on the Azure IoT Hub Device Provisioning Service, see the [Microsoft reference documentation](https://docs.microsoft.com/en-us/azure/iot-dps/).
 
-For extensive documentation on Azure Device Provisioning Service, see the [API reference documentation][iot_provisioning_mqtt].
 
 ## Contributing
 
-This project welcomes contributions and suggestions. Find [more contributing][SDK_README_CONTRIBUTING] details here.
-
-<!-- LINKS -->
-[IOT_CLIENT_README]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients
-[SDK_README_CONTRIBUTING]:https://github.com/Azure/azure-sdk-for-c/tree/master#contributing
-[SDK_README_GETTING_STARTED]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#getting-started
-[SDK_README_KEY_CONCEPTS]: https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot#azure-iot-clients
-[samples_paho]: src/paho_iot_provisioning_example.c
-[iot_provisioning_mqtt]: https://docs.microsoft.com/en-us/azure/iot-dps/iot-dps-mqtt-support
-[error_codes]: ../../../../sdk/docs/iot/mqtt_state_machine.md#iot-service-errors
-[Eclipse_Paho]: https://www.eclipse.org/paho/clients/c/
-
-![Impressions](https://azure-sdk-impressions.azurewebsites.net/api/impressions/azure-sdk-for-c%2Fsdk%2Fiot%2Fprovisioning%2Fsamples%2FREADME.png)
+This project welcomes contributions and suggestions. Find more contributing details [here](https://github.com/Azure/azure-sdk-for-c/tree/master#contributing).

sdk/samples/iot/provisioning/src/generate_certificate.cmd

@@ -20,32 +20,34 @@ openssl x509 -noout -text -in device_ec_cert.pem
 type device_ec_cert.pem > device_cert_store.pem
 type device_ec_key.pem >> device_cert_store.pem
 
+FOR /F "tokens=*" %%a in ('openssl x509 -noout -fingerprint -in device_ec_cert.pem') do SET output=%%a
+set fingerprint=%output::=%
+echo %fingerprint% > fingerprint.txt
+
 echo.
+echo IMPORTANT:
 echo It is NOT recommended to use OpenSSL on Windows or OSX. Recommended TLS stacks are:
 echo Microsoft Windows SChannel: https://docs.microsoft.com/en-us/windows/win32/com/schannel
 echo OR
 echo Apple Secure Transport : https://developer.apple.com/documentation/security/secure_transport
 echo If using OpenSSL, it is recommended to use the OpenSSL Trusted CA store configured on your system.
 echo.
+echo.
+echo SAS SAMPLES:
+echo Use the following fingerprint when enrolling your device in Device Provisioning Service.
+echo The fingerprint has also been placed in fingerprint.txt for future reference.
+echo.
+echo %fingerprint%
+echo.
+echo.
+echo CERTIFICATE SAMPLES:
 echo If required (for example on Windows), download the Baltimore PEM CA from https://www.digicert.com/digicert-root-certificates.htm to the current folder.
 echo Once it is downloaded, run the following command to set the environment variable for the samples:
 echo.
-echo    set "AZ_IOT_DEVICE_X509_TRUST_PEM_FILE=%CD%\BaltimoreCyberTrustRoot.crt.pem"
+echo        set "AZ_IOT_DEVICE_X509_TRUST_PEM_FILE=%CD%\BaltimoreCyberTrustRoot.crt.pem"
 echo.
 echo Sample certificate generated:
 echo Upload device_ec_cert.pem to Device Provisioning Service.
 echo Use the following command to set the environment variable for the samples:
 echo.
-echo    set "AZ_IOT_DEVICE_X509_CERT_PEM_FILE=%CD%\device_cert_store.pem"
-echo.
-echo Use the following fingerprint when enrolling your device in Device Provisioning Service:
-
-FOR /F "tokens=*" %%a in ('openssl x509 -noout -fingerprint -in device_ec_cert.pem') do SET output=%%a
-set fingerprint=%output::=%
-
-echo %fingerprint%
-
-echo %fingerprint% > fingerprint.txt
-
-echo.
-echo The fingerprint has also been placed in fingerprint.txt for future reference
+echo        set "AZ_IOT_DEVICE_X509_CERT_PEM_FILE=%CD%\device_cert_store.pem"