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://github.com/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://github.com/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://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 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.**
 
@@ -66,8 +69,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 build-essential curl unzip tar pkg-config
     ```
 
     Windows (PowerShell):
@@ -78,7 +80,7 @@ To run the samples, ensure you have the following programs and tools installed o
     </details>
 
 - Have [Git](https://git-scm.com/download) installed.
-- Have Microsoft [vcpkg](https://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/) installed. On Linux, this installation may take an extended amount of time (~20-30 minutes).
+- Have Microsoft [vcpkg](https://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/) installed. On Linux, this installation may take an extended amount of time (~15-20 minutes).
 
     <details><summary><i>Instructions:</i></summary>
     <p>
@@ -129,21 +131,27 @@ To run the samples, ensure you have the following programs and tools installed o
     </p>
     </details>
 
-- Have the latest version of [CMake](https://cmake.org/download) installed. On Linux, this installation may also take an extended amount of time (~20-30 minutes).
+- Have CMake installed.
 
     <details><summary><i>Instructions:</i></summary>
     <p>
 
-    Linux:
+    Linux (Ubuntu 18.04 or 20.04):
 
     ```bash
-    sudo apt-get purge cmake
-    sudo tar -xvzf cmake-<latest-version>.tar.gz
-    cd cmake-<latest-version>
-    ./bootstrap && make && sudo make install
+    sudo apt-get install cmake
     ```
 
-    Windows (PowerShell):
+    Linux (Ubuntu 16.04): Download the latest version of [CMake](https://cmake.org/files).
+
+    ```bash
+    wget https://cmake.org/files/v<latest-version>/cmake-<latest-full-version>-Linux-x86_64.sh
+    sudo ./cmake-<latest-full-version>-Linux-x86_64.sh --prefix=/usr
+    ```
+
+    - When prompted to include the default subdirectory, enter `n` so to install in `/usr/local`.
+
+    Windows (PowerShell): Download the latest version of [CMake](https://cmake.org/download).
 
     - Use the Windows installer.
 
@@ -756,22 +764,12 @@ The resulting thumbprint will be placed in `fingerprint.txt` and the generated p
 
     From the root of the SDK directory `azure-sdk-for-c`:
 
-    Linux:
-
     ```bash
     mkdir build
     cd build
     cmake -DTRANSPORT_PAHO=ON ..
     ```
 
-    Windows (PowerShell):
-
-    ```powershell
-    mkdir build
-    cd build
-    cmake -DTRANSPORT_PAHO=ON ..
-    ```
-
 2. Compile and run the sample.
 
     Linux: