If you prefer using Chrome* DevTools to debug your JavaScript* applications, rather than the command-line debug tool built into Node.js*, you should consider using one of these two options:
- Chrome Inspect for Node — if your IoT Node.js version is 6.3.0 or newer.
- Node Inspector— if the version of Node.js on your IoT device is 6.2.x or older.
Both support a connection to Chrome DevTools in the Chrome browser on your host development system to the remote Node.js application running on your headless IoT target device. Additional Node.js debugging options are described on the Debugging Node.js Apps documentation page.
For help setting up a remote Node.js for IoT JavaScript development environment, see the companion article titled Alternatives to Using the Intel® XDK to Develop Node.js* IoT Applications.
NOTE: The Nuclide* package for Atom* "add-on" provides built-in support for Chrome DevTools and remote development of Node.js applications within a convenient development environment. You will need to install the Atom editor by GitHub* to use this tool.
Using Chrome* Inspect for Node.js*
This debug technique requires:
- Chrome Browser version 55 or higher on your host development system
- Node.js version 6.3.0 or higher on your IoT target device
If you are using older versions of the above components consider using the Node Inspector debug solution, described in the next major section of this document.
If your versions of Node.js and Chrome meet the requirements stated above, there is nothing more that needs to be installed onto your target IoT device or your host development system.
Configuring Chrome*
Some initial configuration in the Chrome browser is required to make this work. Open your the Chrome browser on your host development system and type the following into the URL address bar:
chrome://inspect
Then, make sure the Discover network targets box is checked and push the Configure... button located to the right of that checkbox item (as shown in the image below).
The Configure... button will bring up a Target discovery settings dialog similar to the one shown below. In this dialog you can add the names (or IP addresses) of your IoT target devices, appended with port 9229.
In this example, we are using an IoT device named "de3815-paf2" which is addressable as "de3815-paf2.local" on the local network via MDNS/Avahi/Bonjour (see this companion article for more information about configuring MDNS). If you have a corporate name service on your network the device might be named something like "my-iot-hostname.mycompany.com" or it might be accessible simply as "my-iot-hostname" without any domain qualifier. Use any name that responds to a "ping" command, or use the device IP address if it is statically assigned and you know it will never change.
Using Chrome* Inspect
With "chrome://inspect" configured and running, you can get started debugging your remote IoT application in Chrome DevTools. Using ssh (or PuTTY), log into your IoT target and start the application in "debug mode" by typing the following:
$ node --inspect --debug-brk <my-app-name>.js
In the example below, the application to be debugged is named main.js and is located in the ~/node-debug-test folder.
The application being debugged in this example uses the MRAA library, which requires that this application be run as root. Thus the reason for the sudo -E bash command, which is simply a convenient way to get a root prompt.
The --debug-brk option pauses your application at the first line of executable code. Additional command-line options are described in the Node.js debug doc pages.
NOTE: DO NOT open the long "chrome-devtools://devtools/..." URL! That only works if the application and Chrome are on the same system. In this case the application is running on your IoT target device and Chrome is on your host development system.
Once the application has been started in "debug mode" it should appear in the chrome://inspect tab in the Chrome browser window on your host development system. If you do not have Chrome running, start it and enter chrome://inspect into the URL address bar to see a list of debuggable devices and applications.
Click the blue inspect link that appears in the chrome://inspect tab.
In this example you can see the application waiting to be debugged is listed under the title "Remote Target #DE3815-PAF2.LOCAL" and lists the Node.js version (v6.10.3) followed by the name of the application (main.js) and the location on the IoT file system of that application (/home/ubuntu/node-debug-test/main.js).
Clicking the inspect link should bring up an instance of Chrome DevTools for Node.js, similar to that shown below. Obviously, the details of the Chrome DevTools window will vary as a function of the application you are debugging. This is a view of the "blink LED" sample application borrowed from the Intel® XDK.
From here you can use a version of Chrome DevTools tailored for use with Node.js to single-step, break and inspect objects within your application. Notice also that you have access to the JavaScript console for quick tests and debugging.
For help with using Chrome DevTools, see these doc pages on the Google Developers site.
NOTE: if you use console.log() messages in your application they should appear in the Chrome DevTools console, and they will also appear in your remote IoT device's ssh console. This is especially of value if your application ends immediately after issuing some console.log() messages, in which case those messages will appear in the ssh console but may get dropped from the remote Chrome DevTools console, due to a sudden loss of the debug connection.
Using Node Inspector
This debug technique works best with:
- Chrome Browser on your host development system
- Node.js version 6.2.x or lower on your IoT target device
NOTE: If your IoT target device is running Node.js version 6.3.0 or higher consider using the Chrome Inspect for Node debug solution described in the previous section. It provides a superior debug environment and is easier to setup.
Installing Node Inspector
Before you can use this technique you must first install the Node Inspector node module on your IoT target. Log into your IoT target device, using ssh or PuTTY, and type the following command:
$ npm install -g node-inspector
No additional software needs to be installed on your host development system, other than the Chrome browser.
Starting a Node Inspector Debug Session
At the remote login shell on your IoT target device, type the following:
$ node-debug --debug-brk --cli --web-host 192.168.0.2 my-app.js
Where the IP address listed after the --web-host option is your IoT target device's IP address and my-app.js is the name of the Node.js application you are going to run and debug on your IoT system.
If you are uncertain of your IoT device's IP address, type "ping $HOSTNAME" on the remote login shell of your IoT target device and use the IP address that is reported by that command.
In the example below, the application to be debugged is named main.js and is located in the ~/node-debug-test folder.
The application being debugged in this example uses the MRAA library, which requires that this application be run as root. Thus the reason for the sudo -E bash command, which is simply a convenient way to get a root prompt.
The --debug-brk option pauses your application at the first line of executable code and the --cli option makes sure node-debug does not attempt to automatically open a browser on your remote IoT device. Additional command-line options are described in the Node Inspector README.
Once the application has been started in "debug mode" it prints a URL (e.g., "http://192.168.20.37:8080/?port=5858" in the example above). Copy that URL into the Chrome browser window on your host development system to open a copy of Chrome DevTools, as shown below.
The details of the Chrome DevTools window you see will vary as a function of the application you are debugging. This is a view of the "blink LED" sample application borrowed from the Intel® XDK.
From here you can use Chrome DevTools to single-step, break and inspect objects within your remote Node.js application. Notice also that you have access to the JavaScript console for quick tests and debugging.
For help with using Chrome DevTools, see these doc pages on the Google Developers site.
NOTE: if you use console.log() messages in your application they should appear in the Chrome DevTools console, and they will also appear in your remote IoT device's ssh console. This is especially of value if your application ends immediately after issuing some console.log() messages; in which case those messages will appear in the ssh console but may get dropped from the remote Chrome DevTools console, due to a sudden loss of the debug connection.