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 tool
- The Windows-only, graphical 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.
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 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.
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
To install this tool in your environment, run the following command in a terminal/shell window on your machine:
sudo npm install -g iothub-explorer
See Install iothub-explorer for more information.
To provision a new device:
-
Get the connection string for your IoT hub. See Set up IoT Hub for more details.
-
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 login <iothub-connection-string>iothub-explorer 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:
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. 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:
-
Get the connection string for your IoT hub. See Set up IoT Hub for more details.
-
On the Configuration tab, paste the IoT Hub connection-string for your IoT hub into IoT Hub connection string and click Update:
To register a new device with IoT Hub:
-
Click the Management tab to manage the devices connected to the IoT hub.
-
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.
-
The Device Created window appears, indicating that your device has been successfully registered with this IoT Hub.
-
Right-click on a selected device to retrieve the connection string for your device:
-
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.