Skip to content

clean up iot sample readme to sync with master #1521

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
danewalton-msft merged 1 commit into from
Nov 16, 2020
Merged

clean up iot sample readme to sync with master #1521

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
303 changes: 0 additions & 303 deletions sdk/samples/iot/README.md
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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)
Expand Down Expand Up @@ -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=<FULL PATH to vcpkg>
```

Windows (PowerShell):

```powershell
$env:VCPKG_DEFAULT_TRIPLET='x64-windows-static' # Update triplet to match what was used during vcpkg install.
$env:VCPKG_ROOT='<FULL PATH to vcpkg>'
```

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 `<FULL PATH TO azure-sdk-for-c>\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='<FULL PATH TO azure-sdk-for-c>\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`

<details><summary><i>Instructions to run a Hub Certificate sample:</i></summary>
<p>

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=<device-id>
export AZ_IOT_HUB_HOSTNAME=<hostname>
```

Windows (PowerShell):

```powershell
$env:AZ_IOT_HUB_DEVICE_ID='<device-id>'
$env:AZ_IOT_HUB_HOSTNAME='<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)

</p>
</details>

### IoT Hub SAS Sample

*Executable:* `paho_iot_hub_sas_telemetry_sample`

<details><summary><i>Instructions to run a Hub SAS sample:</i></summary>
<p>

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=<sas-device-id>
export AZ_IOT_HUB_SAS_KEY=<sas-key>
export AZ_IOT_HUB_HOSTNAME=<hostname>
```

Windows (PowerShell):

```powershell
$env:AZ_IOT_HUB_SAS_DEVICE_ID='<sas-device-id>'
$env:AZ_IOT_HUB_SAS_KEY='<sas-key>'
$env:AZ_IOT_HUB_HOSTNAME='<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)

</p>
</details>

### IoT Provisioning Certificate Sample

*Executable:* `paho_iot_provisioning_sample`

<details><summary><i>Instructions to run a Provisioning Certificate sample:</i></summary>
<p>

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=<registration-id>
export AZ_IOT_PROVISIONING_ID_SCOPE=<id-scope>
```

Windows (PowerShell):

```powershell
$env:AZ_IOT_PROVISIONING_REGISTRATION_ID='<registration-id>'
$env:AZ_IOT_PROVISIONING_ID_SCOPE='<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)

</p>
</details>

### IoT Provisioning SAS Sample

*Executable:* `paho_iot_provisioning_sas_sample`

<details><summary><i>Instructions to run a Provisioning SAS sample:</i></summary>
<p>

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=<sas-registration-id>
export AZ_IOT_PROVISIONING_SAS_KEY=<sas-key>
export AZ_IOT_PROVISIONING_ID_SCOPE=<id-scope>
```

Windows (PowerShell):

```powershell
$env:AZ_IOT_PROVISIONING_SAS_REGISTRATION_ID='<sas-registration-id>'
$env:AZ_IOT_PROVISIONING_SAS_KEY='<sas-key>'
$env:AZ_IOT_PROVISIONING_ID_SCOPE='<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)

</p>
</details>

## 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/<sample executable here>
```

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!
Expand Down