Import docs and git files

.gitattributes

@@ -0,0 +1,27 @@
+# Default behavior: if Git thinks a file is text (as opposed to binary), it
+# will normalize line endings to LF in the repository, but convert to your
+# platform's native line endings on checkout (e.g., CRLF for Windows).
+* text=auto
+
+# Explicitly declare text files you want to always be normalized and converted
+# to native line endings on checkout. E.g.,
+#*.c text
+
+# Declare files that will always have CRLF line endings on checkout. E.g.,
+#*.sln text eol=crlf
+
+# Declare files that will always have LF line endings on checkout. E.g.,
+*.sh text eol=lf
+*.json text eol=lf
+
+# Denote all files that should not have line endings normalized, should not be
+# merged, and should not show in a textual diff.
+*.docm binary
+*.docx binary
+*.ico binary
+*.lib binary
+*.png binary
+*.pptx binary
+*.snk binary
+*.vsdx binary
+*.xps binary

.gitignore

@@ -0,0 +1,208 @@
+# Compiled object files
+*.o
+*.opp
+
+# Compiled static libraries
+*.a
+
+## Ignore Visual Studio temporary files, build results, and
+## files generated by popular Visual Studio add-ons.
+
+# User-specific files
+*.suo
+*.user
+*.sln.docstates
+
+# Build results
+
+[Dd]ebug/
+[Rr]elease/
+x64/
+[Bb]in/
+[Oo]bj/
+/build/release/Maven
+!/build/release/
+[Cc]make/
+
+# Enable "build/" folder in the NuGet Packages folder since NuGet packages use it for MSBuild targets
+!packages/*/build/
+
+# MSTest test Results
+[Tt]est[Rr]esult*/
+[Bb]uild[Ll]og.*
+
+*_i.c
+*_p.c
+*.ilk
+*.meta
+*.obj
+*.pch
+*.pdb
+*.pgc
+*.pgd
+*.rsp
+*.sbr
+*.tlb
+*.tli
+*.tlh
+*.tmp
+*.tmp_proj
+*.log
+*.vspscc
+*.vssscc
+.builds
+*.pidb
+*.log
+*.scc
+
+# Visual C++ cache files
+ipch/
+*.aps
+*.ncb
+*.opensdf
+*.sdf
+*.cachefile
+
+# Visual Studio profiler
+*.psess
+*.vsp
+*.vspx
+
+# Guidance Automation Toolkit
+*.gpState
+
+# ReSharper is a .NET coding add-in
+_ReSharper*/
+*.[Rr]e[Ss]harper
+*.VC.opendb
+
+# TeamCity is a build add-in
+_TeamCity*
+
+# DotCover is a Code Coverage Tool
+*.dotCover
+
+# NCrunch
+*.ncrunch*
+.*crunch*.local.xml
+
+# Installshield output folder
+[Ee]xpress/
+
+# DocProject is a documentation generator add-in
+DocProject/buildhelp/
+DocProject/Help/*.HxT
+DocProject/Help/*.HxC
+DocProject/Help/*.hhc
+DocProject/Help/*.hhk
+DocProject/Help/*.hhp
+DocProject/Help/Html2
+DocProject/Help/html
+
+# Click-Once directory
+publish/
+
+# Publish Web Output
+*.Publish.xml
+
+# NuGet Packages Directory
+packages/
+
+# Windows Azure Build Output
+csx
+*.build.csdef
+
+# Windows Store app package directory
+AppPackages/
+
+# Others
+sql/
+*.Cache
+ClientBin/
+[Ss]tyle[Cc]op.*
+~$*
+*~
+*.dbmdl
+*.[Pp]ublish.xml
+*.pfx
+*.publishsettings
+*.jar
+
+# RIA/Silverlight projects
+Generated_Code/
+
+# Backup & report files from converting an old project file to a newer
+# Visual Studio version. Backup files are not needed, because we have git ;-)
+_UpgradeReport_Files/
+Backup*/
+UpgradeLog*.XML
+UpgradeLog*.htm
+
+# SQL Server files
+App_Data/*.mdf
+App_Data/*.ldf
+
+
+#LightSwitch generated files
+GeneratedArtifacts/
+_Pvt_Extensions/
+ModelManifest.xml
+
+# CPython & Wheels
+*.pyc
+*.pyd
+*.whl
+*.egg-info
+
+# =========================
+# Windows detritus
+# =========================
+
+# Windows image file caches
+Thumbs.db
+ehthumbs.db
+
+# Folder config file
+Desktop.ini
+
+# Recycle Bin used on file shares
+$RECYCLE.BIN/
+
+# Mac desktop service store files
+.DS_Store
+
+# Visual studio build artifacts
+*.tlog
+*.lastbuildstate
+*.idb
+*.exp
+*.lib
+*.dll
+
+# Visual Studio Temporary files
+*.VC.db
+
+# Windows CE build artifacts
+Build.err
+Build.wrn
+Buildx86retail.dat
+*.dat
+
+# hg directories should be ignored
+**/hg/
+
+# VS Code stuff
+**/typings/**
+**/.vscode/**
+# C/C++ extension for VS Code
+.browse.VC.db*
+
+csharp/device/NuGet/*.exe
+csharp/device/NuGet/*.nupkg
+csharp/device/.vs/*
+csharp/device/build/nuget.exe
+
+# .NET Micro Framework Emulator files and folders
+OnBoardFlash.dat
+OnBoardFlash.dat.smd
+DOTNETMF_FS_EMULATION*/

