This repository contains a UX reference implementation that enables device management capabilities for devices registered with an Azure IoT hub. These capabilities include:
- Querying for devices.
- Configuring a view into the list of devices.
- Basic CRUD operations on single and multiple devices.
- Setting tags, service, and device properties on a device.
- Sending commands to devices that correspond to firmware update, reboot, and factory reset device jobs.
- Querying for a list of jobs submitted to the hub.
For more about device management functionality provided by Azure IoT Hub please see:
- Azure IoT device management overview
- How to create an Azure IoT Hub and provision devices
- Explore Azure IoT Hub device management using the sample UI
- UX will start timing out after 60 minutes and server (console window) will report 500. Use below steps to stop and restart the services.
- Server debugging not working
- Browser window does not launch when using develop mode on Mac/OSX
You will need an active Azure subscription. If you don't have an account, you can create a free trial account in just a couple of minutes. For details, see Azure Free Trial.
You need to create a device management enabled IoT Hub to obtain an IoT Hub connection string. You can create a device management enabled IoT Hub in the Azure portal.
You can find Node.js for windows/mac/linux here.
Windows/OSX/Linux are all supported operating systems. Using a git client clone this repository to a local folder on your machine.
If you are using bash, you can use the following command:
git clone https://github.com/Azure/azure-iot-device-management.git
Execute all the console/command prompt commands below in the root of the cloned folder (for example, /user/me/git/azure-iot-device-management).
In a console or node command prompt, run (ignoring any warnings):
npm install
When the npm install command has completed you are returned to the prompt without any errors. You only need to re-run this command after you pull the latest code from the repository.
In a console or command prompt, run:
npm run build
Execute this command when you first clone the repository and whenever you update the code by editing it or by pulling changes from the repository.
Use a text editor to open the user-config.json file in root folder of your cloned copy of the repository.
Replace the text <YOUR CONNECTION STRING HERE> with the hub's connection string. You can find the connection string in the Azure portal. Be sure to save the file. This is a one-time operation and only needs to be repeated if you purge the local copy of the repository or decide to use a different IoT Hub.
The following flags are in the same user-config.json file as your hub connection string.
Console Reporting:
key: "CONSOLE_REPORTING"
values:
"none"- no logging of any kind."client"- logs all requests for static assets (html/js/css)."server"- logs all API requests going into or out from the server as well as any uncaught exceptions."both"(default) - logs all requests coming into and out from the server as well as any uncaught exceptions.
Log Level: Setting the log level forces only log records at that level or higher to be logged.
key: "LOG_LEVEL"
values:
"trace"(default)"debug""info""warn""error""fatal"
Ensure you have completed the Environment preparation step.
This mode runs the code without the overhead of a developer setup. This is useful when you only need to run the code as an app.
In a console or command prompt, run:
npm run start
The console window reports:
Services starting...
Services started: listening on <PORT>
Where <PORT> is the configured port that the services are currently listening on (see Configuration below). By default, this is port 3003.
Supported browsers are: Edge/IE 11+/Safari/Chrome
In the console window running the services use CTRL+C. You can re-start immediately from this state using the npm run start command.
The recommended editor is vscode
To start the developer experience, launch a console or command prompt and run:
npm run develop
This runs a build and launches a browser window to the port configured (see Configuration below). The default is port 3003. Whenever you edit and save any files the code automatically recompiles and the browser refreshes.
You can find various smaller tasks in the build-scripts\test.js file. More general tasks are listed below.
This command builds the project, putting the output into the dist folder. This is the basis for other tasks:
npm run build
This runs the both the server and app tests. A browser window launches on success with code coverage reports:
npm run test
To debug the app, use your browser developer tool. All client files are transpiled javascript, sass/css, or html.
To debug the server
-
Use vscode to add breakpoints to javascript transpiled code generated in dist\server folder
-
Run node in debug mode
node debug dist/server/start.js
Follow the debugging instructions here
- Switch to node debugger, select "Attach Server Debug" and press play. You can find the vscode debugger instructions here
- Please visit here to learn how run a node.js application on Azure.
- You should run the application using the https protocol if you are deploying outside of a local setup.
- Create a website with git credentials, and add it as a remote for your pulled copy. See Getting Started with NodeJS for more details.
- Navigate to the website in the Azure Portal.
- Add the app setting
IOTHUB_CONNECTION_STRINGwith the hub connection string. - Push from your local github repository.
- If you find that the application isn't starting, turn on logging in iisnode.yml and investigate the stderr. This most often occurs because it can't find the connection string. By default stdout and stderr are dropped in the 'logs' folder under the site.
- If you find that you're getting a number of 503s when launching the application, wait a little bit and try refreshing.
- The first deployment sometimes disconnects when doing the install step. If this occurs, pushing again will resolve the issue.
There are three places where you can configure the experience. In order of preference:
- The user-config.json file. This configuration is suitable for development experience only.
- Environment variables. This configuration is suitable when deploying.
- Hard-coded defaults (if they exist).