Merge pull request #919 from Azure/public-preview-update

Public preview update for release 2019-03-18

.github/ISSUE_TEMPLATE/bug-report.md

@@ -0,0 +1,81 @@
+---
+name: Bug Report
+about: Create a bug report to help us improve
+title: ''
+labels: 
+assignees: ''
+
+---
+
+------------------------------- delete below -------------------------------
+
+INSTRUCTIONS
+==========
+
+Please follow the instructions and template below to save us time requesting additional information from you.
+
+1. Search existing issues to avoid creating duplicates.
+
+2. If possible test using the latest release to make sure your issues has not already been fixed: 
+https://github.com/Azure/azure-iot-sdk-c/releases/latest 
+
+3. Do not share information from your Azure subscription here (connection strings, service names (IoT Hub name, Device Provisioning Service scope ID), etc...). If you need to share any of this information, you can create a ticket and get assistance from the Microsoft Support.
+
+How to Submit an Azure Support Ticket: https://docs.microsoft.com/en-us/azure/azure-supportability/how-to-create-azure-support-request
+
+
+4. Include enough information for us to address the bug:
+
+   -  A detailed description.
+   -  A Minimal Complete Reproducible Example (https://stackoverflow.com/help/mcve). This is code we can cut and paste into a readily available sample and run, or a link to a project you've written that we can compile to reproduce the bug. 
+   -  Console logs. If you are unsure how to enable logging, refer to this document: https://github.com/Azure/azure-iot-sdk-c/blob/master/doc/Iothub_sdk_options.md
+
+5. Delete these instructions before submitting the bug.
+
+
+
+Below is a hypothetical bug report. We recommend you use it as a template and replace the information below each header with your own. 
+
+------------------------------- delete above -------------------------------
+
+
+**Development Machine, OS, Compiler (and Other Relevant Toolchain Info)**
+
+Raspberry Pi, Raspbian Stretch Lite (Release 2018-11-13)
+Cross Compiled on Ubuntu 18.04 using GCC 6.3.0
+
+**SDK Version (Please Give Commit SHA if Manually Compiling)**
+
+Release 2019-01-31
+
+**Protocol**
+
+MQTT
+
+**Describe the Bug**
+
+If MQTT is unable to establish a connection, it will keep trying and once it succeeds queued messages will be sent to the Cloud. However, if for some reason we can't get past the initial connection phase, then SDK does not respect message timeouts. 
+
+**[MCVE](https://stackoverflow.com/help/mcve)**
+
+```
+#include "iothub.h"
+
+int main(void)
+{
+    if (lightbulb == ON) {
+        iothub_say_hello();
+        return 0;
+    } else {
+        iothub_say_goodbye();
+        return 1;
+    }
+}
+```
+
+**Console Logs**
+
+Sending message 1 to IoTHub
+-> 15:07:42 PUBLISH | IS_DUP: false | RETAIN: 0 | QOS: DELIVER_AT_LEAST_ONCE | TOPIC_NAME: devices/tracingDevice/messages/events/property_key=property_value | PACKET_ID: 93 | PAYLOAD_LEN: 12
+<- 15:07:42 PUBACK | PACKET_ID: 92
+Confirmation callback received for message 86 with result IOTHUB_CLIENT_CONFIRMATION_OK

.github/ISSUE_TEMPLATE/feature-request.md

@@ -0,0 +1,33 @@
+---
+name: Feature Request
+about: Suggest an idea for this project
+title: ''
+labels: enhancement
+assignees: ''
+
+---
+
+------------------------------- delete below -------------------------------
+
+Thank you for submitting a feature request. A few things:
+
+- Please check that a similar feature request has not already been submitted. Adding support to a currently existing feature request by commenting will increase the visibility and importance of your request beyond submitting a duplicate request. 
+
+- If this is a large feature request (i.e. if it requires changes across multiple language SDKs), please submit it to user voice.
+https://feedback.azure.com/forums/321918-azure-iot
+
+As an open source project, we welcome PRs for new features, and we don't want to reject any hard work you've done to contribute. **So propose your solution through an issue first** so we can discuss the changes, and if things look good we will ask you submit a PR to implement the changes.
+
+------------------------------- delete above -------------------------------
+
+**Is your feature request related to a problem? Please describe.**
+A clear and concise description of what the problem is. Ex. I'm always frustrated when [...]
+
+**Describe the solution you'd like**
+A clear and concise description of what you want to happen.
+
+**Describe alternatives you've considered**
+A clear and concise description of any alternative solutions or features you've considered.
+
+**Additional context**
+Add any other context or screenshots about the feature request here.

.github/ISSUE_TEMPLATE/technical-question.md

@@ -0,0 +1,20 @@
+---
+name: Technical Question
+about: Ask a technical question related to the SDK
+title: ''
+labels: question
+assignees: ''
+
+---
+
+------------------------------- delete below -------------------------------
+
+Thank you for asking a technical question! If your question is "why doesn't my code work?", please submit a Bug issue instead.
+
+We also encourage users to submit technical questions related to the SDK on Stack Overflow. 
+
+For Stack Overflow, simply submit a question with the tag "azure-iot-hub". 
+
+If your technical question requires submitting service logs, you can submit an Azure Support Ticket: https://docs.microsoft.com/en-us/azure/azure-supportability/how-to-create-azure-support-request
+
+------------------------------- delete above -------------------------------

build/.horton-e2e.yml

@@ -0,0 +1,20 @@
+variables:
+  Horton.FrameworkRoot: $(Agent.BuildDirectory)/e2e-fx
+  Horton.FrameworkRef: master
+  Horton.Language: c
+  Horton.Repo: $(Build.Repository.Uri)
+  Horton.Commit: $(Build.SourceBranch)
+  Horton.ForcedImage: ''
+
+resources:
+  repositories:
+  - repository: e2e_fx
+    type: github
+    name: Azure/iot-sdks-e2e-fx
+    ref: refs/heads/master
+    endpoint: 'GitHub OAuth - az-iot-builder-01'
+
+jobs:
+- template: vsts/templates/jobs-gate-c.yaml@e2e_fx
+
+

build_all/docs/Doxyfile

@@ -38,7 +38,7 @@ PROJECT_NAME           = "Microsoft Azure IoT Device SDK for C"
 # could be handy for archiving the generated documentation or if some version
 # control system is used.
 
-PROJECT_NUMBER         = 1.2.12
+PROJECT_NUMBER         = 1.3.0
 
 # Using the PROJECT_BRIEF tag one can provide an optional one line description
 # for a project that appears at the top of each page and should give viewer a

doc/Docker_SDK_Cross_Compile.md

@@ -15,16 +15,21 @@ The Docker container is based on the latest Ubuntu Docker container. From there
 * nano - in case one needs to edit any files in the Docker container
 
 Once this is complete, the script will acquire all of the prerequisites. These are:
-* The toolchain that will build binaries for our target platform. You should substitute the toolchain for your target platform.
+* The toolchain that will build binaries for our target platform. You should substitute the toolchain for your target platform
 * [The IoT SDK source code](https://github.com/azure/azure-iot-sdk-c).
-* [OpenSSL](https://www.openssl.org/) at version 1.0.2o.
-* [cURL](https://curl.haxx.se/) at version 7.60.0.
+* [OpenSSL](https://www.openssl.org/) - version 1.0.2o used
+* [cURL](https://curl.haxx.se/) - version 7.60.0 used
 * [util-linux](https://en.wikipedia.org/wiki/Util-linux) for uuid functionality.
 
 With all of those in place we can build OpenSSL, cURL, and libuuid. These will be installed into the toolchain as each is built and will be used in the final step when the SDK itself is built.
 
+## Major Tasks
+You will need to identify a suitable toolchain for your target platform and modify the line that downloads this toolchain in your Docker script. 
+
+Once this is done, then the environment variable set below will need to be modified to reflect the location and directory names of that toolchain. Once these have been updated then the Docker script should be ready to run.
+
 ## The Docker Script
-Here is the script:
+Here is an example script:
 ```docker
 # Start with the latest version of the Ubuntu Docker container
 FROM ubuntu:latest
@@ -48,6 +53,11 @@ WORKDIR /home/builder
 RUN mkdir MIPSBuild
 WORKDIR MIPSBuild
 
+#
+# The following wget invocation will need to be modified to download a toolchain appropriate 
+# for your target device.
+#
+
 # Download the WRTNode cross compile toolchain and expand it
 RUN wget https://downloads.openwrt.org/barrier_breaker/14.07/ramips/mt7620n/OpenWrt-Toolchain-ramips-for-mipsel_24kec%2bdsp-gcc-4.8-linaro_uClibc-0.9.33.2.tar.bz2
 RUN tar -xvf OpenWrt-Toolchain-ramips-for-mipsel_24kec+dsp-gcc-4.8-linaro_uClibc-0.9.33.2.tar.bz2
@@ -67,8 +77,10 @@ RUN tar -xvf curl-7.60.0.tar.gz
 RUN wget https://mirrors.edge.kernel.org/pub/linux/utils/util-linux/v2.32/util-linux-2.32-rc2.tar.gz
 RUN tar -xvf util-linux-2.32-rc2.tar.gz
 
+#
 # Set up environment variables in preparation for the builds to follow
-# These will need to be modified for the corresponding locations in the toolchain being used
+# These will need to be modified for the corresponding locations in the downloaded toolchain
+#
 ENV WORK_ROOT=/home/builder/MIPSBuild
 ENV TOOLCHAIN_ROOT=${WORK_ROOT}/OpenWrt-Toolchain-ramips-for-mipsel_24kec+dsp-gcc-4.8-linaro_uClibc-0.9.33.2
 ENV TOOLCHAIN_SYSROOT=${TOOLCHAIN_ROOT}/toolchain-mipsel_24kec+dsp_gcc-4.8-linaro_uClibc-0.9.33.2
@@ -142,16 +154,17 @@ WORKDIR ../..
 
 To run this script save it to a directory and change to that directory then simply enter:
 ```bash
-docker build -t mipsbuild:latest . --network=host
+docker build -t mipsiotbuild:latest . --network=host
 ```
-You can replace the value 'mipsbuild' with any name that describes your build. In this instance it is building for a MIPS32 processor hence the name. Once the build is complete you will be ready to build your application against the libraries just built.
+You can replace the value 'mipsiotbuild' with any name that describes your build. In this instance it is building for a MIPS32 processor hence the name. Once the build is complete you will be ready to build your application against the libraries just built.
 
 *Note:* The build of the Azure IoT C SDK uses cmake to generate the makefiles. In order to instruct cmake to perform a cross-compile one uses a cmake toolchain file. This tells cmake where to find the libraries etc. in the toolchain rather than on the host. This file is created on the fly in the above script to reduce dependencies on external files. Alternatively one could create this file outside the script and import into the container.
+
 ## Building Your Application
-Once you have successfully built the SDK you are now ready to create your application. Your application will also need to be cross compiled so adding additional steps to the end of the Dockerfile script to build your code is likely the easiest way to accomplish this. If you set up your application to also build with cmake then you can simply use the cmake toolchain file created to build the SDK. 
+Once you have successfully built the SDK you are now ready to create your application. You will need to create a directory that contains your source code and a CMakeLists.txt. The application build can use the cmake toolchain file that is already present in the image. 
 
 ### Sample ```CMakeLists.txt``` for an Application
-Here is a simple ```CMakeLists.txt``` file that demonstrates how to build an application that uses the libraries built above. This sample, for demonstration purposes uses the ```iothub_convenience_sample.c``` sample from the SDK.
+Here is a simple ```CMakeLists.txt``` file that demonstrates how to build an application that uses the libraries built above. This sample, for demonstration purposes uses a copy of the ```iothub_convenience_sample.c``` sample from the SDK.
 ```cmake
 cmake_minimum_required(VERSION 2.8.11)
 project(myapp_project)
@@ -183,17 +196,24 @@ link_directories($ENV{TOOLCHAIN_PREFIX}/lib)
 
 add_executable(myapp ${iothub_c_files})
 
-# Redundant in this case but shows how to rename your output executable
+# Redundant in this case but demonstrates how to rename your output executable
 set_target_properties(myapp PROPERTIES OUTPUT_NAME "myapp") 
 
 # List the libraries required by the link step
 target_link_libraries(myapp iothub_client_mqtt_transport iothub_client umqtt aziotsharedutil parson pthread curl ssl crypto m )
 ```
-### Sample Additions to Dockerfile to build the application
-This sample assumes that you have a subdirectory in the directory containing your Dockerfile called myapp. In this directory are the CMakeLists.txt file above and your code to be built. This will be copied to your Docker container and built. This fragment would be appended to the sample above.
+### Using a Separate Docker Script to Build the Application
+Though one could append the application build steps to the Docker script above, this will demonstrate how to use the existing image and build the application in a seperate Docker script. This will keep the original image clean so it may be used for building multiple applications.
+
+This sample script assumes you have your source files and the ```CMakeLists.txt``` in a directory called ```myapp```.
 ```docker
+FROM mipsiotbuild:latest
+
+USER builder
+WORKDIR /home/builder
+
 # Copy a directory from the host containing the files to build setting ownership at the same time
-ADD --chown=builder:builder myapp  ${WORK_ROOT}/myapp
+ADD --chown=builder:builder myapp myapp
 
 # Sanity check
 RUN ls -al myapp
@@ -212,21 +232,53 @@ RUN make
 # There should be an executable called myapp
 RUN ls -al myapp
 ```
-## Copying the Executable from the Docker Container
-The last step is to copy the new executable from your Docker container to your host so that it can be deployed to your target device. 
 
-Find out what your container is called, in this case it's vibrant_goodall.
+Execute this Docker script with:
 ```
-markrad@markradubuh:~/MIPS32cc$ docker container ls -a
-CONTAINER ID        IMAGE                                      COMMAND                   CREATED             STATUS                         PORTS               NAMES
-c6f501066027        259c8fe3911f                               "/bin/bash"               5 minutes ago       Exited (0) 5 minutes ago                           vibrant_goodall
+docker build -t mipsiotapp:latest . --network=host
 ```
-Copy the executable from the container to your local file system.
+## Copying the Executable from the Docker Container
+Now the applicaton is built the last step is to copy the new executable from your Docker container to your host so that it can be deployed to your target device. An example of how you might do this follows:
+
 ```
-docker cp vibrant_goodall:/home/builder/MIPSBuild/myapp/cmake/myapp ./myapp_exe
+id =$(docker create mipsiotapp)
+docker cp $id:/home/builder/myapp/cmake/myapp ./myapp_exe
+docker rm -v $id
 ```
-This will copy the executable to your local host and rename it to myapp_exe. If all has worked well then a ```file``` command executed against ```myapp_exe``` should, in this case, show as an ELF 32 bit MIPS32.
+The above steps will create and acquire the Docker container identifier, copy the application to the local directory on the host and then delete the container.
 
-**Note:** Depending upon your device you may need to copy additional binaries from the container in order to add them to your device. For example you device may not have the OpenSSL binaries so you will need to copy libssl.so and libcrypto.so. This could also be true for libuuid and libcurl. All of these libraries will be in the toolchain.
+**Note:** Depending upon your device you may need to copy additional binaries from the container in order to add them to your device. For example you device may not have the OpenSSL binaries so you will need to copy libssl.so and libcrypto.so. This could also be true for libuuid and libcurl. All of these libraries will be in the toolchain typically in ```/usr/local/lib```.
+# A Complete Example
+You can find two complete examples in [samples](../samples/dockerbuilds). This directory contains Docker scripts to cross compile the SDK for MIPS32 and for Raspbian and subsequently builds an application. In order to reduce the number of files required, the steps are slightly modified though they perform the same function. To cross compile the SDK for Raspbian, create an application and copy it to your host use the following steps. 
+```bash
+# Change directory to your Azure IoT SDK cloned repository root
+cd <SDK Root>
+# Work in this directory or two copies of the myapp directory will be required
+cd samples/dockerbuilds
+# Cross compile the SDK
+docker build -t rpiiotbuild:latest ./RaspberryPi --network=host
+# Build the application against the SDK
+docker build -t rpiiotapp:latest . --network=host --file ./RaspberryPi/Dockerfile_adjunct
+id=$(docker create rpiiotapp)
+# Copy application to home directory
+docker cp $id:/home/builder/myapp/cmake/myapp ~/myapp_rpi
+docker rm -v $id
+```
+And for MIPS32:
+```bash
+# Change directory to your Azure IoT SDK cloned repository root
+cd <SDK Root>
+# Work in this directory or two copies of the myapp directory will be required
+cd samples/dockerbuilds
+# Cross compile the SDK
+docker build -t mipsiotbuild:latest ./MIPS32 --network=host
+# Build the application against the SDK
+docker build -t mipsiotapp:latest . --network=host --file ./MIPS32/Dockerfile_adjunct
+id=$(docker create mipsiotapp)
+# Copy application to home directory
+docker cp $id:/home/builder/myapp/cmake/myapp ~/myapp_mips
+docker rm -v $id
+```
+**Note:** For these examples to work successfully the image names must be exactly as they are shown in the examples.
 ## Summing Up
 This document demonstrates how to compile the Azure IoT SDK for C along with all of its dependents and then create and link an application with the libraries and headers. It uses a MIPS32 toolchain for this demonstration but it should be easily adaptable to the toolchain required by the target device.