From bd76db872a795bcf9682e8e1f7de737555e512be Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 29 Sep 2020 22:08:50 -0700 Subject: [PATCH 01/24] docs iot README update --- sdk/docs/iot/README.md | 265 ++++++++++---------------------------- sdk/samples/iot/README.md | 3 + 2 files changed, 74 insertions(+), 194 deletions(-) diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index e45f8fd6f7..b9f8eff5b0 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -9,17 +9,15 @@ Here you will find everything you need to get devices connected to Azure. - [Azure IoT Clients](#azure-iot-clients) - [Table of Contents](#table-of-contents) - [Getting Started](#getting-started) - - [Docs](#docs) + - [Documentation](#documentation) - [Build](#build) - [Samples](#samples) - - [Prerequisites](#prerequisites) - [Key Features](#key-features) - [Examples](#examples) - [IoT Hub Client Initialization](#iot-hub-client-initialization) - [Properties](#properties) - [Telemetry](#telemetry) - - [IoT Hub Client with MQTT Stack](#iot-hub-client-with-mqtt-stack) - - [Need Help?](#need-help) + - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) - [License](#license) @@ -29,19 +27,18 @@ The Azure IoT Client library is created to facilitate connectivity to Azure IoT ![Methods](./resources/embc_high_level_arch.png) -From a functional perspective, this means that the user's application code (not the SDK) calls directly to the MQTT stack of their choice. The SDK provides utilities (in the form of functions, default values, etc) which help make the connection and feature set easier. Some examples of those utilities include: +From a functional perspective, this means that the user's application code (not the SDK) calls directly to the MQTT stack of their choice. The SDK provides utilities (functions, default values, etc.) that help make the connection and feature set easier to use. Some examples of those utilities include: -- Publish topics to which messages can be sent and subscription topics to which users can subscribe for incoming messages. -- Functions to parse incoming message topics which populate structs with crucial message information. +- Publish topics to which messages can be sent. +- Subscription topics to which users can subscribe for incoming messages. +- Functions to parse incoming message topics, which populate structs with crucial message information. - Default values for MQTT connect keep alive and connection port. -A full list of features can be found in the doxygen docs listed below in [Docs](#docs). +**NOTE**: This Embedded C SDK requires a different programming model as compared to the earlier version of the [C SDK](https://github.com/Azure/azure-iot-sdk-c). To better understand the responsibilities of the user application code and the Embedded C SDK, please take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md), which explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. -**Note**: this therefore requires a different programming model as compared to the earlier version of the C SDK ([found here](https://github.com/Azure/azure-iot-sdk-c)). To better understand the responsibilities of the user application code and the SDK, please take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. +### Documentation -### Docs - -For API documentation, please see the doxygen generated docs [here][azure_sdk_for_c_doxygen_docs]. You can find the IoT specific docs by navigating to the **Files -> File List** section near the top and choosing any of the header files prefixed with `az_iot_`. +For API documentation, please see the [doxygen generated documents](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/index.html). After following that link, you can find the IoT specific documents by navigating to the **Files -> File List** section near the top and choosing any of the header files prefixed with `az_iot_`. ### Build @@ -49,33 +46,27 @@ The Azure IoT library is compiled following the same steps listed on the root [R The library targets made available via CMake are the following: -- `az::iot::hub` - For Azure IoT Hub features ([API documentation here][azure_sdk_for_c_doxygen_hub_docs]) -- `az::iot::provisioning` - For Azure IoT Provisioning features ([API documentation here][azure_sdk_for_c_doxygen_provisioning_docs]) +- `az::iot::hub` - For Azure IoT Hub features ([API documentation here](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/az__iot__hub__client_8h.html)). +- `az::iot::provisioning` - For Azure IoT Provisioning features ([API documentation here](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/az__iot__provisioning__client_8h.html)). ### Samples -[This page](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) explains samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients and how to use them. +View the [samples README](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) to learn how to run samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients. - For step-by-step guides starting from scratch, you may refer to these documents: + For step-by-step guides to run the IoT Hub certificate samples from scratch, you may refer to these documents: -- Linux: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Linux](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md) +- Linux: [How to Setup and Run Azure SDK for Embedded C IoT Hub Certificate Samples on Linux](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md) -- Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Microsoft Windows](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md). +- Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Certificate Samples on Microsoft Windows](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md) - ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md) - **Important Note on Linux and Windows Samples**: 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, debug and step through the code to learn about it, even without a real device. We understand not everyone will have a real device to test and - sometimes - these devices won't have debugging capabilities. + **Important Note on Linux and Windows Samples**: 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. For extra guidance, please feel free to watch our Deep Dive Video below which goes over building the SDK, running the samples, and the architecture of the samples. [![Watch the video](./resources/deep_dive_screenshot.png)](https://youtu.be/qdb3QIq8msg) -### Prerequisites - -For compiling the Azure SDK for Embedded C for the most common platforms (Windows and Linux), no further prerequisites are necessary. -Please follow the instructions in the [Getting Started](#Getting-Started) section above. -For compiling for specific target devices, please refer to their specific toolchain documentation. - ## Key Features √ feature available √* feature partially available (see Description for details) × feature planned but not supported @@ -93,47 +84,50 @@ Feature | Azure SDK for Embedded C | Description ## Examples +These examples introduce you to the API calls for a few key features of the Embedded C SDK. 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/). + ### IoT Hub Client Initialization -To use IoT Hub connectivity, the first action by a developer should be to initialize the -client with the `az_iot_hub_client_init()` API. Once that is initialized, you may use the -`az_iot_hub_client_get_user_name()` and `az_iot_hub_client_get_client_id()` to get the +To use IoT Hub connectivity, the first action by a developer should be to initialize the client with the `az_iot_hub_client_init()` API. Once that is initialized, you may use the `az_iot_hub_client_get_user_name()` and `az_iot_hub_client_get_client_id()` to get the user name and client id to establish a connection with IoT Hub. An example use case is below. ```C -//FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. +// FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. az_iot_hub_client my_client; static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR("contoso.azure-devices.net"); static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR("contoso_device"); -//Make sure to size the buffer to fit the user name (100 is an example) -static char my_mqtt_user_name[100]; -static size_t my_mqtt_user_name_length; - -//Make sure to size the buffer to fit the client id (16 is an example) -static char my_mqtt_client_id_buffer[16]; +// Make sure to size the buffer to fit the client id (16 is an example) +static char my_mqtt_client_id[16]; static size_t my_mqtt_client_id_length; -int main() +// Make sure to size the buffer to fit the username (128 is an example) +static char my_mqtt_user_name[128]; +static size_t my_mqtt_user_name_length; + +int main(void) { - //Get the default IoT Hub options + // 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 + // Initialize the hub client with hostname, device id, and default connection 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), &my_mqtt_user_name_length); + // Get the MQTT client id used for the MQTT connection. + az_iot_hub_client_get_client_id( + &my_client, my_mqtt_client_id, sizeof(my_mqtt_client_id), &my_mqtt_client_id_length); - //Get the MQTT client id to connect - sizeof(my_mqtt_client_id), &my_mqtt_client_id_length); + // 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), &my_mqtt_user_name_length); - //At this point you are free to use my_mqtt_client_id and my_mqtt_user_name to connect using - //your MQTT client. + // At this point you are free to use my_mqtt_client_id and my_mqtt_user_name to connect using + // your MQTT client. + + return 0; } ``` @@ -145,32 +139,38 @@ Below is an example use case of appending properties. ```C //FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. -void my_property_func() + +void my_property_func(void) { - //Allocate a span to put the properties + // Allocate a span to put the properties. uint8_t property_buffer[64]; - az_span property_span = az_span_create(property_buffer, sizeof(property_buffer)); + az_span property_span = AZ_SPAN_FROM_BUFFER(property_buffer); - //Initialize the property struct with the span + // Initialize the property struct with the span. az_iot_message_properties props; az_iot_message_properties_init(&props, property_span, 0); - //Append properties - az_iot_message_properties_append(&props, AZ_SPAN_FROM_STR("key"), AZ_SPAN_FROM_STR("value")); - //At this point, you are able to pass the `props` to other APIs with property parameters. + + // Append properties. + az_iot_message_properties_append( + &props, AZ_SPAN_LITERAL_FROM_STR("key"), AZ_SPAN_LITERAL_FROM_STR("value")); + + // At this point, you are able to pass the `props` to other APIs with property parameters. } ``` -Below is an example use case of initializing an already populated property span. +Below is an example use case of initializing with an already populated property span. ```C -//FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. -static az_span my_prop_span = AZ_SPAN_LITERAL_FROM_STR("my_device=contoso&my_key=my_value"); -void my_property_func() +// FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. + +static az_span property_span = AZ_SPAN_LITERAL_FROM_STR("my_device=contoso&my_key=my_value"); +void my_property_func(void) { - //Initialize the property struct with the span + // Initialize the property struct with the span. az_iot_message_properties props; - az_iot_message_properties_init(&props, my_prop_span, az_span_size(my_prop_span)); - //At this point, you are able to pass the `props` to other APIs with property parameters. + az_iot_message_properties_init(&props, property_span, az_span_size(property_span)); + + // At this point, you are able to pass the `props` to other APIs with property parameters. } ``` @@ -179,160 +179,37 @@ void my_property_func() Telemetry functionality can be achieved by sending a user payload to a specific topic. In order to get the appropriate topic to which to send, use the `az_iot_hub_client_telemetry_get_publish_topic()` API. An example use case is below. ```C -//FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. +// FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. static az_iot_hub_client my_client; static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR("contoso.azure-devices.net"); static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR("contoso_device"); -void my_telemetry_func() +void my_telemetry_func(void) { - //Initialize the client to then pass to the telemetry API + // Initialize the client to then pass to the telemetry API. az_iot_hub_client_init(&my_client, my_iothub_hostname, my_device_id, NULL); - //Allocate a char buffer with capacity large enough to put the telemetry topic. + // Allocate a char buffer with capacity large enough to put the telemetry topic. char telemetry_topic[64]; size_t telemetry_topic_length; - //Get the NULL terminated topic and put in telemetry_topic to send the telemetry - az_iot_hub_client_telemetry_get_publish_topic(&my_client, NULL, telemetry_topic, - sizeof(telemetry_topic), &telemetry_topic_length); -} -``` - -### 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 -#include -#include - -az_iot_hub_client my_client; -static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR(""); -static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR(""); - -//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() -{ - //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() -{ - //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); + // Get the NULL terminated topic and put in telemetry_topic to send the telemetry. + az_iot_hub_client_telemetry_get_publish_topic( + &my_client, NULL, telemetry_topic, sizeof(telemetry_topic), &telemetry_topic_length); } - -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 - } -} - ``` -## Need Help? +## Troubleshooting +- The error policy for 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). - File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-c/issues/new/choose). -- Check [previous questions](https://stackoverflow.com/questions/tagged/azure+c) or ask new ones on StackOverflow using - the `azure` and `c` tags. +- Check [previous questions](https://stackoverflow.com/questions/tagged/azure+c) or ask new ones on StackOverflow using the `azure` and `c` tags. ## Contributing -If you'd like to contribute to this library, please read the [contributing guide][azure_sdk_for_c_contributing] to learn more about how to build and test the code. +This project welcomes contributions and suggestions. Find more contributing details [here](https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md). ### License -Azure SDK for Embedded C is licensed under the [MIT][azure_sdk_for_c_license] license. - - -[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md -[azure_sdk_for_c_doxygen_docs]: https://azure.github.io/azure-sdk-for-c -[azure_sdk_for_c_doxygen_hub_docs]: https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0-preview.2/az__iot__hub__client_8h.html -[azure_sdk_for_c_doxygen_provisioning_docs]: https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0-preview.2/az__iot__provisioning__client_8h.html -[azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE +Azure SDK for Embedded C is licensed under the [MIT](https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE) license. diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 622b2e3282..630b6e884c 100644 --- a/sdk/samples/iot/README.md +++ b/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) From 83e6fde614ff26f3278d0a7d6c1031c0f882f412 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 29 Sep 2020 22:46:36 -0700 Subject: [PATCH 02/24] how to guides update --- .../iot/docs/how_to_iot_hub_samples_linux.md | 19 +++++++++++++++---- .../docs/how_to_iot_hub_samples_windows.md | 16 +++++++++++++++- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index e2da9052c6..52484997bb 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/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) @@ -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://github.com/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://github.com/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://github.com/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://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#error-policy). diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md index ed8cc40c76..7e74921d1d 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md +++ b/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) @@ -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://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/). +1. From PowerShell, install Microsoft [vcpkg](https://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/). ```powershell PS C:\> git clone https://github.com/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://github.com/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://github.com/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://github.com/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://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#error-policy). From cb615896cec13d772b7caae699e7fc24901f69c0 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 29 Sep 2020 22:08:50 -0700 Subject: [PATCH 03/24] docs iot README update --- sdk/docs/iot/README.md | 265 ++++++++++---------------------------- sdk/samples/iot/README.md | 3 + 2 files changed, 74 insertions(+), 194 deletions(-) diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index e45f8fd6f7..b9f8eff5b0 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -9,17 +9,15 @@ Here you will find everything you need to get devices connected to Azure. - [Azure IoT Clients](#azure-iot-clients) - [Table of Contents](#table-of-contents) - [Getting Started](#getting-started) - - [Docs](#docs) + - [Documentation](#documentation) - [Build](#build) - [Samples](#samples) - - [Prerequisites](#prerequisites) - [Key Features](#key-features) - [Examples](#examples) - [IoT Hub Client Initialization](#iot-hub-client-initialization) - [Properties](#properties) - [Telemetry](#telemetry) - - [IoT Hub Client with MQTT Stack](#iot-hub-client-with-mqtt-stack) - - [Need Help?](#need-help) + - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) - [License](#license) @@ -29,19 +27,18 @@ The Azure IoT Client library is created to facilitate connectivity to Azure IoT ![Methods](./resources/embc_high_level_arch.png) -From a functional perspective, this means that the user's application code (not the SDK) calls directly to the MQTT stack of their choice. The SDK provides utilities (in the form of functions, default values, etc) which help make the connection and feature set easier. Some examples of those utilities include: +From a functional perspective, this means that the user's application code (not the SDK) calls directly to the MQTT stack of their choice. The SDK provides utilities (functions, default values, etc.) that help make the connection and feature set easier to use. Some examples of those utilities include: -- Publish topics to which messages can be sent and subscription topics to which users can subscribe for incoming messages. -- Functions to parse incoming message topics which populate structs with crucial message information. +- Publish topics to which messages can be sent. +- Subscription topics to which users can subscribe for incoming messages. +- Functions to parse incoming message topics, which populate structs with crucial message information. - Default values for MQTT connect keep alive and connection port. -A full list of features can be found in the doxygen docs listed below in [Docs](#docs). +**NOTE**: This Embedded C SDK requires a different programming model as compared to the earlier version of the [C SDK](https://github.com/Azure/azure-iot-sdk-c). To better understand the responsibilities of the user application code and the Embedded C SDK, please take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md), which explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. -**Note**: this therefore requires a different programming model as compared to the earlier version of the C SDK ([found here](https://github.com/Azure/azure-iot-sdk-c)). To better understand the responsibilities of the user application code and the SDK, please take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. +### Documentation -### Docs - -For API documentation, please see the doxygen generated docs [here][azure_sdk_for_c_doxygen_docs]. You can find the IoT specific docs by navigating to the **Files -> File List** section near the top and choosing any of the header files prefixed with `az_iot_`. +For API documentation, please see the [doxygen generated documents](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/index.html). After following that link, you can find the IoT specific documents by navigating to the **Files -> File List** section near the top and choosing any of the header files prefixed with `az_iot_`. ### Build @@ -49,33 +46,27 @@ The Azure IoT library is compiled following the same steps listed on the root [R The library targets made available via CMake are the following: -- `az::iot::hub` - For Azure IoT Hub features ([API documentation here][azure_sdk_for_c_doxygen_hub_docs]) -- `az::iot::provisioning` - For Azure IoT Provisioning features ([API documentation here][azure_sdk_for_c_doxygen_provisioning_docs]) +- `az::iot::hub` - For Azure IoT Hub features ([API documentation here](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/az__iot__hub__client_8h.html)). +- `az::iot::provisioning` - For Azure IoT Provisioning features ([API documentation here](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/az__iot__provisioning__client_8h.html)). ### Samples -[This page](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) explains samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients and how to use them. +View the [samples README](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) to learn how to run samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients. - For step-by-step guides starting from scratch, you may refer to these documents: + For step-by-step guides to run the IoT Hub certificate samples from scratch, you may refer to these documents: -- Linux: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Linux](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md) +- Linux: [How to Setup and Run Azure SDK for Embedded C IoT Hub Certificate Samples on Linux](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md) -- Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Microsoft Windows](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md). +- Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Certificate Samples on Microsoft Windows](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md) - ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md) - **Important Note on Linux and Windows Samples**: 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, debug and step through the code to learn about it, even without a real device. We understand not everyone will have a real device to test and - sometimes - these devices won't have debugging capabilities. + **Important Note on Linux and Windows Samples**: 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. For extra guidance, please feel free to watch our Deep Dive Video below which goes over building the SDK, running the samples, and the architecture of the samples. [![Watch the video](./resources/deep_dive_screenshot.png)](https://youtu.be/qdb3QIq8msg) -### Prerequisites - -For compiling the Azure SDK for Embedded C for the most common platforms (Windows and Linux), no further prerequisites are necessary. -Please follow the instructions in the [Getting Started](#Getting-Started) section above. -For compiling for specific target devices, please refer to their specific toolchain documentation. - ## Key Features √ feature available √* feature partially available (see Description for details) × feature planned but not supported @@ -93,47 +84,50 @@ Feature | Azure SDK for Embedded C | Description ## Examples +These examples introduce you to the API calls for a few key features of the Embedded C SDK. 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/). + ### IoT Hub Client Initialization -To use IoT Hub connectivity, the first action by a developer should be to initialize the -client with the `az_iot_hub_client_init()` API. Once that is initialized, you may use the -`az_iot_hub_client_get_user_name()` and `az_iot_hub_client_get_client_id()` to get the +To use IoT Hub connectivity, the first action by a developer should be to initialize the client with the `az_iot_hub_client_init()` API. Once that is initialized, you may use the `az_iot_hub_client_get_user_name()` and `az_iot_hub_client_get_client_id()` to get the user name and client id to establish a connection with IoT Hub. An example use case is below. ```C -//FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. +// FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. az_iot_hub_client my_client; static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR("contoso.azure-devices.net"); static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR("contoso_device"); -//Make sure to size the buffer to fit the user name (100 is an example) -static char my_mqtt_user_name[100]; -static size_t my_mqtt_user_name_length; - -//Make sure to size the buffer to fit the client id (16 is an example) -static char my_mqtt_client_id_buffer[16]; +// Make sure to size the buffer to fit the client id (16 is an example) +static char my_mqtt_client_id[16]; static size_t my_mqtt_client_id_length; -int main() +// Make sure to size the buffer to fit the username (128 is an example) +static char my_mqtt_user_name[128]; +static size_t my_mqtt_user_name_length; + +int main(void) { - //Get the default IoT Hub options + // 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 + // Initialize the hub client with hostname, device id, and default connection 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), &my_mqtt_user_name_length); + // Get the MQTT client id used for the MQTT connection. + az_iot_hub_client_get_client_id( + &my_client, my_mqtt_client_id, sizeof(my_mqtt_client_id), &my_mqtt_client_id_length); - //Get the MQTT client id to connect - sizeof(my_mqtt_client_id), &my_mqtt_client_id_length); + // 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), &my_mqtt_user_name_length); - //At this point you are free to use my_mqtt_client_id and my_mqtt_user_name to connect using - //your MQTT client. + // At this point you are free to use my_mqtt_client_id and my_mqtt_user_name to connect using + // your MQTT client. + + return 0; } ``` @@ -145,32 +139,38 @@ Below is an example use case of appending properties. ```C //FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. -void my_property_func() + +void my_property_func(void) { - //Allocate a span to put the properties + // Allocate a span to put the properties. uint8_t property_buffer[64]; - az_span property_span = az_span_create(property_buffer, sizeof(property_buffer)); + az_span property_span = AZ_SPAN_FROM_BUFFER(property_buffer); - //Initialize the property struct with the span + // Initialize the property struct with the span. az_iot_message_properties props; az_iot_message_properties_init(&props, property_span, 0); - //Append properties - az_iot_message_properties_append(&props, AZ_SPAN_FROM_STR("key"), AZ_SPAN_FROM_STR("value")); - //At this point, you are able to pass the `props` to other APIs with property parameters. + + // Append properties. + az_iot_message_properties_append( + &props, AZ_SPAN_LITERAL_FROM_STR("key"), AZ_SPAN_LITERAL_FROM_STR("value")); + + // At this point, you are able to pass the `props` to other APIs with property parameters. } ``` -Below is an example use case of initializing an already populated property span. +Below is an example use case of initializing with an already populated property span. ```C -//FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. -static az_span my_prop_span = AZ_SPAN_LITERAL_FROM_STR("my_device=contoso&my_key=my_value"); -void my_property_func() +// FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. + +static az_span property_span = AZ_SPAN_LITERAL_FROM_STR("my_device=contoso&my_key=my_value"); +void my_property_func(void) { - //Initialize the property struct with the span + // Initialize the property struct with the span. az_iot_message_properties props; - az_iot_message_properties_init(&props, my_prop_span, az_span_size(my_prop_span)); - //At this point, you are able to pass the `props` to other APIs with property parameters. + az_iot_message_properties_init(&props, property_span, az_span_size(property_span)); + + // At this point, you are able to pass the `props` to other APIs with property parameters. } ``` @@ -179,160 +179,37 @@ void my_property_func() Telemetry functionality can be achieved by sending a user payload to a specific topic. In order to get the appropriate topic to which to send, use the `az_iot_hub_client_telemetry_get_publish_topic()` API. An example use case is below. ```C -//FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. +// FOR SIMPLICITY THIS DOES NOT HAVE ERROR CHECKING. IN PRODUCTION ENSURE PROPER ERROR CHECKING. static az_iot_hub_client my_client; static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR("contoso.azure-devices.net"); static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR("contoso_device"); -void my_telemetry_func() +void my_telemetry_func(void) { - //Initialize the client to then pass to the telemetry API + // Initialize the client to then pass to the telemetry API. az_iot_hub_client_init(&my_client, my_iothub_hostname, my_device_id, NULL); - //Allocate a char buffer with capacity large enough to put the telemetry topic. + // Allocate a char buffer with capacity large enough to put the telemetry topic. char telemetry_topic[64]; size_t telemetry_topic_length; - //Get the NULL terminated topic and put in telemetry_topic to send the telemetry - az_iot_hub_client_telemetry_get_publish_topic(&my_client, NULL, telemetry_topic, - sizeof(telemetry_topic), &telemetry_topic_length); -} -``` - -### 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 -#include -#include - -az_iot_hub_client my_client; -static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR(""); -static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR(""); - -//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() -{ - //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() -{ - //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); + // Get the NULL terminated topic and put in telemetry_topic to send the telemetry. + az_iot_hub_client_telemetry_get_publish_topic( + &my_client, NULL, telemetry_topic, sizeof(telemetry_topic), &telemetry_topic_length); } - -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 - } -} - ``` -## Need Help? +## Troubleshooting +- The error policy for 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). - File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-c/issues/new/choose). -- Check [previous questions](https://stackoverflow.com/questions/tagged/azure+c) or ask new ones on StackOverflow using - the `azure` and `c` tags. +- Check [previous questions](https://stackoverflow.com/questions/tagged/azure+c) or ask new ones on StackOverflow using the `azure` and `c` tags. ## Contributing -If you'd like to contribute to this library, please read the [contributing guide][azure_sdk_for_c_contributing] to learn more about how to build and test the code. +This project welcomes contributions and suggestions. Find more contributing details [here](https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md). ### License -Azure SDK for Embedded C is licensed under the [MIT][azure_sdk_for_c_license] license. - - -[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md -[azure_sdk_for_c_doxygen_docs]: https://azure.github.io/azure-sdk-for-c -[azure_sdk_for_c_doxygen_hub_docs]: https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0-preview.2/az__iot__hub__client_8h.html -[azure_sdk_for_c_doxygen_provisioning_docs]: https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0-preview.2/az__iot__provisioning__client_8h.html -[azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE +Azure SDK for Embedded C is licensed under the [MIT](https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE) license. diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 622b2e3282..630b6e884c 100644 --- a/sdk/samples/iot/README.md +++ b/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) From 082c5a03934f84d471bf487c7f8a98effa00c113 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 29 Sep 2020 22:46:36 -0700 Subject: [PATCH 04/24] how to guides update --- .../iot/docs/how_to_iot_hub_samples_linux.md | 19 +++++++++++++++---- .../docs/how_to_iot_hub_samples_windows.md | 16 +++++++++++++++- 2 files changed, 30 insertions(+), 5 deletions(-) diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index e2da9052c6..52484997bb 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/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) @@ -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://github.com/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://github.com/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://github.com/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://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#error-policy). diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md index ed8cc40c76..7e74921d1d 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md +++ b/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) @@ -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://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/). +1. From PowerShell, install Microsoft [vcpkg](https://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/). ```powershell PS C:\> git clone https://github.com/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://github.com/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://github.com/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://github.com/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://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#error-policy). From 3696d0f7d06653028e791f3297533b230941a2b5 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Wed, 30 Sep 2020 17:10:46 -0700 Subject: [PATCH 05/24] remove hub and provisioning mds. Add pseudo_code md. update readmes --- sdk/docs/iot/README.md | 44 +++--- sdk/docs/iot/hub.md | 26 ---- sdk/docs/iot/provisioning.md | 29 ---- sdk/docs/iot/pseudo_code_examples.md | 127 ++++++++++++++++++ sdk/samples/iot/README.md | 2 +- .../iot/docs/how_to_iot_hub_samples_linux.md | 2 +- .../docs/how_to_iot_hub_samples_windows.md | 2 +- 7 files changed, 150 insertions(+), 82 deletions(-) delete mode 100644 sdk/docs/iot/hub.md delete mode 100644 sdk/docs/iot/provisioning.md create mode 100644 sdk/docs/iot/pseudo_code_examples.md diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index b9f8eff5b0..43dd2ed8ec 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -1,26 +1,9 @@ -# Azure IoT Clients +# Azure Embedded C SDK IoT Clients This is the main page for the Azure SDK for Embedded C official IoT client libraries. Here you will find everything you need to get devices connected to Azure. -## Table of Contents - -- [Azure IoT Clients](#azure-iot-clients) - - [Table of Contents](#table-of-contents) - - [Getting Started](#getting-started) - - [Documentation](#documentation) - - [Build](#build) - - [Samples](#samples) - - [Key Features](#key-features) - - [Examples](#examples) - - [IoT Hub Client Initialization](#iot-hub-client-initialization) - - [Properties](#properties) - - [Telemetry](#telemetry) - - [Troubleshooting](#troubleshooting) - - [Contributing](#contributing) - - [License](#license) - ## Getting Started The Azure IoT Client library is created to facilitate connectivity to Azure IoT services alongside an MQTT and TLS stack of the user's choice. This means that this SDK is **NOT** a platform but instead is a true SDK library. @@ -34,7 +17,12 @@ From a functional perspective, this means that the user's application code (not - Functions to parse incoming message topics, which populate structs with crucial message information. - Default values for MQTT connect keep alive and connection port. -**NOTE**: This Embedded C SDK requires a different programming model as compared to the earlier version of the [C SDK](https://github.com/Azure/azure-iot-sdk-c). To better understand the responsibilities of the user application code and the Embedded C SDK, please take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md), which explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. +To better understand the responsibilities of the user application code and the Embedded C SDK, please take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md), which explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. + +For more details about the Azure IoT Hub, see the following [Azure IoT Hub documentation](https://docs.microsoft.com/azure/iot-hub/). +For more details about the Azure IoT Device Provisioning Service (DPS), see the [Azure IOT DPS documentation](https://docs.microsoft.com/azure/iot-dps/). + +**NOTE**: This Embedded C SDK requires a different programming model as compared to the earlier version of the [C SDK](https://github.com/Azure/azure-iot-sdk-c). ### Documentation @@ -42,7 +30,7 @@ For API documentation, please see the [doxygen generated documents](https://azur ### Build -The Azure IoT library is compiled following the same steps listed on the root [README](https://github.com/Azure/azure-sdk-for-c/blob/master/README.md) documentation, under ["Getting Started Using the SDK"](https://github.com/Azure/azure-sdk-for-c/blob/master/README.md#getting-started-using-the-sdk). +The Azure IoT library is compiled following the same steps listed on the root [Azure SDK for Embedded C README](https://github.com/Azure/azure-sdk-for-c/blob/master/README.md) documentation, under ["Getting Started Using the SDK"](https://github.com/Azure/azure-sdk-for-c/blob/master/README.md#getting-started-using-the-sdk). The library targets made available via CMake are the following: @@ -51,9 +39,9 @@ The library targets made available via CMake are the following: ### Samples -View the [samples README](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) to learn how to run samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients. +View the [Azure Embedded C SDK IoT Samples README](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) to learn how to run samples for the Azure Embedded C SDK IoT Hub Client and the Provisioning Clients. The README will provide general prerequisites, environment setup instructions, sample descriptions, as well as directions on how to build and run all the samples on either a Linux or Windows environment. - For step-by-step guides to run the IoT Hub certificate samples from scratch, you may refer to these documents: +For more detailed, step-by-step guides to setup and run the IoT Hub certificate samples from scratch, refer to these documents: - Linux: [How to Setup and Run Azure SDK for Embedded C IoT Hub Certificate Samples on Linux](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md) @@ -61,7 +49,7 @@ View the [samples README](https://github.com/Azure/azure-sdk-for-c/blob/master/s - ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md) - **Important Note on Linux and Windows Samples**: 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. +**Important Note on Linux and Windows Samples**: 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. For extra guidance, please feel free to watch our Deep Dive Video below which goes over building the SDK, running the samples, and the architecture of the samples. @@ -84,7 +72,15 @@ Feature | Azure SDK for Embedded C | Description ## Examples -These examples introduce you to the API calls for a few key features of the Embedded C SDK. 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/). +These examples introduce you to the API calls for a few key features of the Embedded C SDK. + +- [IoT Hub Client Initialization](#iot-hub-client-initialization) +- [Properties](#properties) +- [Telemetry](#telemetry) + +Additional pseudo code examples can be found [here](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/pseudo_code_examples.md). The pseudo code examples are MQTT stack agnostic and can give you a general overview of the API calls and structure needed to use the Azure IoT Embedded C SDK features. + +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. ### IoT Hub Client Initialization diff --git a/sdk/docs/iot/hub.md b/sdk/docs/iot/hub.md deleted file mode 100644 index 83a7aef274..0000000000 --- a/sdk/docs/iot/hub.md +++ /dev/null @@ -1,26 +0,0 @@ -# Azure IoT Hub Client - -Official Embedded C client for Azure IoT Hub. - -## Getting Started - -- **Docs**: If you're new to the Azure SDK for Embedded C take a look at the [State Machine diagram](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#iot-hub) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities. -- **Samples**: [This page](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/) explains samples for the Azure SDK for Embedded C and how to use them. - -## Need Help? - -- File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-c/issues/new/choose). -- Check [previous questions](https://stackoverflow.com/questions/tagged/azure+c) or ask new ones on StackOverflow using - the `azure` and `c` tags. - -## Contributing - -If you'd like to contribute to this library, please read the [contributing guide][azure_sdk_for_c_contributing] to learn more about how to build and test the code. - -### License - -Azure SDK for Embedded C is licensed under the [MIT][azure_sdk_for_c_license] license. - - -[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md -[azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE diff --git a/sdk/docs/iot/provisioning.md b/sdk/docs/iot/provisioning.md deleted file mode 100644 index 93578c0a0c..0000000000 --- a/sdk/docs/iot/provisioning.md +++ /dev/null @@ -1,29 +0,0 @@ -# Azure IoT Device Provisioning Client - -Official Embedded C client for Azure IoT Provisioning Service. - -For more details about Provisioning Service check [Azure documentation](https://docs.microsoft.com/azure/iot-dps/) - -## Getting Started - -- Please refer to the state machine diagram which describes the Azure SDK for Embedded C flow for Provisioning Service [here](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md#device-provisioning-service). - -- **Samples**: [This page](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/README.md) explains samples for the Azure SDK for Embedded C IoT Provisioning Client and how to use them. - -## Need Help? - -- File an issue via [Github Issues](https://github.com/Azure/azure-sdk-for-c/issues/new/choose). -- Check [previous questions](https://stackoverflow.com/questions/tagged/azure+c) or ask new ones on StackOverflow using - the `azure` and `c` tags. - -## Contributing - -If you'd like to contribute to this library, please read the [contributing guide][azure_sdk_for_c_contributing] to learn more about how to build and test the code. - -### License - -Azure SDK for Embedded C is licensed under the [MIT][azure_sdk_for_c_license] license. - - -[azure_sdk_for_c_contributing]: https://github.com/Azure/azure-sdk-for-c/blob/master/CONTRIBUTING.md -[azure_sdk_for_c_license]: https://github.com/Azure/azure-sdk-for-c/blob/master/LICENSE diff --git a/sdk/docs/iot/pseudo_code_examples.md b/sdk/docs/iot/pseudo_code_examples.md new file mode 100644 index 0000000000..360d27ad37 --- /dev/null +++ b/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 +#include +#include + +az_iot_hub_client my_client; +static az_span my_iothub_hostname = AZ_SPAN_LITERAL_FROM_STR(""); +static az_span my_device_id = AZ_SPAN_LITERAL_FROM_STR(""); + +//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 + } +} + +``` diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 630b6e884c..19d3ca9e1d 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -36,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 develoeprs 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.** diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index 52484997bb..c0fc049c58 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md @@ -23,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://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. -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. diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md index 7e74921d1d..2e249bfec8 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md @@ -23,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://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**. -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. From fba1ee4f837717ec5e3af4e663fef11ed5b191a6 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Wed, 30 Sep 2020 17:19:49 -0700 Subject: [PATCH 06/24] typo fix --- sdk/samples/iot/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 19d3ca9e1d..68de4a0e4a 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -36,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 develoeprs 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.** From 87e5c1b33901453dac19a1f58112a8395fc40e1c Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Thu, 1 Oct 2020 04:26:57 -0700 Subject: [PATCH 07/24] Update CMake instructions --- sdk/samples/iot/README.md | 33 ++++++++----------- .../iot/docs/how_to_iot_hub_samples_linux.md | 24 ++++++++++---- 2 files changed, 31 insertions(+), 26 deletions(-) diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 68de4a0e4a..d7391ea7fb 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -69,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): @@ -132,21 +131,27 @@ To run the samples, ensure you have the following programs and tools installed o

-- 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.
Instructions:

- Linux: + Linux (Ubuntu 20.04): ```bash - sudo apt-get purge cmake - sudo tar -xvzf cmake-.tar.gz - cd cmake- - ./bootstrap && make && sudo make install + sudo apt-get install cmake ``` - Windows (PowerShell): + Linux (Ubuntu 16.04 or 18.04): Download the latest version of [CMake](https://cmake.org/files). + + ```bash + wget https://cmake.org/files/v/cmake--Linux-x86_64.sh + sudo ./cmake--Linux-x86_64.sh --prefix=/usr/local + ``` + + - 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. @@ -759,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: diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index c0fc049c58..269a393026 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md @@ -71,18 +71,28 @@ To run the samples, ensure you have the following programs and tools installed o NOTE: Please keep in mind, **every time a new terminal is opened, the environment variables will have to be reset**. -3. Install the latest version of [CMake](https://cmake.org/download). In this sample, it is `cmake-3.18.2.tar.gz`. This installation may also take an extended amount of time (~20-30 minutes). +3. Install [CMake](https://cmake.org/files). - Move the downloaded tar file to the root directory. Then run the following commands: + For Ubuntu 20.04, run the following command: + + ``` + sudo apt-get instal cmake + ``` + + For Ubuntu 16.04 or 18.04, run the following commands: + + NOTE: This guide is based on Ubuntu 18.04 and uses `cmake-3.18.3-Linux-x86_64.sh`. ```bash - /$ sudo apt-get purge cmake - /$ sudo tar -xvzf cmake-3.18.2.tar.gz # Use latest version - /$ cd cmake-3.18.2 - /cmake-3.18.2$ sudo ./bootstrap && sudo make && sudo make install - /cmake-3.18.2$ cd .. + /$ sudo wget https://cmake.org/files/v3.18/cmake-3.18.3-Linux-x86_64.sh # Use latest version. + /$ sudo chmod 777 cmake-3.18.3-Linux-x86_64.sh # Update permissions since the script was cloned into the root directory. + /$ sudo ./cmake-3.18.3-Linux-x86_64.sh --prefix=/usr/local ``` + - When prompted to include the default subdirectory, enter `n` so to install in `/usr/local`. + + + 4. Clone the Azure SDK for Embedded C IoT repository. ```bash From f8ad6a4b1c562f9a80947be5c52d1c6b3fa07008 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Thu, 1 Oct 2020 04:41:05 -0700 Subject: [PATCH 08/24] typo fix --- sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index 269a393026..eb8770658f 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md @@ -76,7 +76,7 @@ To run the samples, ensure you have the following programs and tools installed o For Ubuntu 20.04, run the following command: ``` - sudo apt-get instal cmake + sudo apt-get install cmake ``` For Ubuntu 16.04 or 18.04, run the following commands: From 08ed710a5909377bc03463444c1b27916e5f6c67 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Thu, 1 Oct 2020 12:45:56 -0700 Subject: [PATCH 09/24] Fix CMake instructions --- sdk/samples/iot/README.md | 8 +-- .../iot/docs/how_to_iot_hub_samples_linux.md | 63 +++++++++---------- 2 files changed, 33 insertions(+), 38 deletions(-) diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index d7391ea7fb..2d13cdad72 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -80,7 +80,7 @@ To run the samples, ensure you have the following programs and tools installed o

- 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).
Instructions:

@@ -136,17 +136,17 @@ To run the samples, ensure you have the following programs and tools installed o

Instructions:

- Linux (Ubuntu 20.04): + Linux (Ubuntu 18.04 or 20.04): ```bash sudo apt-get install cmake ``` - Linux (Ubuntu 16.04 or 18.04): Download the latest version of [CMake](https://cmake.org/files). + Linux (Ubuntu 16.04): Download the latest version of [CMake](https://cmake.org/files). ```bash wget https://cmake.org/files/v/cmake--Linux-x86_64.sh - sudo ./cmake--Linux-x86_64.sh --prefix=/usr/local + sudo ./cmake--Linux-x86_64.sh --prefix=/usr ``` - When prompted to include the default subdirectory, enter `n` so to install in `/usr/local`. diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index eb8770658f..ffedca267f 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md @@ -51,53 +51,48 @@ To run the samples, ensure you have the following programs and tools installed o ## Setup Instructions -1. Install Microsoft [vcpkg](https://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/). This installation may take an extended amount of time (~20-30 minutes). +1. Install Microsoft [vcpkg](https://github.com/microsoft/vcpkg) package manager and [Eclipse Paho MQTT C client](https://www.eclipse.org/paho/). This installation may take an extended amount of time (~15-20 minutes). ```bash - cd / # Run this command from any directory to go to the root. - /$ sudo git clone https://github.com/Microsoft/vcpkg.git - /$ cd vcpkg - /vcpkg$ sudo ./bootstrap-vcpkg.sh - /vcpkg$ sudo ./vcpkg install --triplet x64-linux curl cmocka paho-mqtt - /vcpkg$ cd .. + cd ~ # Run this command from any directory to go to your user home directory. + ~$ sudo git clone https://github.com/Microsoft/vcpkg.git + ~$ cd vcpkg + ~/vcpkg$ sudo ./bootstrap-vcpkg.sh + ~/vcpkg$ sudo ./vcpkg install --triplet x64-linux curl cmocka paho-mqtt + ~/vcpkg$ cd .. ``` 2. Set the vcpkg environment variables. ```bash - /$ export VCPKG_DEFAULT_TRIPLET=x64-linux - /$ export VCPKG_ROOT=/vcpkg + ~$ export VCPKG_DEFAULT_TRIPLET=x64-linux + ~$ export VCPKG_ROOT=~/vcpkg ``` NOTE: Please keep in mind, **every time a new terminal is opened, the environment variables will have to be reset**. 3. Install [CMake](https://cmake.org/files). - For Ubuntu 20.04, run the following command: + For Ubuntu 18.04 or 20.04, run the following command: ``` sudo apt-get install cmake ``` - For Ubuntu 16.04 or 18.04, run the following commands: - - NOTE: This guide is based on Ubuntu 18.04 and uses `cmake-3.18.3-Linux-x86_64.sh`. + For Ubuntu 16.04, run the following commands: ```bash - /$ sudo wget https://cmake.org/files/v3.18/cmake-3.18.3-Linux-x86_64.sh # Use latest version. - /$ sudo chmod 777 cmake-3.18.3-Linux-x86_64.sh # Update permissions since the script was cloned into the root directory. - /$ sudo ./cmake-3.18.3-Linux-x86_64.sh --prefix=/usr/local + ~$ wget https://cmake.org/files/v3.18/cmake-3.18.3-Linux-x86_64.sh # Use latest version. + ~$ sudo chmod 777 cmake-3.18.3-Linux-x86_64.sh # Update permissions to execute script. + ~$ sudo ./cmake-3.18.3-Linux-x86_64.sh --prefix=/usr ``` - When prompted to include the default subdirectory, enter `n` so to install in `/usr/local`. - - 4. Clone the Azure SDK for Embedded C IoT repository. ```bash - /$ sudo git clone https://github.com/Azure/azure-sdk-for-c.git - /$ sudo chmod -R 777 azure-sdk-for-c/ # Update permissions since the repo was cloned into the root directory. + ~$ git clone https://github.com/Azure/azure-sdk-for-c.git ``` ## Configure and Run the Samples @@ -113,11 +108,11 @@ To run the samples, ensure you have the following programs and tools installed o Run the following commands: ```bash - /$ cd azure-sdk-for-c/sdk/samples/iot/ + ~$ cd azure-sdk-for-c/sdk/samples/iot/ - /azure-sdk-for-c/sdk/samples/iot$ openssl ecparam -out device_ec_key.pem -name prime256v1 -genkey - /azure-sdk-for-c/sdk/samples/iot$ 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" - /azure-sdk-for-c/sdk/samples/iot$ openssl x509 -noout -text -in device_ec_cert.pem + ~/azure-sdk-for-c/sdk/samples/iot$ openssl ecparam -out device_ec_key.pem -name prime256v1 -genkey + ~/azure-sdk-for-c/sdk/samples/iot$ 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" + ~/azure-sdk-for-c/sdk/samples/iot$ openssl x509 -noout -text -in device_ec_cert.pem ```

The output will look similar to: @@ -159,9 +154,9 @@ To run the samples, ensure you have the following programs and tools installed o Run the following commands: ```bash - /azure-sdk-for-c/sdk/samples/iot$ rm -f device_cert_store.pem - /azure-sdk-for-c/sdk/samples/iot$ cat device_ec_cert.pem device_ec_key.pem > device_cert_store.pem - /azure-sdk-for-c/sdk/samples/iot$ openssl x509 -noout -fingerprint -in device_ec_cert.pem | sed 's/://g'| sed 's/\(SHA1 Fingerprint=\)//g' | tee fingerprint.txt + ~/azure-sdk-for-c/sdk/samples/iot$ rm -f device_cert_store.pem + ~/azure-sdk-for-c/sdk/samples/iot$ cat device_ec_cert.pem device_ec_key.pem > device_cert_store.pem + ~/azure-sdk-for-c/sdk/samples/iot$ openssl x509 -noout -fingerprint -in device_ec_cert.pem | sed 's/://g'| sed 's/\(SHA1 Fingerprint=\)//g' | tee fingerprint.txt ```
The output will be the fingerprint and will look similar to: @@ -179,7 +174,7 @@ To run the samples, ensure you have the following programs and tools installed o Complete by setting the cert pem file path environment variable: ```bash - /azure-sdk-for-c/sdk/samples/iot$ export AZ_IOT_DEVICE_X509_CERT_PEM_FILE_PATH=$(pwd)/device_cert_store.pem + ~/azure-sdk-for-c/sdk/samples/iot$ export AZ_IOT_DEVICE_X509_CERT_PEM_FILE_PATH=$(pwd)/device_cert_store.pem ``` 2. Create a logical device. @@ -207,17 +202,17 @@ To run the samples, ensure you have the following programs and tools installed o 4. Build the Azure SDK for Embedded C directory structure. ```bash - /azure-sdk-for-c/sdk/samples/iot$ cd ../../.. - /azure-sdk-for-c$ mkdir build - /azure-sdk-for-c$ cd build - /azure-sdk-for-c/build$ cmake -DTRANSPORT_PAHO=ON .. + ~/azure-sdk-for-c/sdk/samples/iot$ cd ../../.. + ~/azure-sdk-for-c$ mkdir build + ~/azure-sdk-for-c$ cd build + ~/azure-sdk-for-c/build$ cmake -DTRANSPORT_PAHO=ON .. ``` 5. Compile and run your sample of choice from within the `build` directory. ```bash - /azure-sdk-for-c/build$ cmake --build . - /azure-sdk-for-c/build$ ./sdk/samples/iot/paho_iot_hub_telemetry_sample # Use the executable of your choice. + ~/azure-sdk-for-c/build$ cmake --build . + ~/azure-sdk-for-c/build$ ./sdk/samples/iot/paho_iot_hub_telemetry_sample # Use the executable of your choice. ``` ## Sample Instructions From 5177c11b68b7e0b886c4a8b402e041fcdcbb2391 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Fri, 2 Oct 2020 12:28:02 -0700 Subject: [PATCH 10/24] Updates per comments --- sdk/docs/iot/README.md | 24 +++++++++---------- ...do_code_examples.md => coding_patterns.md} | 7 +++--- sdk/samples/iot/README.md | 10 ++++---- .../iot/docs/how_to_iot_hub_samples_linux.md | 4 ++-- 4 files changed, 24 insertions(+), 21 deletions(-) rename sdk/docs/iot/{pseudo_code_examples.md => coding_patterns.md} (93%) diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index b5835d0ab4..ae02c551c0 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -1,4 +1,4 @@ -# Azure Embedded C SDK IoT Clients +# Azure IoT Clients This is the main page for the Azure SDK for Embedded C official IoT client libraries. @@ -26,7 +26,7 @@ For more details about the Azure IoT Device Provisioning Service (DPS), see the ### Documentation -For API documentation, please see the [doxygen generated documents](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/index.html). After following that link, you can find the IoT specific documents by navigating to the **Files -> File List** section near the top and choosing any of the header files prefixed with `az_iot_`. +Please view the API documentation [here](https://azuresdkdocs.blob.core.windows.net/$web/c/docs/1.0.0/index.html). After following that link, you can find the IoT specific documents by navigating to the **Files -> File List** section near the top and choosing any of the header files prefixed with `az_iot_`. ### Build @@ -73,17 +73,17 @@ Feature | Azure SDK for Embedded C | Description ## Examples -These examples introduce you to the API calls for a few key features of the Embedded C SDK. +These examples are scenario-focused and introduce you to the API calls for a few key features of the Embedded C SDK. -- [IoT Hub Client Initialization](#iot-hub-client-initialization) -- [Properties](#properties) -- [Telemetry](#telemetry) + - [Azure IoT Hub Client Initialization](#azure-iot-hub-client-initialization) + - [Azure IoT Message Properties](#azure-iot-message-properties) + - [Azure IoT Telemetry](#azure-iot-telemetry) -Additional pseudo code examples can be found [here](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/pseudo_code_examples.md). The pseudo code examples are MQTT stack agnostic and can give you a general overview of the API calls and structure needed to use the Azure IoT Embedded C SDK features. +General [coding patterns](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/pseudo_code_examples.md) that are MQTT stack agnostic are also available to view. These patterns can give you an overview of the API calls and structure needed to use the Azure IoT Embedded C SDK features. 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. -### IoT Hub Client Initialization +### Azure IoT Hub Client Initialization To use IoT Hub connectivity, the first action by a developer should be to initialize the client with the `az_iot_hub_client_init()` API. Once that is initialized, you may use the `az_iot_hub_client_get_user_name()` and `az_iot_hub_client_get_client_id()` to get the user name and client id to establish a connection with IoT Hub. @@ -128,9 +128,9 @@ int main(void) } ``` -### Properties +### Azure IoT Message Properties -Included in the Azure SDK for Embedded C are helper functions to form and manage properties for IoT Hub services. Implementation starts by using the `az_iot_message_properties_init()` API. The user is free to initialize using an empty, but appropriately sized, span to later append properties or an already populated span containing a properly formatted property buffer. "Properly formatted" properties follow the form `{key}={value}&{key}={value}`. +Included in the Azure SDK for Embedded C are helper functions to form and manage message properties for Azure IoT Hub services. Implementation starts by using the `az_iot_message_properties_init()` API. The user is free to initialize using an empty, but appropriately sized, span to later append properties or an already populated span containing a properly formatted property buffer. "Properly formatted" properties follow the form `{key}={value}&{key}={value}`. Below is an example use case of appending properties. @@ -151,7 +151,7 @@ void my_property_func(void) az_iot_message_properties_append( &props, AZ_SPAN_LITERAL_FROM_STR("key"), AZ_SPAN_LITERAL_FROM_STR("value")); - // At this point, you are able to pass the `props` to other APIs with property parameters. + // At this point, you are able to pass the `props` to other APIs with message property parameters. } ``` @@ -171,7 +171,7 @@ void my_property_func(void) } ``` -### Telemetry +### Azure IoT Telemetry Telemetry functionality can be achieved by sending a user payload to a specific topic. In order to get the appropriate topic to which to send, use the `az_iot_hub_client_telemetry_get_publish_topic()` API. An example use case is below. diff --git a/sdk/docs/iot/pseudo_code_examples.md b/sdk/docs/iot/coding_patterns.md similarity index 93% rename from sdk/docs/iot/pseudo_code_examples.md rename to sdk/docs/iot/coding_patterns.md index 360d27ad37..f2ea45093f 100644 --- a/sdk/docs/iot/pseudo_code_examples.md +++ b/sdk/docs/iot/coding_patterns.md @@ -1,13 +1,14 @@ -# Azure Embedded C SDK IoT Client Pseudo Code Examples +# Azure IoT Client Coding Patterns ## 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. +This page introduces you to coding patterns 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. +To view scenario-focused examples using the API calls, 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 diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 2d13cdad72..13a18e4bff 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -1,8 +1,8 @@ -# Azure Embedded C SDK IoT Samples +# Azure IoT Samples ## Table of Contents -- [Azure Embedded C SDK IoT Samples](#azure-embedded-c-sdk-iot-samples) +- [Azure IoT Samples](#azure-iot-samples) - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Prerequisites](#prerequisites) @@ -46,6 +46,8 @@ More detailed step-by-step guides on how to run an IoT Hub Client sample from sc - Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Certificate Samples on Microsoft Windows](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md) - ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md) +To view scenario-focused examples using the API calls, please view the Azure IoT Client [introductory examples](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/README.md#examples). General [coding patterns](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/pseudo_code_examples.md) that are MQTT stack agnostic are also available to view. + ## Prerequisites To run the samples, ensure you have the following programs and tools installed on your system: @@ -145,8 +147,8 @@ To run the samples, ensure you have the following programs and tools installed o Linux (Ubuntu 16.04): Download the latest version of [CMake](https://cmake.org/files). ```bash - wget https://cmake.org/files/v/cmake--Linux-x86_64.sh - sudo ./cmake--Linux-x86_64.sh --prefix=/usr + wget https://cmake.org/files/v3.18/cmake-3.18.3-Linux-x86_64.sh # Use latest version. + sudo ./cmake-3.18.3-Linux-x86_64.sh --prefix=/usr ``` - When prompted to include the default subdirectory, enter `n` so to install in `/usr/local`. diff --git a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md index ffedca267f..e75e041e98 100644 --- a/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md +++ b/sdk/samples/iot/docs/how_to_iot_hub_samples_linux.md @@ -101,7 +101,7 @@ To run the samples, ensure you have the following programs and tools installed o For the certificate samples, x509 authentication is used to connect to Azure IoT Hub. - **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. + **WARNING: Certificates created by these commands MUST NOT be used in production-level code on Windows or macOS.** These certificates expire after one day 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. The resulting thumbprint will be placed in `fingerprint.txt` and the generated pem file is named `device_ec_cert.pem`. @@ -111,7 +111,7 @@ To run the samples, ensure you have the following programs and tools installed o ~$ cd azure-sdk-for-c/sdk/samples/iot/ ~/azure-sdk-for-c/sdk/samples/iot$ openssl ecparam -out device_ec_key.pem -name prime256v1 -genkey - ~/azure-sdk-for-c/sdk/samples/iot$ 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" + ~/azure-sdk-for-c/sdk/samples/iot$ openssl req -new -days 1 -nodes -x509 -key device_ec_key.pem -out device_ec_cert.pem -config x509_config.cfg -subj "/CN=paho-sample-device1" ~/azure-sdk-for-c/sdk/samples/iot$ openssl x509 -noout -text -in device_ec_cert.pem ``` From 113cbc6e7a03616ba65479a42648264b203c2ecb Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Fri, 2 Oct 2020 12:29:57 -0700 Subject: [PATCH 11/24] naming update --- sdk/docs/iot/coding_patterns.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/docs/iot/coding_patterns.md b/sdk/docs/iot/coding_patterns.md index f2ea45093f..43f8b999ba 100644 --- a/sdk/docs/iot/coding_patterns.md +++ b/sdk/docs/iot/coding_patterns.md @@ -11,7 +11,7 @@ For a more extensive demonstration of the API, please view and run the [sample c ## Examples -### IoT Hub Client with MQTT Stack +### Azure 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. From 6e7f3fb4fb434de6f1956ab4a20ad47fc6ef7bb5 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Fri, 2 Oct 2020 14:34:42 -0700 Subject: [PATCH 12/24] update naming --- sdk/docs/iot/README.md | 12 ++++++------ sdk/docs/iot/coding_patterns.md | 2 +- 2 files changed, 7 insertions(+), 7 deletions(-) diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index 599059b964..883cdd0d23 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -75,15 +75,15 @@ Feature | Azure SDK for Embedded C | Description These examples are scenario-focused and introduce you to the API calls for a few key features of the Embedded C SDK. - - [Azure IoT Hub Client Initialization](#azure-iot-hub-client-initialization) - - [Azure IoT Message Properties](#azure-iot-message-properties) - - [Azure IoT Telemetry](#azure-iot-telemetry) + - [IoT Hub Client Initialization](#iot-hub-client-initialization) + - [IoT Message Properties](#iot-message-properties) + - [IoT Telemetry](#iot-telemetry) General [coding patterns](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/pseudo_code_examples.md) that are MQTT stack agnostic are also available to view. These patterns can give you an overview of the API calls and structure needed to use the Azure IoT Embedded C SDK features. 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. -### Azure IoT Hub Client Initialization +### IoT Hub Client Initialization To use IoT Hub connectivity, the first action by a developer should be to initialize the client with the `az_iot_hub_client_init()` API. Once that is initialized, you may use the `az_iot_hub_client_get_user_name()` and `az_iot_hub_client_get_client_id()` to get the user name and client id to establish a connection with IoT Hub. @@ -128,7 +128,7 @@ int main(void) } ``` -### Azure IoT Message Properties +### IoT Message Properties Included in the Azure SDK for Embedded C are helper functions to form and manage message properties for Azure IoT Hub services. Implementation starts by using the `az_iot_message_properties_init()` API. The user is free to initialize using an empty, but appropriately sized, span to later append properties or an already populated span containing a properly formatted property buffer. "Properly formatted" properties follow the form `{key}={value}&{key}={value}`. @@ -171,7 +171,7 @@ void my_property_func(void) } ``` -### Azure IoT Telemetry +### IoT Telemetry Telemetry functionality can be achieved by sending a user payload to a specific topic. In order to get the appropriate topic to which to send, use the `az_iot_hub_client_telemetry_get_publish_topic()` API. An example use case is below. diff --git a/sdk/docs/iot/coding_patterns.md b/sdk/docs/iot/coding_patterns.md index 43f8b999ba..f2ea45093f 100644 --- a/sdk/docs/iot/coding_patterns.md +++ b/sdk/docs/iot/coding_patterns.md @@ -11,7 +11,7 @@ For a more extensive demonstration of the API, please view and run the [sample c ## Examples -### Azure IoT Hub Client with MQTT Stack +### 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. From 427abf66375656a201e6ef1ad1637a1f9e92a7a1 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 6 Oct 2020 10:34:09 -0700 Subject: [PATCH 13/24] fix link --- sdk/docs/iot/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index 883cdd0d23..8939feb339 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -79,7 +79,7 @@ These examples are scenario-focused and introduce you to the API calls for a few - [IoT Message Properties](#iot-message-properties) - [IoT Telemetry](#iot-telemetry) -General [coding patterns](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/pseudo_code_examples.md) that are MQTT stack agnostic are also available to view. These patterns can give you an overview of the API calls and structure needed to use the Azure IoT Embedded C SDK features. +General [coding patterns](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/coding_patterns.md) that are MQTT stack agnostic are also available to view. These patterns can give you an overview of the API calls and structure needed to use the Azure IoT Embedded C SDK features. 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. From dc89eef64bbd65c5d94006481f4855138c556c6c Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 6 Oct 2020 11:26:49 -0700 Subject: [PATCH 14/24] fix link --- sdk/samples/iot/README.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 13a18e4bff..61eb61b2b7 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -46,7 +46,7 @@ More detailed step-by-step guides on how to run an IoT Hub Client sample from sc - Windows: [How to Setup and Run Azure SDK for Embedded C IoT Hub Certificate Samples on Microsoft Windows](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_samples_windows.md) - ESP8266: [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/samples/iot/docs/how_to_iot_hub_esp8266_nodemcu.md) -To view scenario-focused examples using the API calls, please view the Azure IoT Client [introductory examples](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/README.md#examples). General [coding patterns](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/pseudo_code_examples.md) that are MQTT stack agnostic are also available to view. +To view scenario-focused examples using the API calls, please view the Azure IoT Client [introductory examples](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/README.md#examples). General [coding patterns](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/coding_patterns.md) that are MQTT stack agnostic are also available to view. ## Prerequisites From 0a964171ccc6c94553806c67b146ef84cdd94684 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 6 Oct 2020 15:48:02 -0700 Subject: [PATCH 15/24] commit to kick of fresh testing --- sdk/samples/iot/pnp/pnp_protocol.c | 1 + 1 file changed, 1 insertion(+) diff --git a/sdk/samples/iot/pnp/pnp_protocol.c b/sdk/samples/iot/pnp/pnp_protocol.c index 7336cc528d..4ac91573a1 100644 --- a/sdk/samples/iot/pnp/pnp_protocol.c +++ b/sdk/samples/iot/pnp/pnp_protocol.c @@ -5,6 +5,7 @@ #include +# #include #include #include From 1de8c179b7c26bd8ce906b442574336eb41fd0f3 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 6 Oct 2020 15:48:19 -0700 Subject: [PATCH 16/24] revert change --- sdk/samples/iot/pnp/pnp_protocol.c | 1 - 1 file changed, 1 deletion(-) diff --git a/sdk/samples/iot/pnp/pnp_protocol.c b/sdk/samples/iot/pnp/pnp_protocol.c index 4ac91573a1..7336cc528d 100644 --- a/sdk/samples/iot/pnp/pnp_protocol.c +++ b/sdk/samples/iot/pnp/pnp_protocol.c @@ -5,7 +5,6 @@ #include -# #include #include #include From 12e4150854167c16c5112e9f22876705bb41dd97 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 6 Oct 2020 22:36:02 -0700 Subject: [PATCH 17/24] build fix attempt --- eng/pipelines/templates/steps/cmake-build.yml | 4 ++++ 1 file changed, 4 insertions(+) diff --git a/eng/pipelines/templates/steps/cmake-build.yml b/eng/pipelines/templates/steps/cmake-build.yml index 8090aec324..347ed557bd 100644 --- a/eng/pipelines/templates/steps/cmake-build.yml +++ b/eng/pipelines/templates/steps/cmake-build.yml @@ -10,6 +10,10 @@ steps: workingDirectory: build displayName: cmake --version + - script: vcpkg list + workingDirectory: build + displayName: vcpkg list + - script: cmake ${{ parameters.BuildArgs }} .. -DCMAKE_BUILD_TYPE=${{ parameters.BuildType }} workingDirectory: build displayName: cmake generate From 57fb6983e439bb8972c79d51a712d03280528b59 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 6 Oct 2020 22:48:54 -0700 Subject: [PATCH 18/24] build fix attempt --- eng/pipelines/templates/steps/vcpkg.yml | 32 ++++++++++++------------- 1 file changed, 16 insertions(+), 16 deletions(-) diff --git a/eng/pipelines/templates/steps/vcpkg.yml b/eng/pipelines/templates/steps/vcpkg.yml index 7e35ad37f7..1c01bae688 100644 --- a/eng/pipelines/templates/steps/vcpkg.yml +++ b/eng/pipelines/templates/steps/vcpkg.yml @@ -24,22 +24,22 @@ steps: not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')) ) - - task: Cache@2 - inputs: - key: >- - $(Agent.JobName) - | "$(VcpkgCommit)" - | $(Agent.Os) - | $(${{ parameters.DependenciesVariableName }}) - path: $(VCPKG_INSTALLATION_ROOT) - cacheHitVar: VcpkgRestoredFromCache - displayName: Vcpkg Cache - condition: >- - and( - succeeded(), - not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')), - not(eq(variables['Skip.VcpkgCache'], 'true')) - ) +# - task: Cache@2 +# inputs: +# key: >- +# $(Agent.JobName) +# | "$(VcpkgCommit)" +# | $(Agent.Os) +# | $(${{ parameters.DependenciesVariableName }}) +# path: $(VCPKG_INSTALLATION_ROOT) +# cacheHitVar: VcpkgRestoredFromCache +# displayName: Vcpkg Cache +# condition: >- +# and( +# succeeded(), +# not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')), +# not(eq(variables['Skip.VcpkgCache'], 'true')) +# ) - task: PowerShell@2 inputs: From 5a086646be2447172f0ef049663db7f6e6654d2c Mon Sep 17 00:00:00 2001 From: Ahson Ahmed Khan Date: Tue, 6 Oct 2020 23:26:27 -0700 Subject: [PATCH 19/24] Disable vcpkg caching to use the correct triplet. --- eng/pipelines/templates/steps/vcpkg.yml | 17 ----------------- 1 file changed, 17 deletions(-) diff --git a/eng/pipelines/templates/steps/vcpkg.yml b/eng/pipelines/templates/steps/vcpkg.yml index 7e35ad37f7..09e182c9b4 100644 --- a/eng/pipelines/templates/steps/vcpkg.yml +++ b/eng/pipelines/templates/steps/vcpkg.yml @@ -24,23 +24,6 @@ steps: not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')) ) - - task: Cache@2 - inputs: - key: >- - $(Agent.JobName) - | "$(VcpkgCommit)" - | $(Agent.Os) - | $(${{ parameters.DependenciesVariableName }}) - path: $(VCPKG_INSTALLATION_ROOT) - cacheHitVar: VcpkgRestoredFromCache - displayName: Vcpkg Cache - condition: >- - and( - succeeded(), - not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')), - not(eq(variables['Skip.VcpkgCache'], 'true')) - ) - - task: PowerShell@2 inputs: targetType: filePath From c6c40681300047fadd0333ca69055b6e8898d3ef Mon Sep 17 00:00:00 2001 From: Ahson Ahmed Khan Date: Tue, 6 Oct 2020 23:43:23 -0700 Subject: [PATCH 20/24] Revert "Disable vcpkg caching to use the correct triplet." This reverts commit 5a086646be2447172f0ef049663db7f6e6654d2c. --- eng/pipelines/templates/steps/vcpkg.yml | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/eng/pipelines/templates/steps/vcpkg.yml b/eng/pipelines/templates/steps/vcpkg.yml index 09e182c9b4..7e35ad37f7 100644 --- a/eng/pipelines/templates/steps/vcpkg.yml +++ b/eng/pipelines/templates/steps/vcpkg.yml @@ -24,6 +24,23 @@ steps: not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')) ) + - task: Cache@2 + inputs: + key: >- + $(Agent.JobName) + | "$(VcpkgCommit)" + | $(Agent.Os) + | $(${{ parameters.DependenciesVariableName }}) + path: $(VCPKG_INSTALLATION_ROOT) + cacheHitVar: VcpkgRestoredFromCache + displayName: Vcpkg Cache + condition: >- + and( + succeeded(), + not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')), + not(eq(variables['Skip.VcpkgCache'], 'true')) + ) + - task: PowerShell@2 inputs: targetType: filePath From de644528dd9b6e663b9e1e544df61313bf25b95b Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Tue, 6 Oct 2020 23:55:25 -0700 Subject: [PATCH 21/24] revert vcpkg and cmake-build changes to clear cache --- eng/pipelines/templates/steps/cmake-build.yml | 4 ---- eng/pipelines/templates/steps/vcpkg.yml | 17 +++++++++++++++++ 2 files changed, 17 insertions(+), 4 deletions(-) diff --git a/eng/pipelines/templates/steps/cmake-build.yml b/eng/pipelines/templates/steps/cmake-build.yml index 347ed557bd..8090aec324 100644 --- a/eng/pipelines/templates/steps/cmake-build.yml +++ b/eng/pipelines/templates/steps/cmake-build.yml @@ -10,10 +10,6 @@ steps: workingDirectory: build displayName: cmake --version - - script: vcpkg list - workingDirectory: build - displayName: vcpkg list - - script: cmake ${{ parameters.BuildArgs }} .. -DCMAKE_BUILD_TYPE=${{ parameters.BuildType }} workingDirectory: build displayName: cmake generate diff --git a/eng/pipelines/templates/steps/vcpkg.yml b/eng/pipelines/templates/steps/vcpkg.yml index 09e182c9b4..7e35ad37f7 100644 --- a/eng/pipelines/templates/steps/vcpkg.yml +++ b/eng/pipelines/templates/steps/vcpkg.yml @@ -24,6 +24,23 @@ steps: not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')) ) + - task: Cache@2 + inputs: + key: >- + $(Agent.JobName) + | "$(VcpkgCommit)" + | $(Agent.Os) + | $(${{ parameters.DependenciesVariableName }}) + path: $(VCPKG_INSTALLATION_ROOT) + cacheHitVar: VcpkgRestoredFromCache + displayName: Vcpkg Cache + condition: >- + and( + succeeded(), + not(eq(variables['${{ parameters.DependenciesVariableName }}'], '')), + not(eq(variables['Skip.VcpkgCache'], 'true')) + ) + - task: PowerShell@2 inputs: targetType: filePath From cfa4294cb8b7799d7f2866ea208072db074a298d Mon Sep 17 00:00:00 2001 From: Ahson Ahmed Khan Date: Tue, 6 Oct 2020 23:55:29 -0700 Subject: [PATCH 22/24] Adding the triplet as part of the restore key. --- eng/pipelines/templates/steps/vcpkg.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/eng/pipelines/templates/steps/vcpkg.yml b/eng/pipelines/templates/steps/vcpkg.yml index 7e35ad37f7..048be8cabe 100644 --- a/eng/pipelines/templates/steps/vcpkg.yml +++ b/eng/pipelines/templates/steps/vcpkg.yml @@ -31,6 +31,7 @@ steps: | "$(VcpkgCommit)" | $(Agent.Os) | $(${{ parameters.DependenciesVariableName }}) + | $(VCPKG_DEFAULT_TRIPLET) path: $(VCPKG_INSTALLATION_ROOT) cacheHitVar: VcpkgRestoredFromCache displayName: Vcpkg Cache From bcfe16b783cd73aaf091e652fba4f509fe5d5e70 Mon Sep 17 00:00:00 2001 From: Ahson Ahmed Khan Date: Wed, 7 Oct 2020 00:03:07 -0700 Subject: [PATCH 23/24] Adding back the triplet as part of the restore key. --- eng/pipelines/templates/steps/vcpkg.yml | 1 + 1 file changed, 1 insertion(+) diff --git a/eng/pipelines/templates/steps/vcpkg.yml b/eng/pipelines/templates/steps/vcpkg.yml index 7e35ad37f7..048be8cabe 100644 --- a/eng/pipelines/templates/steps/vcpkg.yml +++ b/eng/pipelines/templates/steps/vcpkg.yml @@ -31,6 +31,7 @@ steps: | "$(VcpkgCommit)" | $(Agent.Os) | $(${{ parameters.DependenciesVariableName }}) + | $(VCPKG_DEFAULT_TRIPLET) path: $(VCPKG_INSTALLATION_ROOT) cacheHitVar: VcpkgRestoredFromCache displayName: Vcpkg Cache From d44be0677235b3079b14df6eb943e995daf1d898 Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Wed, 7 Oct 2020 00:52:32 -0700 Subject: [PATCH 24/24] Comment updates --- sdk/docs/iot/coding_patterns.md | 1 - sdk/samples/iot/README.md | 2 +- 2 files changed, 1 insertion(+), 2 deletions(-) diff --git a/sdk/docs/iot/coding_patterns.md b/sdk/docs/iot/coding_patterns.md index f2ea45093f..f3e997ddcc 100644 --- a/sdk/docs/iot/coding_patterns.md +++ b/sdk/docs/iot/coding_patterns.md @@ -8,7 +8,6 @@ To view scenario-focused examples using the API calls, please view the [introduc 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 diff --git a/sdk/samples/iot/README.md b/sdk/samples/iot/README.md index 61eb61b2b7..d988aa3ea1 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -133,7 +133,7 @@ To run the samples, ensure you have the following programs and tools installed o

-- Have CMake installed. +- Have CMake installed. The minimum required is 3.10.
Instructions: