Samples reorganization and readme adjusts (Azure#851)

* Samples reorganization and readme adjusts * Update README.md Co-authored-by: danewalton <[email protected]> * Update README.md Co-authored-by: danewalton <[email protected]> * Update sdk/docs/iot/README.md Co-authored-by: danewalton <[email protected]> * Update sdk/docs/iot/README.md Co-authored-by: danewalton <[email protected]> * Update sdk/samples/iot/hub/linux/how_to_iot_hub_samples_linux.md Co-authored-by: danewalton <[email protected]> * Update sdk/samples/iot/readme.md Co-authored-by: danewalton <[email protected]> Co-authored-by: Wellington Duraes <[email protected]> Co-authored-by: danewalton <[email protected]>
sima-zhu · Jun 23, 2020 · 2d589c9 · 2d589c9
1 parent 2f1e51d
commit 2d589c9
Show file tree

Hide file tree

Showing 9 changed files with 179 additions and 42 deletions.
diff --git a/README.md b/README.md
@@ -4,7 +4,7 @@
 
 The Azure SDK for Embedded C is designed to allow small embedded (IoT) devices to communicate with Azure services. Since we expect our client library code to run on microcontrollers, which have very limited amounts of flash and RAM, and have slower CPUs, our C SDK does things very differently than the SDKs we offer for other languages.
 
-With this in mind, there are many tenants or principles that we follow in order to properly address this target audience:
+With this in mind, there are many tenets or principles that we follow in order to properly address this target audience:
 
 - Customers of our SDK compile our source code along with their own.
 
@@ -23,6 +23,7 @@ With this in mind, there are many tenants or principles that we follow in order
   - [Table of Contents](#table-of-contents)
   - [Documentation](#documentation)
   - [The GitHub Repository](#the-github-repository)
+    - [Services](#service)
     - [Structure](#structure)
     - [Master Branch](#master-branch)
     - [Release Branches and Release Tagging](#release-branches-and-release-tagging)
@@ -56,18 +57,27 @@ To get help with the SDK:
 - File a [Github Issue](https://github.com/Azure/azure-sdk-for-c/issues/new/choose).
 - Ask new questions or see others' questions on [Stack Overflow](https://stackoverflow.com/questions/tagged/azure+c) using the `azure` and `c` tags.
 
+### Services
+
+The Azure SDK for Embedded C repo has been structured around the service libraries it provides:
+
+
+1. [IoT](sdk/docs/iot) - Library to connect Embedded Devices to Azure IoT services
+2. [Storage](sdk/docs/storage) - Library to send blob files to Azure IoT services
+
+
 ### Structure
 
-The repo is structured with two priorities:
+This repo is structured with two priorities:
 1. Separation of services/features to make it easier to find relevant information and resources.
 2. Simplified source file structuring to easily integrate features into a user's project.
 
-`/sdk` (folder containing docs, sources, samples, tests for all SDK packages)<br>
-&nbsp;&nbsp;&nbsp;&nbsp;`/docs` (documentation for each service (iot, storage, etc))<br>
-&nbsp;&nbsp;&nbsp;&nbsp;`/inc` (include directory - can be singularly included in your project to resolve all headers)<br>
-&nbsp;&nbsp;&nbsp;&nbsp;`/samples` (samples for each service)<br>
-&nbsp;&nbsp;&nbsp;&nbsp;`/src` (source files for each service)<br>
-&nbsp;&nbsp;&nbsp;&nbsp;`/tests` (tests for each service)<br>
+`/sdk` - folder containing docs, sources, samples, tests for all SDK packages<br>
+&nbsp;&nbsp;&nbsp;&nbsp;`/docs` - documentation for each service (iot, storage, etc)<br>
+&nbsp;&nbsp;&nbsp;&nbsp;`/inc` - include directory - can be singularly included in your project to resolve all headers<br>
+&nbsp;&nbsp;&nbsp;&nbsp;`/samples` - samples for each service<br>
+&nbsp;&nbsp;&nbsp;&nbsp;`/src` - source files for each service<br>
+&nbsp;&nbsp;&nbsp;&nbsp;`/tests` - tests for each service<br>
 
 For instructions on how to consume the libraries via CMake, please see [here](#cmake). For instructions on how consume the source code in an IDE, command line, or other build systems, please see [here](#source-files-ide-command-line-etc).
 
@@ -81,6 +91,9 @@ When we make an official release, we will create a unique git tag containing the
 
    `<package-name>_<package-version>`
 
+ The latest release can be found in the [release section](https://github.com/Azure/azure-sdk-for-c/releases) of this repo. 
+
+
  For more information, please see this [branching strategy](https://github.com/Azure/azure-sdk/blob/master/docs/policies/repobranching.md#release-tagging) document.
 
 ## Getting Started Using the SDK
@@ -99,7 +112,7 @@ The SDK can be conveniently consumed either via CMake or other non-CMake methods
 
         git checkout <tag_name>
 
-    For information about using a specific client library, see the README file located in the client library's folder which is a subdirectory under the [`/sdk`](sdk) folder.
+    For information about using a specific client library, see the README file located in the client library's folder which is a subdirectory under the [`/sdk/docs`](sdk/docs) folder.
 
 3. Ensure the SDK builds correctly.
 

diff --git a/sdk/docs/iot/README.md b/sdk/docs/iot/README.md
@@ -6,14 +6,16 @@ Azure SDK for Embedded C official IoT client libraries.
 
 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:
 - 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.
 - 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 therefore requires a different programming model as compared to the earlier version of the 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 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](mqtt_state_machine.md) that explains the high-level architecture, SDK components, and a clear view of SDK x Application responsibilities.
 
 ### 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_`.
@@ -26,12 +28,16 @@ The library targets made available via CMake are the following:
 - `az::iot::provisioning`: For Azure IoT Provisioning features ([API documentation here][azure_sdk_for_c_doxygen_provisioning_docs])
 
 ### Samples
-[This page](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/samples/iot/hub#getting-started) explains samples for the Azure Embedded C SDK IoT Hub Client and [this page](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/samples/iot/provisioning#getting-started) shows the Provisioning Clients and how to use them.
+[This page](https://github.com/Azure/azure-sdk-for-c/tree/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.
+
+ For step-by-step guides starting 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/tree/master/sdk/samples/iot/hub/linux/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/tree/master/sdk/samples/iot/hub/windows/how_to_iot_hub_samples_windows.md).
 
-  For step-by-step guides starting from scratch, you may refer to these documents:
-  - [How to setup and run Azure SDK for Embedded C IoT Hub Samples on Linux](how_to_iot_hub_samples_linux.md)
-  - [How to setup and run Azure SDK for Embedded C IoT Hub Samples on Microsoft Windows](how_to_iot_hub_samples_windows.md).
-  - [How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Esp8266 NodeMCU](how_to_esp8266_nodemcu.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/tree/master/sdk/samples/iot/hub/esp8266nodemcu/how_to_esp8266_nodemcu.md)
+
+  **Note**: While Windows and Linux devices are not likely to be considered as contrained ones, these samples were created to make it simpler to test the Azure SDK for Embedded C libraries, even without a real device. 
 
 ### Prerequisites
 
@@ -184,4 +190,3 @@ Azure SDK for Embedded C is licensed under the [MIT][azure_sdk_for_c_license] li
 [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
-
diff --git a/sdk/docs/iot/resources/embc_high_level_arch.png b/sdk/docs/iot/resources/embc_high_level_arch.png
diff --git a/sdk/samples/iot/hub/README.md b/sdk/samples/iot/hub/README.md
@@ -9,9 +9,17 @@ products:
 urlFragment: iot-hub-samples
 ---
 
-# Azure IoT Hub Sample
+# Azure IoT Hub Samples
+
+This document explains samples for the Azure SDK for Embedded C IoT Hub Client and how to use them. 
+
+For step-by-step guides starting 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/tree/master/sdk/samples/iot/hub/linux/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/tree/master/sdk/samples/iot/hub/windows/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/tree/master/sdk/samples/iot/hub/esp8266nodemcu/how_to_esp8266_nodemcu.md)
+
+  **Note**: While Windows and Linux devices are not likely to be considered as contrained ones, these samples were created to make it simpler to test the Azure SDK for Embedded C libraries, even without a real device. 
 
-This document explains samples for the Azure SDK for Embedded C IoT Hub Client and how to use them.
 
 ## Key Concepts
 

diff --git a/sdk/docs/iot/how_to_esp8266_nodemcu.md → .../esp8266nodemcu/how_to_esp8266_nodemcu.md b/sdk/docs/iot/how_to_esp8266_nodemcu.md → .../esp8266nodemcu/how_to_esp8266_nodemcu.md
@@ -1,7 +1,5 @@
 # How to Setup and Run Azure SDK for Embedded C IoT Hub Client on Espressif ESP8266 NodeMCU
 
-_Last edited on June 10th, 2020._
-
 This is a to-the-point documentation of how to run an Azure SDK for Embedded C IoT Hub Telemetry Samples on an Esp8266 NodeMCU microcontroller. 
 
 Pre-requisites:
@@ -237,3 +235,23 @@ _The following was run on an Ubuntu Desktop 18.04 environment, with Arduino IDE
     ^CStopping event monitor...
     ```
     </details>
+
+
+
+## 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.
+
+<!-- LINKS -->
+[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/how_to_iot_hub_samples_linux.md → ...hub/linux/how_to_iot_hub_samples_linux.md b/sdk/docs/iot/how_to_iot_hub_samples_linux.md → ...hub/linux/how_to_iot_hub_samples_linux.md
@@ -1,7 +1,5 @@
 # How to Setup and Run Azure SDK for Embedded C IoT Hub Samples on Linux
 
-_Last edited on June 15th, 2020._
-
 This is a step-by-step guide of how to start from scratch and get the Azure SDK for Embedded C IoT Hub Samples running. 
 
 Pre-requisites:
@@ -12,7 +10,7 @@ What is covered:
 - Downloading and building the Azure SDK for Embedded C suite
 - Configuring and running the IoT Hub client samples.  
 
-_The following was run on an Ubuntu Desktop 18.04 environment._
+_The following was run on an Ubuntu Desktop 18.04 environment, but it also works on WSL 1 and 2 (Windows Subsystem for Linux)_
 
 01. Install library dependencies
 
@@ -273,12 +271,12 @@ _The following was run on an Ubuntu Desktop 18.04 environment._
     - Go to your Azure IoT hub page.
     - Click on "IoT devices" under "Explorers".
     - From the list of devices, click on your device (created on step 8).
-      ![Device page](./resources/embc_samples_01_device.png)
+      ![Device page](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot/resources/embc_samples_01_device.png)
     - Click on "Message to Device".
     - On "Message Body", type "Hello world!" (too cheesy? how about "Lorem Ipsum"?)
-      ![Send message](./resources/embc_samples_02_c2d.png)
+      ![Send message](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot/resources/embc_samples_02_c2d.png)
     - Click on "Send Message".
-      ![Success](./resources/embc_samples_03_c2d_success.png)
+      ![Success](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot/resources/embc_samples_03_c2d_success.png)
 
     Back to the shell, verify that the message has been received by the sample:
 
@@ -322,12 +320,12 @@ _The following was run on an Ubuntu Desktop 18.04 environment._
     - Click on "IoT devices" under "Explorers".
     - From the list of devices, click on your device (created on step Z).
     - Click on "Direct Method".
-      ![Methods](./resources/embc_samples_04_methods.png)
+      ![Methods](https://github.com/Azure/azure-sdk-for-c/tree/master/sdk/docs/iot/resources/embc_samples_04_methods.png)
     - On "Method Name", type "ping" (the sample expects the name "ping").
     - On "Payload", type '{ "somevalue": 1234 }' (the payload can be empty, but MUST be a valid Json).
     - Click on "Invoke Method".
     - See the reply from the sample on "Result" (bottom of the page).
-      ![Response](./resources/embc_samples_05_methods_response.png)
+      ![Response](../../../../docs/iot/resources/embc_samples_05_methods_response.png)
 
 
     Back to the shell, verify that the message has been received by the sample:
@@ -397,7 +395,17 @@ _The following was run on an Ubuntu Desktop 18.04 environment._
     /azure-sdk-for-c/cmake/sdk/samples/iot/hub/$
     ```
 
-# License
+## 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.
 

diff --git a/sdk/samples/iot/hub/src/generate_certificate.cmd b/sdk/samples/iot/hub/src/generate_certificate.cmd
@@ -0,0 +1,50 @@
+@REM Copyright (c) Microsoft Corporation. All rights reserved.
+@REM SPDX-License-Identifier MIT
+
+@echo off
+
+openssl ecparam -out device_ec_key.pem -name prime256v1 -genkey
+IF %ERRORLEVEL% NEQ 0 ( 
+	echo Failed generating certificate key
+	exit b 1
+)
+
+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
+IF %ERRORLEVEL% NEQ 0 ( 
+	echo Failed generating certificate
+	exit b 1
+)
+
+openssl x509 -noout -text -in device_ec_cert.pem
+
+type device_ec_cert.pem  device_cert_store.pem
+type device_ec_key.pem  device_cert_store.pem
+
+echo.
+echo It is NOT recommended to use OpenSSL on Windows or OSX. Recommended TLS stacks are
+echo Microsoft Windows SChannel httpsdocs.microsoft.comen-uswindowswin32comschannel
+echo OR
+echo Apple Secure Transport  httpsdeveloper.apple.comdocumentationsecuritysecure_transport
+echo If using OpenSSL, it is recommended to use the OpenSSL Trusted CA store configured on your system.
+echo.
+echo If required (for example on Windows), download the Baltimore PEM CA from httpswww.digicert.comdigicert-root-certificates.htm to the current folder.
+echo Once it is downloaded, run the following command to set the environment variable for the samples
+echo.
+echo    set AZ_IOT_DEVICE_X509_TRUST_PEM_FILE=%CD%BaltimoreCyberTrustRoot.crt.pem
+echo.
+echo Sample certificate generated
+echo Use the following command to set the environment variable for the samples
+echo.
+echo    set AZ_IOT_DEVICE_X509_CERT_PEM_FILE=%CD%device_cert_store.pem
+echo.
+echo Use the following fingerprint when creating your device in IoT Hub
+
+FOR F tokens= %%a in ('openssl x509 -noout -fingerprint -in device_ec_cert.pem') do SET output=%%a
+set fingerprint=%output=%
+
+echo %fingerprint%
+
+echo %fingerprint%  fingerprint.txt
+
+echo.
+echo The fingerprint has also been placed in fingerprint.txt for future reference