diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 237d9411f6..5b0114b297 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -27,15 +27,6 @@ - [IoT Plug and Play Multiple Component Sample](#iot-plug-and-play-multiple-component-sample) - [IoT Provisioning Certificate Sample](#iot-provisioning-certificate-sample) - [IoT Provisioning SAS Sample](#iot-provisioning-sas-sample) - - [Getting Started](#getting-started-1) - - [Set Environment Variables](#set-environment-variables-1) - - [Generate Device Certificate](#generate-device-certificate) - - [Sample Instructions](#sample-instructions) - - [IoT Hub Certificate Samples](#iot-hub-certificate-samples) - - [IoT Hub SAS Sample](#iot-hub-sas-sample) - - [IoT Provisioning Certificate Sample](#iot-provisioning-certificate-sample-1) - - [IoT Provisioning SAS Sample](#iot-provisioning-sas-sample-1) - - [Build and Run the Sample](#build-and-run-the-sample-1) - [Next Steps and Additional Documentation](#next-steps-and-additional-documentation) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) @@ -773,300 +764,6 @@ This section provides an overview of the different samples available to run and This [sample](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/paho_iot_provisioning_sas_sample.c) registers a device with the Azure IoT Device Provisioning Service. It will wait to receive the registration status before disconnecting. SAS authentication is used. -## Getting Started - -### Set Environment Variables - -Samples use environment variables for a variety of purposes, including filepaths and connection parameters. Please keep in mind, **every time a new terminal is opened, the environment variables will have to be reset**. Setting a variable will take the following form: - -**Linux:** - -```bash -export ENV_VARIABLE_NAME=VALUE -``` - -**Windows (PowerShell):** - -```powershell -$env:ENV_VARIABLE_NAME='VALUE' -``` - -Set the following environment variables for all samples: - - 1. Set the vcpkg environment variables. - - Refer to these [directions](https://github.com/Azure/azure-sdk-for-c#development-environment) for more detail. - - Linux: - - ```bash - export VCPKG_DEFAULT_TRIPLET=x64-linux - export VCPKG_ROOT= - ``` - - Windows (PowerShell): - - ```powershell - $env:VCPKG_DEFAULT_TRIPLET='x64-windows-static' # Update triplet to match what was used during vcpkg install. - $env:VCPKG_ROOT='' - ``` - - 2. Set the trust pem filepath. **Only for Windows or if required by OS.** - - Download [BaltimoreCyberTrustRoot.crt.pem](https://cacerts.digicert.com/BaltimoreCyberTrustRoot.crt.pem) to `\sdk\samples\iot\`. Confirm the downloaded certificate uses the correct file name and file extension. - - Windows (PowerShell): - - ```powershell - $env:AZ_IOT_DEVICE_X509_TRUST_PEM_FILE_PATH='\sdk\samples\iot\BaltimoreCyberTrustRoot.crt.pem' - ``` - -### Generate Device Certificate - -For samples using certificates, x509 authentication is used to connect to Azure IoT Hub or Azure IoT Hub DPS. - -**WARNING: Certificates created by these commands MUST NOT be used in production-level code on Windows or macOS.** These certificates expire after 365 days and are provided ONLY to help you easily understand CA Certificates. When productizing against CA Certificates, you will need to use your own security best practices for certificate creation and lifetime management. - - - *Executables:* `paho_iot_hub_c2d_sample`, `paho_iot_hub_methods_sample`, `paho_iot_hub_telemetry_sample`, `paho_iot_hub_twin_sample`, `paho_iot_pnp_sample`, `paho_iot_pnp_component_sample`, `paho_iot_provisioning_sample` - -The resulting thumbprint will be placed in `fingerprint.txt` and the generated pem file is named `device_ec_cert.pem`. - -**Linux:** - - 1. Enter the directory `azure-sdk-for-c/sdk/samples/iot/`. - 2. Run the following commands: - - ```bash - openssl ecparam -out device_ec_key.pem -name prime256v1 -genkey - openssl req -new -days 365 -nodes -x509 -key device_ec_key.pem -out device_ec_cert.pem -config x509_config.cfg -subj "/CN=paho-sample-device1" - openssl x509 -noout -text -in device_ec_cert.pem - - rm -f device_cert_store.pem - cat device_ec_cert.pem device_ec_key.pem > device_cert_store.pem - - openssl x509 -noout -fingerprint -in device_ec_cert.pem | sed 's/://g'| sed 's/\(SHA1 Fingerprint=\)//g' | tee fingerprint.txt - - export AZ_IOT_DEVICE_X509_CERT_PEM_FILE_PATH=$(pwd)/device_cert_store.pem - ``` - -**Windows (PowerShell):** - - 1. Enter the directory `azure-sdk-for-c\sdk\samples\iot\`. - 2. Run the following commands: - - ```powershell - openssl ecparam -out device_ec_key.pem -name prime256v1 -genkey - openssl req -new -days 365 -nodes -x509 -key device_ec_key.pem -out device_ec_cert.pem -config x509_config.cfg -subj "/CN=paho-sample-device1" - openssl x509 -noout -text -in device_ec_cert.pem - - Get-Content device_ec_cert.pem, device_ec_key.pem | Set-Content device_cert_store.pem - - openssl x509 -noout -fingerprint -in device_ec_cert.pem | % {$_.replace(":", "")} | % {$_.replace("SHA1 Fingerprint=", "")} | Tee-Object fingerprint.txt - - $env:AZ_IOT_DEVICE_X509_CERT_PEM_FILE_PATH=$(Resolve-Path device_cert_store.pem) - ``` - -## Sample Instructions - -### IoT Hub Certificate Samples - -*Executables:* -- `paho_iot_hub_c2d_sample` -- `paho_iot_hub_methods_sample` -- `paho_iot_hub_telemetry_sample` -- `paho_iot_hub_twin_sample` -- `paho_iot_pnp_sample` -- `paho_iot_pnp_component_sample` - -
Instructions to run a Hub Certificate sample: -

- -1. In your Azure IoT Hub, add a new device using a self-signed certificate. See [here](https://docs.microsoft.com/azure/iot-hub/iot-hub-security-x509-get-started#create-an-x509-device-for-your-iot-hub) for further instruction, with one exception--**DO NOT** select X.509 CA Signed as the authentication type. Select **X.509 Self-Signed**. - - For the Thumbprint, use the recently generated fingerprint, which has been placed in the file `fingerprint.txt`. - -2. Set the following environment variables: - - - `AZ_IOT_HUB_DEVICE_ID`: Select your device from the IoT Devices page and copy its Device Id. - - `AZ_IOT_HUB_HOSTNAME`: Copy the Hostname from the Overview tab in your Azure IoT Hub. - - Linux: - - ```bash - export AZ_IOT_HUB_DEVICE_ID= - export AZ_IOT_HUB_HOSTNAME= - ``` - - Windows (PowerShell): - - ```powershell - $env:AZ_IOT_HUB_DEVICE_ID='' - $env:AZ_IOT_HUB_HOSTNAME='' - ``` - -3. [Build and run the sample](#build-and-run-the-sample). - -4. See the sample description for interaction instructions: - - - [`paho_iot_hub_c2d_sample`](#iot-hub-c2d-sample) - - [`paho_iot_hub_methods_sample`](#iot-hub-methods-sample) - - [`paho_iot_hub_telemetry_sample`](#iot-hub-telemetry-sample) - - [`paho_iot_hub_twin_sample`](#iot-hub-twin-sample) - - [`paho_iot_pnp_sample`](#iot-hub-plug-and-play-sample) - - [`paho_iot_pnp_component_sample`](#iot-hub-plug-and-play-muiltiple-component-sample) - -

-
- -### IoT Hub SAS Sample - -*Executable:* `paho_iot_hub_sas_telemetry_sample` - -
Instructions to run a Hub SAS sample: -

- -1. In your Azure IoT Hub, add a new device using a symmetric key. See [here](https://docs.microsoft.com/azure/iot-hub/iot-hub-create-through-portal#register-a-new-device-in-the-iot-hub) for further instruction. - -2. Set the following environment variables: - - - `AZ_IOT_HUB_SAS_DEVICE_ID`: Select your device from the IoT Devices page and copy its Device Id. - - `AZ_IOT_HUB_SAS_KEY`: Copy its Primary Key from the same page. - - `AZ_IOT_HUB_HOSTNAME`: Copy the Hostname from the Overview tab in your Azure IoT Hub. - - Linux: - - ```bash - export AZ_IOT_HUB_SAS_DEVICE_ID= - export AZ_IOT_HUB_SAS_KEY= - export AZ_IOT_HUB_HOSTNAME= - ``` - - Windows (PowerShell): - - ```powershell - $env:AZ_IOT_HUB_SAS_DEVICE_ID='' - $env:AZ_IOT_HUB_SAS_KEY='' - $env:AZ_IOT_HUB_HOSTNAME='' - ``` - -3. [Build and run the sample](#build-and-run-the-sample). - -4. See the sample description for interaction instructions: - - - [`paho_iot_hub_sas_telemetry_sample`](#iot-hub-sas-telemetry-sample) - -

-
- -### IoT Provisioning Certificate Sample - -*Executable:* `paho_iot_provisioning_sample` - -
Instructions to run a Provisioning Certificate sample: -

- -1. In your Azure IoT Hub DPS, add a new individual device enrollment using the recently generated `device_ec_cert.pem` file. See [here](https://docs.microsoft.com/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. - -2. Set the following environment variables: - - - `AZ_IOT_PROVISIONING_REGISTRATION_ID`: This should be `paho-sample-device1`. - - `AZ_IOT_PROVISIONING_ID_SCOPE`: Copy the Id Scope from the Overview tab in your Azure IoT Hub DPS. - - Linux: - - ```bash - export AZ_IOT_PROVISIONING_REGISTRATION_ID= - export AZ_IOT_PROVISIONING_ID_SCOPE= - ``` - - Windows (PowerShell): - - ```powershell - $env:AZ_IOT_PROVISIONING_REGISTRATION_ID='' - $env:AZ_IOT_PROVISIONING_ID_SCOPE='' - ``` - -3. [Build and run the sample](#build-and-run-the-sample). - -4. See the sample description for interaction instructions: - - - [`paho_iot_provisioning_sample`](#iot-provisioning-sample) - -

-
- -### IoT Provisioning SAS Sample - -*Executable:* `paho_iot_provisioning_sas_sample` - -
Instructions to run a Provisioning SAS sample: -

- -1. In your Azure IoT Hub DPS, add a new individual device enrollment using a symmetric key. See [here](https://docs.microsoft.com/azure/iot-dps/quick-create-simulated-device-symm-key#create-a-device-enrollment-entry-in-the-portal) for further instruction. After creation, the Registration ID of your device will appear in the Individual Enrollments tab. - -2. Set the following environment variables: - - - `AZ_IOT_PROVISIONING_SAS_REGISTRATION_ID`: Copy the Registration Id of your SAS device from the Individual Enrollments tab. - - `AZ_IOT_PROVISIONING_SAS_KEY`: Select your SAS device from the Individual Enrollments tab and copy its Primary Key. - - `AZ_IOT_PROVISIONING_ID_SCOPE`: Copy the Id Scope from the Overview tab in your Azure IoT Hub DPS. - - Linux: - - ```bash - export AZ_IOT_PROVISIONING_SAS_REGISTRATION_ID= - export AZ_IOT_PROVISIONING_SAS_KEY= - export AZ_IOT_PROVISIONING_ID_SCOPE= - ``` - - Windows (PowerShell): - - ```powershell - $env:AZ_IOT_PROVISIONING_SAS_REGISTRATION_ID='' - $env:AZ_IOT_PROVISIONING_SAS_KEY='' - $env:AZ_IOT_PROVISIONING_ID_SCOPE='' - ``` - -3. [Build and run the sample](#build-and-run-the-sample). - -4. See the sample description for interaction instructions: - - - [`paho_iot_provisioning_sas_sample`](#iot-provisioning-sas-sample) - -

-
- -## Build and Run the Sample - -1. Build the Azure SDK for Embedded C directory structure. - - From the root of the SDK directory `azure-sdk-for-c`: - - ```bash - mkdir build - cd build - cmake -DTRANSPORT_PAHO=ON .. - ``` - -2. Compile and run the sample. - - Linux: - - ```bash - cmake --build . - ./sdk/samples/iot/ - ``` - - Windows (PowerShell): - - ```powershell - .\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. - - Right-click on the sample project, then click on "Set as Startup Project". (This makes it the default startup project.) - - Build and run the project (`F5` on most installations). - ## Next Steps and Additional Documentation Start using the Azure Embedded C SDK IoT Clients in your solutions!