Merge pull request #306 from dominicbetts/working-devicemanagement

Create new Manage IoT Hub doc and adjust links from other docs

c/readme.md

@@ -30,8 +30,7 @@ For information on how to use this library refer to the documents below:
 
 - [Prepare your development environment to use the Azure IoT device SDK for C](doc/devbox_setup.md)
 - [Setup IoT Hub](../doc/setup_iothub.md)
-- [Provision devices](../tools/iothub-explorer/doc/provision_device.md)
-- [Using the DeviceExplorer application to tests IoT Hub device connectivity](../tools/DeviceExplorer/doc/how_to_use_device_explorer.md)
+- [Provision and manage devices](../doc/manage_iot_hub.md)
 - [Azure IoT device SDK for C  tutorial](https://azure.microsoft.com/documentation/articles/iot-hub-device-sdk-c-intro/)
 - [Setup a Protocol Gateway - (i.e. MQTT)](https://github.com/Azure/azure-iot-protocol-gateway/blob/master/README.md)
 - [How to port the C libraries to other OS platforms](doc/porting_guide.md)

doc/get_started/openwrt-arduino-yun-c.md

@@ -76,7 +76,6 @@ apt-get install curl libcurl4-openssl-dev uuid-dev uuid g++ make cmake git unzip
 static const char* connectionString = "[device connection string]";
 ```
 - Replace "[device connection string]" with the device connection string you noted [earlier](#beforebegin). Save the changes.
-- The section "Send events" in the document [How to use Device Explorer](../../tools/DeviceExplorer/doc/how_to_use_device_explorer.md) describes how to prepare the **DeviceExplorer** tool to receive device-to-cloud messages from the sample application.
 - Run the `./build.sh` script in the **c/build_all/arduino** directory.   
 
 <a name="deploy"/>
@@ -115,13 +114,11 @@ You might get an error message at this step(return code 127), but the certificat
 ## Run the sample
 
 - Run the sample **/tmp/simplesample_http**
-- Use the **DeviceExplorer** utility to observe the messages IoT Hub receives from the **simplesample_http** application.
-- See "Send cloud-to-device messages" in the document [How to use Device Explorer for IoT Hub devices][device-explorer] for instructions on sending messages with the **DeviceExplorer** utility.
+- See [Manage IoT Hub][lnk-manage-iothub] for information about the tools you can use to monitor the messages your device sends to your IoT hub and to send commands to your devices.
 
 ***Note: To send a command to the device from iothub-explorer or DeviceExplorer, the command should be like {"Name":"TurnFanOff", "Parameters":{}}***
 
 [setup-devbox-linux]: devbox_setup.md
-[device-explorer]: ../../tools/DeviceExplorer/doc/how_to_use_device_explorer.md
-[setup-iothub]: ../../doc/setup_iothub.md
-[provision-device]: ./provision_device.md
+[setup-iothub]: ../setup_iothub.md
+[lnk-manage-iothub]: ../manage_iot_hub.md
 

doc/get_started/yocto-intel-edison-c.md

@@ -11,7 +11,7 @@ The following describes how to build and run the **simplesample_amqp** applicati
 ## Before you begin
 Before you begin you will need to create and configure an IoT hub to connect to.
   1. [Set up your IoT Hub][setup-iothub].
-  1. With your IoT hub configured and running in Azure, follow the instructions in [Connecting your device to an IoT hub][provision-device].
+  1. With your IoT hub configured and running in Azure, follow the instructions in [Manage IoT hub][provision-device].
   1. Make note of the Connection String for your device from the previous step.
 
   > Note: You can skip this step if you just want to build the sample application without running it.
@@ -143,4 +143,4 @@ We first need to update the credentials in the sample AMPQ app to match those of
 [img2]: ./media/edison02.png
 
 [setup-iothub]: ../setup_iothub.md
-[provision-device]: ../../tools/iothub-explorer/doc/provision_device.md
+[provision-device]: ../manage_iot_hub.md

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. 
+
+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/releases
+[lnk-device-explorer-docs]: ../tools/DeviceExplorer/doc/how_to_use_device_explorer.md

doc/setup_iothub.md

@@ -37,21 +37,20 @@ You can use the [Azure Preview Portal][azure-portal] to create an IoT hub to use
 
     ![][5]
 
-Your IoT hub is now created, and you have the connection string you need to use the [iothub-explorer][use-iothub-explorer] or the [Device Explorer][use-device-explorer] tool. This connection string enables applications to perform management operations on the IoT hub such as adding a new device to the IoT hub.
+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][use-iothub-explorer] or the [Device Explorer][use-device-explorer] 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.
+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/en-us/documentation/services/iot-hub/
 [azure-portal]: https://portal.azure.com
 [manage-iothub-portal]: http://azure.microsoft.com/en-us/documentation/articles/iot-hub-manage-portal/
-[use-device-explorer]: ../tools/DeviceExplorer/doc/how_to_use_device_explorer.md
-[use-iothub-explorer]: ../tools/iothub-explorer/doc/provision_device.md
+[lnk-manage-iothub]: manage_iot_hub.md
 [resource-group-portal]: https://github.com/Azure/azure-content/blob/master/articles/azure-portal/resource-group-portal.md
 
 [1]: media/create-iot-hub1.png

java/device/readme.md

@@ -17,8 +17,8 @@ The device library consists of a set of reusable components with abstract interf
 For more information on how to use this library refer to the documents below:
 - [Setup your development environment][devbox-setup]
 - [Setup IoT Hub](../../doc/setup_iothub.md)
-- [Provision devices](../../tools/iothub-explorer/doc/provision_device.md)
-- [Using the DeviceExplorer application to test IoT Hub device connectivity](../../tools/DeviceExplorer/doc/how_to_use_device_explorer.md)
+- [Provision devices](../../doc/manage_iot_hub.md)
+- [Test IoT Hub device connectivity](../../doc/manage_iot_hub.md)
 - [Run the Java sample][run-java-sample]
 - [How to build an IoTHub Java application from scratch on Windows][how-to-build-a-java-app-from-scratch]
 - [Java API reference](http://azure.github.io/azure-iot-sdks/java/device/api_reference/index.html)

java/service/readme.md

@@ -11,8 +11,8 @@ The Microsoft Azure IoT Service SDK for Java facilitates building applications t
 For more information on how to use this library refer to the documents below:
 - [Setup your development environment][devbox-setup]
 - [Setup IoT Hub](../../doc/setup_iothub.md)
-- [Provision devices](../../c/doc/provision_device.md)
-- [Using the DeviceExplorer application to test IoT Hub device connectivity](../../tools/DeviceExplorer/doc/how_to_use_device_explorer.md)
+- [Provision devices](../../doc/manage_iot_hub.md)
+- [Test IoT Hub device connectivity](../../doc/manage_iot_hub.md)
 - [Run the Java sample][run-java-sample]
 - [Java API reference](http://azure.github.io/azure-iot-sdks/java/service/api_reference/index.html)
 

node/device/readme.md

@@ -13,7 +13,7 @@ Use the device SDK to:
 For more information on how to use this library refer to the documents below:
 - [Prepare your node.js development environment](doc/devbox_setup.md)
 - [Setup IoT Hub](../../doc/setup_iothub.md)
-- [Provision devices](../../tools/iothub-explorer/doc/provision_device.md)
+- [Provision devices](../../doc/manage_iot_hub.md)
 - [Run a node.js sample application](doc/run_sample.md)
 - [Node API reference](http://azure.github.io/azure-iot-sdks/node/api_reference/azure-iot-device/1.0.0/index.html)
 - [Debugging with Visual Studio Code](../../doc/get_started/node-debug-vscode.md)

readme.md

@@ -61,11 +61,12 @@ This folder contains various build scripts to build the libraries.
 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.
 - [OS Platforms and hardware compatibility](https://azure.microsoft.com/en-us/documentation/articles/iot-hub-tested-configurations/) describes the SDK compatibility with different OS platforms as well as specific device configurations.
 
 ### /tools
 
 This folder contains tools you will find useful when you are working with IoT Hub and the device SDKs.
-- [iothub-explorer](tools/iothub-explorer/doc/provision_device.md): describes how to use the iothub-explorer node.js tool to provision a device for use in IoT Hub.
+- [iothub-explorer](tools/iothub-explorer/readme.md): describes how to use the iothub-explorer node.js tool to provision a device for use in IoT Hub, monitor the messages from the device, and send commands to the device.
 - [Device Explorer](tools/DeviceExplorer/doc/how_to_use_device_explorer.md): this tool enables you to perform operations such as manage the devices registered to an IoT hub, view device-to-cloud messages sent to an IoT hub, and send cloud-to-device messages from an IoT hub. Note this tool only runs on Windows.

tools/DeviceExplorer/doc/how_to_use_device_explorer.md

@@ -153,4 +153,4 @@ Run your sample application. Device Explorer should now show that the IoT hub ha
 [protocol-gateway]: https://github.com/Azure/azure-iot-protocol-gateway
 [lnk-devguide]: https://azure.microsoft.com/documentation/articles/iot-hub-devguide/
 [what-is-iot-hub]: https://azure.microsoft.com/documentation/articles/iot-hub-what-is-iot-hub/
-[iothub-explorer]: ../../iothub-explorer/doc/provision_device.md
+[iothub-explorer]: ../../iothub-explorer/readme.md

tools/iothub-explorer/doc/provision_device.md

@@ -1,41 +0,0 @@
-# Connecting your device to an IoT hub
-
-IoT Hub only allows connections from known devices that present valid credentials. This document describes how to use the *iothub-explorer* tool to provision a device for use in IoT Hub.  While IoT Hub supports multiple authentication schemes, the iothub-explorer tool generates a pre-shared key.
-
- > 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.
-
-## Provision the device in your IoT hub
-
-The iothub-explorer tool enables you to provision devices in your IoT hub. It runs on any computer where Node.js is available. For your convininence the tool is also published to  npm, preventing you from having to clone the repository or download the code. 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 commands in a terminal/shell window on your machine after making sure [node](http://nodejs.org) is installed. When running the commands, use the IoT Hub connection string from the previous step and replace "mydevice" with your desired device name.
-
-```
-npm install -g iothub-explorer
-iothub-explorer <iothub-connection-string> create mydevice --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=hub-name.azure-devices.net;DeviceId=device-id;SharedAccessKey=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
-```
-
-> Note: Windows users also have the option of using the [Device Explorer][device-explorer] application to provision devices.
-
-[setup-iothub]: ../../../doc/setup_iothub.md
-[device-explorer]: ../../DeviceExplorer/doc/how_to_use_device_explorer.md

tools/iothub-explorer/readme.md

@@ -3,6 +3,7 @@ A sample CLI tool to manage device clients using the Azure IoT Hub service SDK.
 
 [![npm version](https://badge.fury.io/js/iothub-explorer.svg)](https://badge.fury.io/js/iothub-explorer)
 
+<a name="install"/>
 ## Installing iothub-explorer
 
 > Note: This tool requires Node.js version 4.x or higher for all features to work.
@@ -19,6 +20,7 @@ You can use the following command to get additional help about all the iothub-ex
 $ iothub-explorer help
 ```
 
+<a name="identityregistry"/>
 ## Working with the device identity registry
 
 Supply your IoT Hub connection-string once using the **login** command. This means you do not need to supply the connection-string for subsequent commands for the duration of the session (defaults to one hour):
@@ -63,6 +65,7 @@ To delete a device from the device identity registry in your IoT Hub, use the fo
 $ iothub-explorer delete existing-device
 ```
 
+<a name="devices"/>
 ## Working with devices
 
 Use the following command to monitor the device-to-cloud messages from a device: