From 8f604dde2415e27120d81a7a88d6c28378d5b89f Mon Sep 17 00:00:00 2001 From: Mollie Munoz Date: Wed, 7 Oct 2020 01:26:12 -0700 Subject: [PATCH] Update documentation from JS comments (#1381) --- eng/pipelines/templates/steps/vcpkg.yml | 1 + sdk/docs/iot/README.md | 299 +++++------------- sdk/docs/iot/coding_patterns.md | 127 ++++++++ sdk/docs/iot/hub.md | 26 -- sdk/docs/iot/provisioning.md | 29 -- sdk/samples/iot/README.md | 46 +-- .../iot/docs/how_to_iot_hub_samples_linux.md | 92 +++--- .../docs/how_to_iot_hub_samples_windows.md | 18 +- 8 files changed, 307 insertions(+), 331 deletions(-) create mode 100644 sdk/docs/iot/coding_patterns.md delete mode 100644 sdk/docs/iot/hub.md delete mode 100644 sdk/docs/iot/provisioning.md 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 diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md index d26625d274..8939feb339 100644 --- a/sdk/docs/iot/README.md +++ b/sdk/docs/iot/README.md @@ -4,79 +4,58 @@ This is the main page for the Azure SDK for Embedded C official IoT client libra 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) - - [Docs](#docs) - - [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) - - [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. ![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). +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 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. +**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). -### Docs +### Documentation -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_`. +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 -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: -- `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::pnp` - **[BETA]** For Azure IoT Plug and Play features ([feature branch here](https://github.com/Azure/azure-sdk-for-c/tree/feature/iot_pnp)) +- `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)). +- `az::iot::pnp` - **[BETA]** For Azure IoT Plug and Play features ([feature branch here](https://github.com/Azure/azure-sdk-for-c/tree/feature/iot_pnp)). ### 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 [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 starting 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 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 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. [![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 @@ -94,246 +73,140 @@ Feature | Azure SDK for Embedded C | Description ## Examples +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) + - [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/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. + ### 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; } ``` -### Properties +### 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. ```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 message 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. } ``` -### 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. ```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); + // 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 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); -} - -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/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/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/docs/iot/coding_patterns.md b/sdk/docs/iot/coding_patterns.md new file mode 100644 index 0000000000..f3e997ddcc --- /dev/null +++ b/sdk/docs/iot/coding_patterns.md @@ -0,0 +1,127 @@ +# Azure IoT Client Coding Patterns + +## Introduction + +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. + +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 + +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/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/samples/iot/README.md b/sdk/samples/iot/README.md index 622b2e3282..d988aa3ea1 100644 --- a/sdk/samples/iot/README.md +++ b/sdk/samples/iot/README.md @@ -1,6 +1,9 @@ -# Azure Embedded C SDK IoT Samples +# Azure IoT Samples -- [Azure Embedded C SDK IoT Samples](#azure-embedded-c-sdk-iot-samples) +## Table of Contents + +- [Azure IoT Samples](#azure-iot-samples) + - [Table of Contents](#table-of-contents) - [Introduction](#introduction) - [Prerequisites](#prerequisites) - [Sample Descriptions](#sample-descriptions) @@ -33,7 +36,7 @@ This document explains samples for the Azure Embedded C SDK IoT Hub Client and D Samples are designed to highlight the function calls required to connect with the Azure IoT Hub or the Azure IoT Hub Device Provisioning Service (DPS). These calls illustrate the happy path of the [mqtt state machine](https://github.com/Azure/azure-sdk-for-c/blob/master/sdk/docs/iot/mqtt_state_machine.md). As a result, **these samples are NOT designed to be used as production-level code**. Production code needs to incorporate other elements, such as connection retries and more extensive error-handling, which these samples do not include. These samples also utilize OpenSSL, which is **NOT recommended to use in production-level code on Windows or macOS**. -The samples' instructions include specifics for both Windows and Linux based systems. For Windows, the command line examples are based on PowerShell. The Linux examples are tailored to Debian/Ubuntu environments. Samples are also designed to work on macOS systems, but the instructions do not yet include specific command line examples for this environment. While Windows and Linux devices are not likely to be considered constrained, these samples enable one to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities. +The samples' instructions include specifics for both Windows and Linux based systems. For Windows, the command line examples are based on PowerShell. The Linux examples are tailored to Debian/Ubuntu environments. Samples are also designed to work on macOS systems, but the instructions do not yet include specific command line examples for this environment. While Windows and Linux devices are not likely to be considered constrained, these samples enable developers to test the Azure SDK for Embedded C libraries, debug, and step through the code, even without a real device. We understand not everyone will have a real device to test and that sometimes these devices won't have debugging capabilities. **WARNING: Samples are generic and should not be used in any production-level code.** @@ -43,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/coding_patterns.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: @@ -66,8 +71,7 @@ To run the samples, ensure you have the following programs and tools installed o ```bash sudo apt-get update - sudo apt-get install build-essential # make and gcc - sudo apt-get install curl unzip tar pkg-config + sudo apt-get install build-essential curl unzip tar pkg-config ``` Windows (PowerShell): @@ -78,7 +82,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:

@@ -129,21 +133,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. The minimum required is 3.10.
Instructions:

- Linux: + Linux (Ubuntu 18.04 or 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): Download the latest version of [CMake](https://cmake.org/files). + + ```bash + 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`. + + Windows (PowerShell): Download the latest version of [CMake](https://cmake.org/download). - Use the Windows installer. @@ -756,22 +766,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 e2da9052c6..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 @@ -11,6 +11,8 @@ - [IoT Hub Methods Sample](#iot-hub-methods-sample) - [IoT Hub Telemetry Sample](#iot-hub-telemetry-sample) - [IoT Hub Twin Sample](#iot-hub-twin-sample) + - [IoT Hub Plug and Play Sample](#iot-hub-plug-and-play-sample) + - [IoT Hub Plug and Play Multiple Component Sample](#iot-hub-plug-and-play-multiple-component-sample) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) - [License](#license) @@ -21,7 +23,7 @@ This is a step-by-step guide of how to start from scratch and get the Azure SDK Samples are designed to highlight the function calls required to connect with the Azure IoT Hub. These calls illustrate the happy path of the [mqtt state machine](https://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. @@ -44,51 +46,53 @@ 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 -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 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 18.04 or 20.04, run the following command: + + ``` + sudo apt-get install cmake + ``` + + For Ubuntu 16.04, run the following commands: ```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 .. + ~$ 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 @@ -97,18 +101,18 @@ 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`. 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 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 ```

The output will look similar to: @@ -150,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: @@ -170,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. @@ -198,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 @@ -237,6 +241,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..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 @@ -11,6 +11,8 @@ - [IoT Hub Methods Sample](#iot-hub-methods-sample) - [IoT Hub Telemetry Sample](#iot-hub-telemetry-sample) - [IoT Hub Twin Sample](#iot-hub-twin-sample) + - [IoT Hub Plug and Play Sample](#iot-hub-plug-and-play-sample) + - [IoT Hub Plug and Play Multiple Component Sample](#iot-hub-plug-and-play-multiple-component-sample) - [Troubleshooting](#troubleshooting) - [Contributing](#contributing) - [License](#license) @@ -21,7 +23,7 @@ This is a step-by-step guide of how to start from scratch and get the Azure SDK Samples are designed to highlight the function calls required to connect with the Azure IoT Hub. These calls illustrate the happy path of the [mqtt state machine](https://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. @@ -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).