Update documentation from JS comments

sdk/docs/iot/pseudo_code_examples.md

@@ -0,0 +1,127 @@
+# Azure Embedded C SDK IoT Client Pseudo Code Examples
+
+## Introduction
+
+This page introduces you to coding examples that are MQTT stack agnostic. These examples will give you a general overview of the API calls and structure needed to use the Azure IoT Embedded C SDK features.
+
+For atomic API call examples, please view the [introductory examples](https:/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/README.md#examples) on the Azure IoT Client README file.
+
+For a more extensive demonstration of the API, please view and run the [sample code](https:/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/), which uses Paho MQTT.
+
+## Examples
+
+### IoT Hub Client with MQTT Stack
+
+Below is an implementation for using the IoT Hub Client SDK. This is meant to guide users in incorporating their MQTT stack with the IoT Hub Client SDK. Note for simplicity reasons, this code will not compile. Ideally, guiding principles can be inferred from reading through this snippet to create an IoT solution.
+
+```C
+#include <az/core/az_result.h>
+#include <az/core/az_span.h>
+#include <az/iot/az_iot_hub_client.h>
+
+az_iot_hub_client my_client;
+static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR("<your hub fqdn here>");
+static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR("<your device id here>");
+
+//Make sure the buffer is large enough to fit the user name (100 is an example)
+static char my_mqtt_user_name[100];
+
+//Make sure the buffer is large enough to fit the client id (16 is an example)
+static char my_mqtt_client_id[16];
+
+//This assumes an X509 Cert. SAS keys may also be used.
+static const char my_device_cert[]= "-----BEGIN CERTIFICATE-----abcdefg-----END CERTIFICATE-----";
+
+static char telemetry_topic[128];
+static char telemetry_payload[] = "Hello World";
+
+void handle_iot_message(mqtt_client_message* msg);
+
+int main(void)
+{
+ //Get the default IoT Hub options
+ az_iot_hub_client_options options = az_iot_hub_client_options_default();
+
+ //Initialize the client with hostname, device id, and options
+ az_iot_hub_client_init(&my_client, my_iothub_hostname, my_device_id, &options);
+
+ //Get the MQTT user name to connect
+ az_iot_hub_client_get_user_name(&my_client, my_mqtt_user_name,
+ sizeof(my_mqtt_user_name), NULL);
+
+ //Get the MQTT client id to connect
+ az_iot_hub_client_get_client_id(&my_client, my_mqtt_client_id,
+ sizeof(my_mqtt_client_id), NULL);
+
+ //Initialize MQTT client with necessary parameters (example params shown)
+ mqtt_client my_mqtt_client;
+ mqtt_client_init(&my_mqtt_client, my_iothub_hostname, my_mqtt_client_id);
+
+ //Subscribe to c2d messages
+ mqtt_client_subscribe(&my_mqtt_client, AZ_IOT_HUB_CLIENT_C2D_SUBSCRIBE_TOPIC);
+
+ //Subscribe to device methods
+ mqtt_client_subscribe(&my_mqtt_client, AZ_IOT_HUB_CLIENT_METHODS_SUBSCRIBE_TOPIC);
+
+ //Subscribe to twin patch topic
+ mqtt_client_subscribe(&my_mqtt_client, AZ_IOT_HUB_CLIENT_TWIN_PATCH_SUBSCRIBE_TOPIC);
+
+ //Subscribe to twin response topic
+ mqtt_client_subscribe(&my_mqtt_client, AZ_IOT_HUB_CLIENT_TWIN_RESPONSE_SUBSCRIBE_TOPIC);
+
+ //Connect to the IoT Hub with your chosen mqtt stack
+ mqtt_client_connect(&my_mqtt_client, my_mqtt_user_name, my_device_cert);
+
+ //This example would run to receive any incoming message and send a telemetry message five times
+ int iterations = 0;
+ mqtt_client_message msg;
+ while(iterations++ < 5)
+ {
+ if(mqtt_client_receive(&msg))
+ {
+ handle_iot_message(&msg);
+ }
+
+ send_telemetry_message();
+ }
+
+ //Disconnect from the IoT Hub
+ mqtt_client_disconnect(&my_mqtt_client);
+
+ //Destroy the mqtt client
+ mqtt_client_destroy(&my_mqtt_client);
+}
+
+void send_telemetry_message(void)
+{
+ //Get the topic to send a telemetry message
+ az_iot_hub_client_telemetry_get_publish_topic(&client, NULL, telemetry_topic, sizeof(telemetry_topic), NULL);
+
+ //Send the telemetry message with the MQTT client
+ mqtt_client_publish(telemetry_topic, telemetry_payload, AZ_HUB_CLIENT_DEFAULT_MQTT_TELEMETRY_QOS);
+}
+
+void handle_iot_message(mqtt_client_message* msg)
+{
+ //Initialize the incoming topic to a span
+ az_span incoming_topic = az_span_create(msg->topic, msg->topic_len);
+
+ //The message could be for three features so parse the topic to see which it is for
+ az_iot_hub_client_method_request method_request;
+ az_iot_hub_client_c2d_request c2d_request;
+ az_iot_hub_client_twin_response twin_response;
+ if (az_result_succeeded(az_iot_hub_client_methods_parse_received_topic(&client, incoming_topic, &method_request)))
+ {
+ //Handle the method request
+ }
+ else if (az_result_succeeded(az_iot_hub_client_c2d_parse_received_topic(&client, incoming_topic, &c2d_request)))
+ {
+ //Handle the c2d message
+ }
+ else if (az_result_succeeded(az_iot_hub_client_twin_parse_received_topic(&client, incoming_topic, &twin_response)))
+ {
+ //Handle the twin message
+ }
+}
+
+```

sdk/samples/iot/README.md

@@ -1,6 +1,9 @@
 # Azure Embedded C SDK IoT Samples
 
+## Table of Contents
+
 - [Azure Embedded C SDK IoT Samples](#azure-embedded-c-sdk-iot-samples)
+ - [Table of Contents](#table-of-contents)
  - [Introduction](#introduction)
  - [Prerequisites](#prerequisites)
  - [Sample Descriptions](#sample-descriptions)
@@ -33,7 +36,7 @@ This document explains samples for the Azure Embedded C SDK IoT Hub Client and D
 
 Samples are designed to highlight the function calls required to connect with the Azure IoT Hub or the Azure IoT Hub Device Provisioning Service (DPS). These calls illustrate the happy path of the [mqtt state machine](https:/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 utilize OpenSSL, which is **NOT recommended to use in production-level code on Windows or macOS**.
 
-The samples' instructions include specifics for both Windows and Linux based systems. For Windows, the command line examples are based on 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. While Windows and Linux devices are not likely to be considered constrained, these samples enable one to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities.
+The samples' instructions include specifics for both Windows and Linux based systems. For Windows, the command line examples are based on 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. While Windows and Linux devices are not likely to be considered constrained, these samples enable developers to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities.
 
 **WARNING: Samples are generic and should not be used in any production-level code.**
 

sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md

@@ -11,6 +11,8 @@
  - [IoT Hub Methods Sample](#iot-hub-methods-sample)
  - [IoT Hub Telemetry Sample](#iot-hub-telemetry-sample)
  - [IoT Hub Twin Sample](#iot-hub-twin-sample)
+ - [IoT Hub Plug and Play Sample](#iot-hub-plug-and-play-sample)
+ - [IoT Hub Plug and Play Multiple Component Sample](#iot-hub-plug-and-play-multiple-component-sample)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
  - [License](#license)
@@ -21,7 +23,7 @@ This is a step-by-step guide of how to start from scratch and get the Azure SDK
 
 Samples are designed to highlight the function calls required to connect with the Azure IoT Hub. These calls illustrate the happy path of the [mqtt state machine](https:/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.
 
-For Linux, the command line examples are tailored to Debian/Ubuntu environments. While Linux devices are not likely to be considered constrained, these samples enable one to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities.
+For Linux, the command line examples are tailored to Debian/Ubuntu environments. While Linux devices are not likely to be considered constrained, these samples enable developers to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities.
 
 NOTE: For simplicity in this instruction set, all repository downloads will be performed at the `\` root. Please feel free to use your preferred location.
 
@@ -44,10 +46,7 @@ To run the samples, ensure you have the following programs and tools installed o
 
  ```bash
  sudo apt-get update
- sudo apt-get install build-essential # make and gcc
- sudo apt-get install curl unzip tar pkg-config
- sudo apt-get install git
- sudo apt-get install openssl libssl-dev
+ sudo apt-get install build-essential curl unzip tar pkg-config git openssl libssl-dev
  ```
 
 ## Setup Instructions
@@ -237,6 +236,18 @@ For the sample description and interaction instructions, please go [here](https:
 
 For the sample description and interaction instructions, please go [here](https:/momuno/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md#iot-hub-twin-sample).
 
+### IoT Hub Plug and Play Sample
+
+- *Executable:* `paho_iot_hub_pnp_sample`
+
+For the sample description and interaction instructions, please go [here](https:/momuno/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md#iot-hub-plug-and-play-sample).
+
+### IoT Hub Plug and Play Multiple Component Sample
+
+- *Executable:* `paho_iot_hub_pnp_component_sample`
+
+For the sample description and interaction instructions, please go [here](https:/momuno/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md#iot-hub-plug-and-play-multiple-component-sample).
+
 ## Troubleshooting
 
 - The error policy for the Embedded C SDK client library is documented [here](https:/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#error-policy).

sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md

@@ -11,6 +11,8 @@
  - [IoT Hub Methods Sample](#iot-hub-methods-sample)
  - [IoT Hub Telemetry Sample](#iot-hub-telemetry-sample)
  - [IoT Hub Twin Sample](#iot-hub-twin-sample)
+ - [IoT Hub Plug and Play Sample](#iot-hub-plug-and-play-sample)
+ - [IoT Hub Plug and Play Multiple Component Sample](#iot-hub-plug-and-play-multiple-component-sample)
  - [Troubleshooting](#troubleshooting)
  - [Contributing](#contributing)
  - [License](#license)
@@ -21,7 +23,7 @@ This is a step-by-step guide of how to start from scratch and get the Azure SDK
 
 Samples are designed to highlight the function calls required to connect with the Azure IoT Hub. These calls illustrate the happy path of the [mqtt state machine](https:/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 utilize OpenSSL, which is **NOT recommended to use in production-level code on Windows or macOS**.
 
-For Windows, the command line examples are based on PowerShell. While Windows devices are not likely to be considered constrained, these samples enable one to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities.
+For Windows, the command line examples are based on PowerShell. While Windows devices are not likely to be considered constrained, these samples enable developers to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities.
 
 NOTE: For simplicity in this instruction set, all repository downloads will be performed at the `C:\` root. Please feel free to use your preferred location.
 
@@ -46,7 +48,7 @@ To run the samples, ensure you have the following programs and tools installed o
 
 ## Setup Instructions
 
-1. Install Microsoft [vcpkg](https:/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/).
+1. From PowerShell, install Microsoft [vcpkg](https:/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/).
 
  ```powershell
  PS C:\> git clone https:/Microsoft/vcpkg.git
@@ -241,6 +243,18 @@ For the sample description and interaction instructions, please go [here](https:
 
 For the sample description and interaction instructions, please go [here](https:/momuno/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md#iot-hub-twin-sample).
 
+### IoT Hub Plug and Play Sample
+
+- *Executable:* `paho_iot_hub_pnp_sample`
+
+For the sample description and interaction instructions, please go [here](https:/momuno/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md#iot-hub-plug-and-play-sample).
+
+### IoT Hub Plug and Play Multiple Component Sample
+
+- *Executable:* `paho_iot_hub_pnp_component_sample`
+
+For the sample description and interaction instructions, please go [here](https:/momuno/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md#iot-hub-plug-and-play-multiple-component-sample).
+
 ## Troubleshooting
 
 - The error policy for the Embedded C SDK client library is documented [here](https:/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#error-policy).