.gitmodules

@@ -0,0 +1,4 @@
+[submodule "device/external_modules/dotnetty"]
+	path = device/external_modules/dotnetty
+	url = https://github.com/Azure/DotNetty.git
+	branch = dev

CONTRIBUTING.md

@@ -0,0 +1,34 @@
+**The Azure IoT SDKs team wants to hear from you!**
+
+- [Ask a question](#ask-a-question)
+- [File a bug](#file-a-bug)
+- [Contribute documentation](#contribute-documentation)
+- [Contribute code](#contribute-code)
+
+# Ask a question
+Our team monitors Stack Overflow, especially the [azure-iot-hub](http://stackoverflow.com/questions/tagged/azure-iot-hub) tag. It really is the best place to ask.
+
+We monitor the Github issues section specifically for bugs found with our SDK, however we will reply to questions asked using Github issues too.
+
+# File a bug (code or documentation)
+That is definitely something we want to hear about. Please open an issue on github, we'll address it as fast as possible. Typically here's the information we're going to ask for to get started:
+- What SDK are you using (Node, C, C#, Python, Java?)
+- What version of the SDK?
+- Do you have a snippet of code that would help us reproduce the bug?
+- Do you have logs showing what's happening?
+
+Our SDK is entirely open-source and we do accept pull-requests if you feel like taking a stab at fixing the bug and maybe adding your name to our commit history :) Please mention
+any relevant issue number in the pull request description.
+
+# Contribute documentation
+For simple markdown files, we accept documentation pull requests submitted against the `master` branch, if it's about existing SDK features.
+If your PR is about future changes or has changes to the comments in the code itself, we'll treat is as a code change (see the next section).
+
+# Contribute code
+Unlike documentation, we require pull-requests for code to be submitted against the `develop` branch in order to review and run it in our gated build system. We try to maintain a high bar
+for code quality and maintainability, we insist on having tests associated with the code, and if necessary, additions/modifications to the requirement documents.
+
+Also, have you signed the [Contribution License Agreement](https://cla.microsoft.com/) ([CLA](https://cla.microsoft.com/))? A friendly bot will remind you about it when you submit your pull-request.
+
+If you feel like your contribution is going to be a major effort, you should probably give us a heads-up. We have a lot of items captured in our backlog and we release every two weeks, so before you spend the time, just check with us to make
+sure your plans and ours are in sync :) Just open an issue on github and tag it "enhancement" or "feature request"

LICENSE

@@ -0,0 +1,21 @@
+Microsoft Azure IoT SDKs 
+Copyright (c) Microsoft Corporation
+All rights reserved. 
+MIT License
+Permission is hereby granted, free of charge, to any person obtaining a copy 
+of this software and associated documentation files (the ""Software""), to deal 
+in the Software without restriction, including without limitation the rights 
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell 
+copies of the Software, and to permit persons to whom the Software is 
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in 
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED *AS IS*, WITHOUT WARRANTY OF ANY KIND, EXPRESS OR 
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY, 
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE 
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER 
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM, 
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN 
+THE SOFTWARE.

doc/faq.md

@@ -0,0 +1,196 @@
+# Microsoft Azure IoT device SDK FAQ
+
+This document contains both general FAQs about the Microsoft Azure IoT device SDK as a whole, and specific FAQs about the C, .NET, Java, and Node.js SDKs in this repository ([azure-iot-sdks](https://github.com/Azure/azure-iot-sdks)).
+
+**Microsoft Azure IoT SDKs**
+
+- [Using Visual Studio 2013](#vs2013)
+- [Line-endings in repository zip archive](#lineendings)
+
+**Microsoft Azure IoT device SDK for C FAQs**
+
+- [Installing CMake manually](#cmake)
+- [Using the IoT Hub c-client libraries in C++](#cpp)
+
+**Microsoft Azure IoT device SDK for .NET FAQs**
+
+- [UWP support for Microsoft.Azure.Devices.Client](#uwpsupport)
+- [NotImplementedException thrown when using UWP](#notimpluwp)
+- [IotHubCommunicationException or FileNotFoundException thrown when using HTTP protocol](#httpexception)
+
+**Microsoft Azure IoT device SDK for Java FAQs**
+
+- [Error when using AMQP on Raspberry Pi2](#javapi2error)
+- [qpid-jms build fails](#qpidjmsbuildfail)
+
+**Microsoft Azure IoT SDK for Node.js FAQs**
+
+- [Using promises instead of callbacks with the device client](#nodepromisify)
+- [Why not use Typescript instead of Javascript?](#whyunotypescript)
+
+<a name="vs2013"/>
+## Using Visual Studio 2013
+
+The Visual Studio native C projects included in this repository ([azure-iot-sdks](https://github.com/Azure/azure-iot-sdks)) are Visual Studio 2015 projects. The following steps describe how to use Visual Studio 2013 if you are unable to install Visual Studio 2015 on your development machine.
+
+Note: You can download the free Community edition of Visual Studio 2015 [here](https://www.visualstudio.com/en-us/downloads/download-visual-studio-vs.aspx).
+
+1. Open the native C solution in Visual Studio 2013 (for example, azure_iot_sdks.sln in your home folder).
+2. In **Solution Explorer** select all the projects in the solution. The right-click in **Solution Explorer** and click **Properties**.
+3. Expand **Configuration Properties**, and then select **General**.
+4. Change the **Platform Toolset** to **Visual Studio 2013 (v120)**, then click **OK**.
+
+  ![][1]
+
+<a name="lineendings"/>
+## Line-endings in repository zip archive
+
+If you download a zip archive of this repository to a Windows machine, you may encounter errors when you run some of the scripts. This is due to the way GitHub handles line-endings in zip archives. For more information, see http://stackoverflow.com/questions/17347611/downloading-a-zip-from-github-removes-newlines-from-text-files.
+
+<a name="cmake"/>
+## Installing CMake manually
+
+If your Linux OS does not include CMake 3.0 and it is not possible to use a package installer, you can install CMake as follows:
+
+```
+wget https://cmake.org/files/v3.4/cmake-3.4.0-Linux-i386.sh
+chmod u+x cmake-3.4.0-Linux-i386.sh
+./cmake-3.4.0-Linux-i386.sh --help
+Usage: ./cmake-3.4.0-Linux-i386.sh [options]
+Options: [defaults in brackets after descriptions]
+  --help            print this message
+  --prefix=dir      directory in which to install
+  --include-subdir  include the cmake-3.4.0-Linux-i386 subdirectory
+  --exclude-subdir  exclude the cmake-3.4.0-Linux-i386 subdirectory
+```
+
+Make sure that the directory where you install CMake is on your path by exporting it. Alternatively, if you use the option `--prefix=/usr` when you install CMake it replaces your current installation.
+
+<a name="cpp"/>
+## Using the IoT Hub c-client libraries in C++
+
+Using the IoT Hub c-client code from C++ is no different than using it from c. Create your C++ project, then reference the client library as you normally would in c++, or install the package via the appropriate package manager based on your platform.
+
+<a name="uwpsupport"/>
+## UWP support for Microsoft.Azure.Devices.Client
+
+- [Overview](#overview)
+- [Project file and assembly](#project)
+- [Device client](#deviceclient)
+- [Asynchrony](#asynchrony)
+- [Library-specific behaviors](#library)
+- [Resources](#resources)
+
+<a name="overview"/>
+### Overview: Why UWP?
+
+UWP (Universal Windows Platform) is an evolution of Windows app model introduced in Windows 8. UWP provides a common app platform available on every device that runs Windows 10, including its IoT flavor, the IoT Core. (See https://msdn.microsoft.com/en-us/library/dn894631.aspx). UWP is the official application model supported on IoT Core.
+
+An existing .NET library can be made UWP-compatible by exposing WinRT interfaces and by porting the implementation to .NET Core (See http://blogs.msdn.com/b/dotnet/archive/2014/12/04/introducing-net-core.aspx)
+
+WinRT imposes certain constraints on the public APIs. Most importantly, only WinRT (and not .NET) types can be exposed. This allows other languages (including unmanaged languages like C++/CX and JavaScript) to consume such libraries.
+
+<a name="project"/>
+### Project file and assembly
+
+A new project file, Microsoft.Azure.Devices.Client.WinRT.csproj has been created. The project has been added to the main solution. The project produces a WinRT AppX package with metadata in Microsoft.Azure.Devices.Client.winmd.
+
+The existing .NET library, Microsoft.Azure.Devices.Client.dll, has remained unchanged (modulo a small number of breaking changes as described below).
+
+<a name="deviceclient"/>
+### DeviceClient
+
+WinRT does not allow exporting abstract classes, therefore **DeviceClient** has become a sealed concrete class. A new private abstract class, **DeviceClientImpl** has been added to maximally reuse the existing implementation.
+
+<a name="asynchrony"/>
+### Asynchrony
+
+Only WinRT types can be exported by WinRT assemblies. The signatures of async methods such as **ReceiveAsync** have been changed to return **AsyncTask** or **AsyncTaskOfMessage**, which is aliased to **Windows.Foundation.IAsyncAction** or **Windows.Foundation.IAsyncOperation<Message>** for WinRT, or **System.Threading.Tasks.Task** and **System.Threading.Tasks.Task<Message>** for .NET.
+
+<a name="library"/>
+### Library-specific Behaviors
+
+WINDOWS_UWP macro is used to differentiate between .NET and UWP behaviors at compile time. Currently, there are almost 200 occurrences of `#if WINDOWS_UWP` in the code.
+
+<a name="resources"/>
+#### Resources
+
+Desktop apps use either text files or XML (.resx) files to create resources. The compiler then embeds them into the assembly. The resources are retrieved using the System.Resources.ResourceManager class.
+
+UWP uses the Windows Store resource model that replaces the hub-and-spoke model common to .NET Framework desktop apps. In UWP apps, .resw files are used to create resources. The format of the file is the same as .resx, but the packaging mechanism is different. At compile time, all the .resw files for an app are packed into a single PRI file by the MakePRI utility and included with the app's deployment package. At run time, the **Windows.ApplicationModel.Resources.ResourceLoader** class and the types in the **Windows.ApplicationModel.Resources.Core** namespace provide access to app resources.
+
+To support resources in Microsoft.Azure.Devices.Client library, the existing Resource.resx file has been copied to Resource.resw. The two files will now need to be kept in sync. Unlike in the .NET version of the library, the UWP version does not contain generated C# files. Instead, a new file, WinRTResources.cs is introduced. Whenever a new string is added to the .resx/.resw file, a corresponding entry must be copied from Resources.Designer.cs to WinRTResources.cs (follow the existing entries as an example)
+
+<a name="notimpluwp"/>
+## System.NotImplementedException occurred in Microsoft.Azure.Devices.Client.winmd
+The Universal Windows Platform (UWP) version of the .NET client device library does **not** currently support **MQTT** protocol.
+
+For example, calling `DeviceClient deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, TransportType.Mqtt);`
+will result in "Mqtt protocol is not supported" exception.
+
+<a name="httpexception"/>
+## IotHubCommunicationException or FileNotFoundException thrown when using HTTP protocol
+
+The **DeviceClient** class in the Microsoft.Azure.Devices.Client package requires the **System.Net.Http.Formatting** class to communicate with IoT Hub over HTTP.
+
+You see an **IotHubCommunicationException** or **FileNotFoundException** exception when you try to use the HTTP protocol to send a device-to-cloud message:
+
+```
+DeviceClient deviceClient = DeviceClient.CreateFromConnectionString(DeviceConnectionString, TransportType.Http1);
+
+...
+
+await deviceClient.SendEventAsync(eventMessage);
+```
+
+To prevent these exceptions from happening, you should add **Microsoft.AspNet.WebApi.Client** NuGet package to your project.
+
+<a name="javapi2error"/>
+## Error when using AMQP on Raspberry Pi2
+When building Qpid using Maven on a Raspberry Pi2 you might encounter a known error with the *SureFire* plugin:
+
+```
+Error occurred during initialization of VM Could not reserve enough space for object heap
+
+Error: Could not create the Java Virtual Machine.
+```
+This results in a failure to build Qpid.  This is a known issue with OpenJDK7 (for more information, see http://laurenthinoul.com/how-to-solve-the-maven-vm-initialization-error/). This article recommends updating SureFire by updating your pom file. As an alternative, you can opt to skip the SureFire tests with the Maven build, using the following command:
+
+```
+mvn install -Dmaven.test.skip=true
+```
+
+For more information, see http://maven.apache.org/surefire/maven-surefire-plugin/examples/skipping-test.html.
+
+<a name="qpidjmsbuildfail"/>
+## qpid-jms build fails
+
+If you get a build error when you try to [build qpid-jms](get_started/java-devbox-setup.md), then you should set the following  variable in your environment before you run `mvn install`.
+
+Windows: `set _JAVA_OPTIONS=-Xmx512M`
+
+Linux: `export _JAVA_OPTIONS=-Xmx512M`
+
+[1]: media/PlatformToolset.png
+
+<a name="nodepromisify"/>
+## Using promises instead of callbacks with the device client
+Currently the device client asynchronous functions follow the callback pattern rather than returning promises. If you wish to use the SDK with promises instead of callbacks, it's extremely easy though, using the bluebird library to "promisify" the device client class.
+
+```javascript
+var Promise = require('bluebird'); 
+var client = Promise.promisifyAll(Client.fromConnectionString(connectionString, Amqp));
+```
+
+And there you have it. All the existing functions of the client still exist, and the promise-returning equivalent has been created and has the same name with `Async` appended to it. In other words:
+- `client.open(callback)` becomes `client.openAsync().then(...).catch(...)`
+- `client.send(message, callback)` becomes `client.sendAsync(message).then(...).catch(...)`
+- `client.complete(message, callback)` becomes `client.completeAsync(message).then(...).catch(...)`
+- etc.
+
+Events are unchanged, so you still subscribe to those the way you would with the un-promisified client.
+
+<a name="whyunotypescript" />
+## Why not use TypeScript instead of JavaScript for the SDK?
+At the time when the SDK development was started, pure JavaScript felt like a better choice in order to make contributions as easy as possible for any Node developer, whether or not he or she was aware and proficient with TypesSript. 
+We regularly re-evaluate this decision as we move forward and you are most welcome to provide feedback or contribute by opening issues or pull-requests and help us decide what to do in the future.

doc/manage_iot_hub.md

@@ -0,0 +1,120 @@
+# Manage IoT Hub
+
+Before a device can communicate with IoT Hub, you must add details of that device to the IoT Hub device identity registry. When you add a device to your IoT Hub device identity registry, the hub generates the connection string that the device must use when it establishes its secure connection to your hub. You can also use the device identity registry to disable a device and prevent it from connecting to your hub.
+
+To add devices to your IoT hub and manage those devices, you can use either of:
+
+- The cross-platform, command-line [iothub-explorer](#iothub-explorer) tool
+- The Windows-only, graphical [Device Explorer](#device-explorer) tool
+
+Use either of these tools to generate a device-specific connection string that you can copy and paste in the source code of the application running on your device. Both tools are available in this [repository][lnk-this-repo].
+ 
+> Note: While IoT Hub supports multiple authentication schemes for devices, both these tools generate a pre-shared key to use for authentication.
+
+> Note: You must have an IoT hub running in Azure before you can provision your device. The document [Set up IoT Hub][setup-iothub] describes how to set up an IoT hub.
+
+You can also use both of these tools to monitor the messages that your device sends to an IoT hub and send commands to you your devices from IoT Hub.
+
+<a name="iothub-explorer"/>
+## Use the iothub-explorer tool to provision a device
+
+The iothub-explorer tool is a cross-platform, command-line tool (written in Node.js) for managing your devices in IoT hub. You will need to pre-install Node.js for your platform including npm package manager from [nodejs.org](https://nodejs.org)
+
+To install this tool in your environment, run the following command in a terminal/shell window on your machine:
+
+```
+npm install -g iothub-explorer
+```
+
+See [Install iothub-explorer][lnk-install-iothub-explorer] for more information.
+
+To provision a new device:
+
+1. Get the connection string for your IoT hub. See [Set up IoT Hub][setup-iothub] for more details.
+
+2.  Run the following command to register your device with your IoT hub. When you run the command, replace `<iothub-connection-string>` with the IoT Hub connection string from the previous step and replace `<device-name>` with a name for your device such as **mydevice**.
+
+```
+iothub-explorer <iothub-connection-string> create <device-name> --connection-string
+```
+
+You should see a response like this:
+
+```
+Created device mydevice
+
+-
+...
+-
+  connectionString: HostName=<hostname>;DeviceId=mydevice;SharedAccessKey=<device-key>
+```
+
+Copy the device connection string information for later use. The samples in this repository use connection strings in the format `HostName=<iothub-name>.azure-devices.net;DeviceId=<device-name>;SharedAccessKey=<device-key>`.
+
+To get help on using the iothub-explorer tool to perform other tasks such as listing devices, deleting devices, and sending commands to devices, enter the following command:
+
+```
+iothub-explorer --help
+```
+
+For further information about using the iothub-explorer tool to perform tasks such as disabling a device, monitoring a device, and sending commands to a device see:
+
+- [Working with the device identity registry][lnk-iothub-explorer-identity]
+- [Working with devices][lnk-iothub-explorer-devices]
+
+<a name="device-explorer"/>
+## Use the Device Explorer tool to provision a device
+
+The Device Explorer tool is a Windows-only graphical tool for managing your devices in IoT Hub. 
+
+The easiest way to install the Device Explorer tool in your environment is to download the pre-built version by clicking [Azure IoT SDKs releases][lnk-releasepage]. Scroll down to the **Downloads** section to locate the download link for the **SetupDeviceExplorer.msi** installer. Download and run the installer.
+
+To run the Device Explorer tool, double-click the **DeviceExplorer.exe** file in Windows Explorer.
+The default installation folder for this application is **C:\Program Files (x86)\Microsoft\DeviceExplorer**.
+
+> Tip: Pin the **DeviceExplorer.exe** application to your taskbar in Windows for easier access.
+
+Before you register a new device in the IoT Hub device identity registry, you must connect Device Explorer to your IoT hub:
+
+1. Get the connection string for your IoT hub. See [Set up IoT Hub][setup-iothub] for more details.
+
+2. On the **Configuration** tab, paste the IoT Hub connection-string for your IoT hub into **IoT Hub connection string** and click **Update**:
+
+    ![][img-getstarted1]
+
+To register a new device with IoT Hub:
+
+1.  Click the **Management** tab to manage the devices connected to the IoT hub.
+
+    ![][img-getstarted2]
+
+2.  On the **Management** tab, click **Create** to register a new device with your IoT hub. The **Create Device** dialog appears. In the **Device ID** field, type a unique name for your device such as **mydevice**, or select **Auto Generate ID** to generate a unique ID. Then click **Create**.
+
+    ![][img-getstarted3]
+
+3.  The **Device Created** window appears, indicating that your device has been successfully registered with this IoT Hub.
+
+    ![][img-getstarted4]
+
+4. Right-click on a selected device to retrieve the connection string for your device:
+
+    ![][img-connstr]
+  
+5. Select **Copy connection string** to copy the device connection string to the clipboard. You can now paste this connection-string into the source code of the device application you are working with. The samples in this repository use connection strings in the format `HostName=<iothub-name>.azure-devices.net;DeviceId=<device-name>;SharedAccessKey=<device-key>`.
+
+For further information about using the Device Explorer tool to perform tasks such as disabling a device, monitoring a device, and sending commands to a device see [Using the Device Explorer tool][lnk-device-explorer-docs].
+
+
+[img-getstarted1]: media/device_explorer/iotgetstart1.png
+[img-getstarted2]: media/device_explorer/iotgetstart2.png
+[img-getstarted3]: media/device_explorer/iotgetstart3.png
+[img-getstarted4]: media/device_explorer/iotgetstart4.png
+[img-connstr]: media/device_explorer/connstr.png
+
+[lnk-this-repo]: https://github.com/Azure/azure-iot-sdks
+[setup-iothub]: setup_iothub.md
+[lnk-install-iothub-explorer]: ../tools/iothub-explorer/readme.md#install
+[lnk-iothub-explorer-identity]: ../tools/iothub-explorer/readme.md#identityregistry
+[lnk-iothub-explorer-devices]: ../tools/iothub-explorer/readme.md#devices
+[lnk-releasepage]: https://github.com/Azure/azure-iot-sdks-preview/releases
+[lnk-device-explorer-docs]: ../tools/DeviceExplorer/readme.md

doc/setup_iothub.md

@@ -0,0 +1,60 @@
+# Set up IoT Hub
+
+[Azure IoT Hub][iothub-landing] is a fully managed service that enables reliable and secure bi-directional communications between millions of IoT devices and an application back end. Azure IoT Hub offers reliable device-to-cloud and cloud-to-device hyper-scale messaging, enables secure communications using per-device security credentials and access control, and includes device libraries for the most popular languages and platforms.
+
+Before you can communicate with IoT Hub from a device you must create an IoT hub instance in your Azure subscription and then provision your device in your IoT hub. You must complete these steps before you try to run any of the sample IoT Hub device client applications in this repository ([azure-iot-sdks](https://github.com/Azure/azure-iot-sdks)).
+
+## Create an IoT hub
+
+You can use the [Azure Portal][azure-portal] to create an IoT hub to use with your devices.
+
+1. Log on to the [Azure Portal][azure-portal].
+
+2. In the jumpbar, click **New**, then click **Internet of Things**, and then click **Azure IoT Hub**.
+
+   ![][1]
+
+3. In the **New IoT Hub** blade, specify the desired configuration for the IoT Hub.
+
+   ![][2]
+
+    * In the **Name** box, enter a name to identify your IoT hub. When the **Name** is validated, a green check mark appears in the **Name** box.
+    * Change the **Pricing and scale tier** as desired. The getting started samples do not require a specific tier.
+    * In the **Resource group** box, create a new resource group, or select and existing one. For more information, see [Using resource groups to manage your Azure resources][resource-group-portal].
+    * Use **Location** to specify the geographic location in which to host your IoT hub.  
+
+
+4. Once the new IoT hub options are configured, click **Create**.  It can take a few minutes for the IoT hub to be created.  To check the status, you can monitor the progress on the Startboard. Or, you can monitor your progress from the Notifications section.
+
+    ![][3]
+
+
+5. After the IoT hub has been created successfully, open the blade of the new IoT hub, take note of the hostname URI, and click **Shared access policies**.
+
+    ![][4]
+
+6. Select the Shared access policy called **iothubowner**, then copy and take note of the connection string on the right blade.
+
+    ![][5]
+
+Your IoT hub is now created, and you have the connection string you need to use the [iothub-explorer or the Device Explorer][lnk-manage-iothub] tool. This connection string enables applications to perform management operations on the IoT hub such as adding a new device to the IoT hub.
+
+
+## Add devices to IoT Hub
+
+You must add details your device to IoT Hub before that device can communicate with the hub. When you add a device to an IoT hub, the hub generates the connection string that the device must use when it establishes the secure connection to the IoT hub.
+
+To add a device to your IoT hub, you can use the [iothub-explorer or the Device Explorer][lnk-manage-iothub] utility in this repository ([azure-iot-sdks](https://github.com/Azure/azure-iot-sdks)). These tools will generate a device specific connection string that you need to copy and paste in the source code of the application running on the device.
+
+
+[iothub-landing]: http://azure.microsoft.com/documentation/services/iot-hub/
+[azure-portal]: https://portal.azure.com
+[manage-iothub-portal]: http://azure.microsoft.com/documentation/articles/iot-hub-manage-portal/
+[lnk-manage-iothub]: manage_iot_hub.md
+[resource-group-portal]: https://azure.microsoft.com/documentation/articles/resource-group-portal/
+
+[1]: media/create-iot-hub1.png
+[2]: media/create-iot-hub2.png
+[3]: media/create-iot-hub3.png
+[4]: media/create-iot-hub4.png
+[5]: media/create-iot-hub5.png

readme.md

@@ -0,0 +1,75 @@
+This project has adopted the [Microsoft Open Source Code of Conduct](https://opensource.microsoft.com/codeofconduct/). For more information see the [Code of Conduct FAQ](https://opensource.microsoft.com/codeofconduct/faq/) or contact [opencode@microsoft.com](mailto:opencode@microsoft.com) with any additional questions or comments.
+
+# Microsoft Azure IoT SDK for .NET
+
+This repository contains both IoT device SDKs and IoT service SDKs. Device SDKs enable you connect client devices to Azure IoT Hub. Service SDKs enable you to manage your IoT Hub service instance.
+
+Visit http://azure.com/iotdev to learn more about developing applications for Azure IoT.
+
+The Microsoft Azure IoT device SDK for .NET contain code that facilitate building devices and applications that connect to and are managed by Azure IoT Hub services.
+
+Devices and data sources in an IoT solution can range from a simple network-connected sensor to a powerful, standalone computing device. Devices may have limited processing capability, memory, communication bandwidth, and communication protocol support. The IoT device SDKs enable you to implement client applications for a wide variety of devices.
+
+Each language SDK includes sample code and documentation in addition to the library code. The API reference documentation is [here](http://azure.github.io/azure-iot-sdks).
+
+### OS platforms and hardware compatibility
+
+Azure IoT device SDKs can be used with a broad range of OS platforms and devices. The minimum requirements are for the device platform to support the following:
+
+- Being capable of establishing an IP connection: only IP-capable devices can communicate directly with Azure IoT Hub.
+- Support TLS: required to establish a secure communication channel with Azure IoT Hub.
+- Support SHA-256: necessary to generate the secure token for authenticating the device with the service.
+- Have a Real Time Clock or implement code to connect to an NTP server: necessary for both establishing the TLS connection and generating the secure token for authentication.
+- Having at least 64KB of RAM: the memory footprint of the SDK depends on the SDK and protocol used as well as the platform targeted. The smallest footprint is achieved using the C SDK targeting microcontrollers.
+
+You can find an exhaustive list of the OS platforms the various SDKs have been tested against in the [Azure Certified for IoT device catalog](https://catalog.azureiotsuite.com/). Note that you might still be able to use the SDKs on OS and hardware platforms that are not listed on this page: all the SDKs are open sourced and designed to be portable. If you have suggestions, feedback or issues to report, refer to the Contribution and Support sections below.
+
+## Samples
+
+Whithin the repository, you can find various types of simple samples that can help you get started.
+Below is a complete list of all these simple samples.
+In addition to these simple samples, you can find a long list of [getting started guides](doc/get_started) that describe all the steps necessary to run the simple samples on a wide variety of devices and platforms.
+And if you are looking for end to end samples that show how to do simple analytics and processing of the data generated by your device using Azure services such as Stream Analytics, Big Data, Machine Learning and others, check out our [E2E samples gallery](http://aka.ms/azureiotsamples).
+
+- C# device SDK:
+   - [Simple .NET sample using AMQP](device/samples/DeviceClientAmqpSample): Shows how to connect to IoT Hub and send and receive raw messages using the AMQP protocol.
+   - [Simple .NET sample using HTTP](device/samples/DeviceClientHttpSample): Shows how to connect to IoT Hub and send and receive raw messages using the HTTP protocol.
+   - [Simple .NET sample using MQTT](device/samples/DeviceClientMqttSample): Shows how to connect to IoT Hub and send and receive raw messages using the MQTT protocol.
+   - [Simple UWP C++ sample](device/samples/CppUWPSample): Shows how to connect to IoT Hub and send and receive raw messages in a C++ [UWP](https://msdn.microsoft.com/windows/uwp/get-started/whats-a-uwp) (Universal Windows Platform) application.
+   - [Simple UWP JS sample](device/samples/JSSample): Shows how to connect to IoT Hub and send and receive raw messages in a JavaScript [UWP](https://msdn.microsoft.com/windows/uwp/get-started/whats-a-uwp) application.
+   - [Simple UWP C# sample](device/samples/UWPSample): Shows how to connect to IoT Hub and send and receive raw messages in a C# [UWP](https://msdn.microsoft.com/windows/uwp/get-started/whats-a-uwp) application.
+   - [Simple .NET Micro Framework 4.3 sample](device/samples/NetMFDeviceClientHttpSample_43): Shows how to connect to IoT Hub and send and receive raw messages from a device running .NET Micro Framework 4.3.
+   - [Simple .NET Micro Framework 4.2 sample](device/samples/NetMFDeviceClientHttpSample_42): Shows how to connect to IoT Hub and send and receive raw messages from a device running .NET Micro Framework 4.2.
+
+## Contribution, feedback and issues
+
+If you encounter any bugs, have suggestions for new features or if you would like to become an active contributor to this project please follow the instructions provided in the [contribution guidelines](CONTRIBUTING.md).
+
+## Support
+
+If you are having issues using one of the packages or using the Azure IoT Hub service that go beyond simple bug fixes or help requests that would be dealt within the [issues section](https://github.com/Azure/azure-iot-sdks/issues) of this project, the Microsoft Customer Support team will try and help out on a best effort basis.
+To engage Microsoft support, you can create a support ticket directly from the [Azure portal](https://ms.portal.azure.com/#blade/Microsoft_Azure_Support/HelpAndSupportBlade).
+Escalated support requests for Azure IoT Hub SDKs development questions will only be available Monday thru Friday during normal coverage hours of 6 a.m. to 6 p.m. PST.
+Here is what you can expect Microsoft Support to be able to help with:
+* **Client SDKs issues**: If you are trying to compile and run the libraries on a supported platform, the Support team will be able to assist with troubleshooting or questions related to compiler issues and communications to and from the IoT Hub.  They will also try to assist with questions related to porting to an unsupported platform, but will be limited in how much assistance can be provided.  The team will be limited with trouble-shooting the hardware device itself or drivers and or specific properties on that device. 
+* **IoT Hub / Connectivity Issues**: Communication from the device client to the Azure IoT Hub service and communication from the Azure IoT Hub service to the client.  Or any other issues specifically related to the Azure IoT Hub.
+* **Portal Issues**: Issues related to the portal, that includes access, security, dashboard, devices, Alarms, Usage, Settings and Actions.
+* **REST/API Issues**: Using the IoT Hub REST/APIs that are documented in the [documentation]( https://msdn.microsoft.com/library/mt548492.aspx).
+
+## Additional resources
+
+In addition to the language SDKs, this repository ([azure-iot-sdks](https://github.com/Azure/azure-iot-sdks)) contains the following folders:
+
+### /build
+
+This folder contains various build scripts to build the libraries.
+
+### /doc
+
+This folder contains the following documents that are relevant to all the language SDKs:
+
+- [Set up IoT Hub](doc/setup_iothub.md) describes how to configure your Azure IoT Hub service.
+- [Manage IoT Hub](doc/manage_iot_hub.md) describes how to provision devices in your Azure IoT Hub service.
+- [FAQ](doc/faq.md) contains frequently asked questions about the SDKs and libraries.
+- [Azure Certified for IoT device catalog](https://catalog.azureiotsuite.com/).
+