Target device software prerequisites (Ubuntu example)

The Intel® XDK provides many paths into IoT development, and is compatible with many Intel Architecture (aka x86) IoT devices running the Linux* operating system. Regardless of which IoT device you have, or which distribution of Linux is running on your IoT device, there are some minimum prerequisites that your IoT device needs before you can use it with the Intel XDK. The specific example used in this document is for a target IoT device running the Ubuntu* distribution of Linux.

For detailed instructions on installing prerequisite dependencies for a specific board's default OS, please select your IoT device from its respective "Configure a <Device>" page inside the Configure your IoT dev boards section (left-side contents of this doc book). The page you are now reading describes generically what you can expect to install no matter which Linux OS you are using (it uses Ubuntu as the example). Use this page as a checklist for getting started with a custom OS installation on your IoT device, or for working through problems if you are having trouble getting the Intel XDK (which runs on your host) to recognize your IoT device.

Software prerequisites

The following software components are maintained and provided by third-party communities, not by the Intel XDK team. As such, we provide links to each component's respective documentation and installation instructions. Note that installation instructions will vary as a function of the specific OS on your IoT device and describe software components that must be installed on your IoT device

The instructions that follow describe the software requirements for your IoT device, not for your host computer (the machine onto which you have installed the Intel XDK). In other words, these software components must be present on your IoT device in order to communicate and work with the Intel XDK (which runs on your Windows*, Mac* or Linux* host workstation).

Node.js and npm must be installed on your IoT device to run the Node.js IoT applications and samples you will create with the Intel XDK. Strictly speaking, the other components listed below are optional, but if they are not present they will severely limit the ability of the Intel XDK to identify and communicate with your IoT device.

  • ssh server -- The OpenSSH sshd daemon is recommended.
    Type "pgrep -a sshd" on your IoT device to determine if sshd is already installed and running.
    Use "which sshd" to locate an existing installed ssh server binary.

  • avahi-daemon -- May already be installed and running.
    Type "pgrep -a avahi-daemon" on your IoT device to determine if the daemon is running.
    For most Linux distributions, the "avahi-daemon" package is what you must install.

  • Avahi dns_sd library and header files -- Will likely need to be installed.
    On Debian Linux distributions, "libavahi-compat-libdnssd-dev" is the name of the package to be installed on your IoT device. This package contains the headers and lib files required to support installation of the Node.js mdns module, which is installed and used by the xdk-daemon that runs on your IoT board and communicates with the Intel XDK.

  • build-essential -- Required to install some Node.js, mraa and xdk-daemon components.
    Might also be required to install some Node.js modules used by your IoT apps.

  • nodejs -- Installation instructions can be found on the Node.js downloads page.
    NOTE: installing Node.js v4.x on your IoT device is recommended, for best results with the Intel XDK.

  • npm -- Installation instructions can be found on the NPM documentation site.
    NOTE: most Node.js installs now also include npm as part of the node installation.

  • xdk-daemon -- The Intel XDK daemon communicates with the Intel XDK.
    You need this component installed on your IoT device so the Intel XDK can locate, identify and communicate with your IoT device. The xdk-daemon transfers your IoT Node.js app files to your IoT device and starts and stops your app on behalf of the Intel XDK. It also provides redirection services for the remote CDT Node.js debugger.

  • mraa and upm -- MRAA (aka libmraa) is a low-level skeleton library for convenient I/O access on Linux platforms. The libmraa library is written in C/C++ with bindings to also support access via the Python, JavaScript and Java languages. It provides I/O mappings for simple control of hardware from high-level languages. This is not a required dependency for use with the Intel XDK; however, in order to use most of the IoT application samples and templates provided by the Intel XDK, you will need it installed on your IoT target device. See the MRAA doc pages and the UPM doc pages for API details. The complete source code for mraa and upm are available online.

  • disengage ModemManager -- this service, if present, interferes with the imraa service.
    You can install a udev rules file (see detailed description below)...
    Or, stop the ModemManager service using:

    # systemctl stop ModemManager
    # systemctl disable ModemManager

    to permanently disable ModemManager.
    NOTE: using a udev rules file is the recommended solution.

  • initialize Arduino 101 with firmata firmware -- optional.
    Required only if you will use an Arduino 101 as an "I/O expander" attached to an IoT Gateway (see the detailed description below for more information).

Installation of the above on an Ubuntu* IoT device

The above components can be installed onto many Linux systems for use as an Intel XDK IoT target device. As a reference example, the following component installation instructions were performed on an Intel x86 IoT device running a fresh installation of 64-bit Ubuntu* Server 16.04 LTS (aka Xenial), specifically:

$ uname -srmo
Linux 4.4.0-71-generic x86_64 GNU/Linux

These instructions should also work with Ubuntu 14.04 (aka Trusty).

In the following command-line examples, a '$' prompt indicates commands typed by a "normal" user at the command-line and a '#' prompt indicates commands typed by the "root" user at the command-line. The standard shell on an Ubuntu system is bash, which was used to execute the following commands using a remote ssh connection to the IoT device that is running Ubuntu. Your host machine (the workstation onto which you installed the Intel XDK) can be running Microsoft* Windows*, Apple* OSX* or Linux* -- it does not need to be running Ubuntu, only the IoT device is running Ubuntu in this scenario. 

All of the command-line prompts shown below are executed on the Ubuntu IoT device; meaning the software components are being installed onto your Ubuntu IoT device, not your workstation. Use a keyboard and video monitor attached to your IoT device or use a remote shell (via ssh or equivalent) from your workstation. None of the setup requires access to a GUI on the Ubuntu IoT device, so you can easily perform this configuration on a "headless" IoT device (e.g., Ubuntu Server).

It is assumed that your Ubuntu IoT device has access to the Internet. If your IoT device is behind a proxy or firewall you may have to configure it to gain access to the Internet before these instructions will work.

Install and configure the OpenSSH server

The Intel XDK provides a built-in ssh client (the SSH Terminal tab) to make it easy to "ssh" into your IoT device. However, this only works when your IoT target device has an ssh server (aka sshd) installed and running on it. Furthermore, the xdk-daemon that communicates with the Intel XDK requires that ssh server be configured to allow remote login as the root user.

The following command-lines assume you are logged in as a normal user on your Ubuntu IoT device, thus the '$' prompt.

To install and configure the ssh server on your IoT device, it may be necessary to login to your IoT device via an attached keyboard and video monitor, or via an IoT device serial port that is configured to provide a login prompt (which is only possible if such a port is available; e.g., some IoT devices provide a serial over USB port for easy, headless, remote access).

If an ssh server is already present on your IoT device, and you only need to configure it for remote root access, you can skip the step below to install an ssh server.

If there is no sshd (or equivalent ssh server) running on your IoT device, type the following command at a bash command-line prompt on your IoT device:

$ sudo apt install openssh-server

To create the root user and assign a root password for your IoT device, type:

$ sudo passwd root
$ sudo passwd –u root

To enable remote login via ssh as root to your IoT device, edit the sshd_config file on your IoT device per the following instructions. Normally this file is located in the /etc/ssh/sshd_config directory. You must edit this file as sudo, or root. You can use vi, emacs or nano:

$ sudo vi /etc/ssh/sshd_config

Using the editor, comment-out the line that says PermitRootLogin prohibit-password (some config files might use the phrase PermitRootLogin without-password) and add a line with PermitRootLogin yes directly below it. You can "comment out" a line in the config file by adding a '#' character before it, as shown below:

#PermitRootLogin prohibit-password
PermitRootLogin yes

Save the file and restart sshd by typing:

$ sudo systemctl restart sshd

When connecting and logging into your IoT device from the Intel XDK user interface, it is assumed you will always provide a root userid and password. This is because the xdk-daemon assumes, and the mraa library requires, that your IoT applications run with root privileges.

With the ssh service running on your IoT device, and remote root access established, you can initiate a remote ssh connection as the root user to your IoT device, from your workstation (i.e., from your laptop).

For the remaining IoT device setup steps, use your favorite ssh client to login to your IoT device remotely, as the root user. Until you have completed the Avahi daemon installation, you may have to identify your IoT device by its numerical IP address in order to establish a remote ssh connection.

From an Apple* OSX* machine, a Linux desktop or a Microsoft* Windows* 10 machine that has "Bash on Windows" enabled, the simplest way to remotely login to your IoT device is from a bash shell prompt (substitute the IP address of your IoT device):

$ ssh root@

The IP address shown above is a placeholder and will probably not work! You must substitute the IP address of your IoT device to establish a remote ssh connection!!

If you do not have "Bash on Windows" enabled (or you have an older version of Windows) you can install the MinGW MSYS utilities for a copy of ssh that will run directly from a Windows command prompt or from within the MSYS bash prompt (remember to add the MSYS utilities to your PATH). Otherwise, a free and popular alternative on Windows to using ssh is the PuTTY ssh and telnet client.

Install the Avahi daemon and libraries

The Avahi daemon and utilities are needed to help the Intel XDK locate your IoT device on your local network. Also, the xdk-daemon needs access to some Avahi development libraries so it can install and use the mdns node module. Avahi is an open-source implementation of Bonjour, which is also known as mDNS.

The following command-lines assume you are logged in as root on your Ubuntu IoT device, thus the '#' prompt.

Type the following at your IoT device's root prompt to install the Avahi daemon, related utilities and required header libraries:

# apt install avahi-daemon avahi-autoipd avahi-utils libavahi-compat-libdnssd-dev

The libavahi-compat-libdnssd-dev component includes the header files that are needed to install the Intel XDK daemon (aka, xdk-daemon) and the mdns node module on your IoT target device.

The avahi-daemon should be running, following a successful install. To check, type:

# service --status-all | grep avahi
 [ + ]  avahi-daemon

If the service command does exist on your system, the following command can be used:

# systemctl is-active avahi-daemon.service

You can quickly test operation of Avahi on your IoT device; from the command-line on your IoT target device type:

# ping $HOSTNAME.local

If you get a response similar to the following, your Avahi daemon is running and working:

PING iot-ubuntu-test.local ( 56(84) bytes of data.
64 bytes from ( icmp_seq=1 ttl=64 time=0.051 ms
64 bytes from ( icmp_seq=2 ttl=64 time=0.090 ms

With the Avahi daemon installed and running on your IoT device, you can now quickly identify your IoT device using the special local domain that is employed by mDNS/Avahi/Bonjour (assuming, of course, that you know the base hostname of your IoT device and your IoT device and development system are on the same local subnet).

On a typical Ubuntu Desktop or Mac OSX machine the mDNS/Bonjour/Avahi services and necessary utilities are already installed. In that case, type the following command at a terminal shell on your Apple or Linux development machine:

$ ping my-iot-base-hostname.local

Where "my-iot-base-hostname" is the base hostname of your IoT device. For example, using the results of the earlier on-device "ping $HOSTNAME.local" test, the following command typed on your development system would locate and identify that IoT device:

$ ping iot-ubuntu-test.local

A Windows machine needs the Apple Bonjour Service installed to perform this ping test. The Bonjour service is typically included with iTunes or any one of a variety of other applications that employ mDNS (typically software designed to support networked printers, media servers and NAS drives). To determine if the Bonjour service is already running on your Windows system, type the following at a Windows command prompt:

> net start | find "Bonjour"
   Bonjour Service

If you see the output "Bonjour Service" it means mDNS/Avahi/Bonjour is installed and running on your Windows system. In that case, the ping test described above will also work from a Windows command line.

If the Bonjour service is not running on your Windows system, it may have been disabled or you may need to install it. To install the Bonjour service, install iTunes or use the "Bonjour Print Services for Windows" installer available at

For more information about mDNS/Avahi/Bonjour and configuring Avahi, please see these useful documents:

Install the essential build tools

It may be necessary to compile some of the Node.js package components during installation, as well as some components of the mraa node library and the xdk-daemon. Likewise, if you create Node.js IoT apps that depend on third-party node modules your system may require access to developer build tools.

The following command-lines assume you are logged in as root on your Ubuntu IoT device, thus the '#' prompt.

At minimum, install the following development tool packages:

# apt install build-essential libssl-dev libkrb5-dev checkinstall

Optionally, some installers may also employ the libtool script and select components of autotools:

# apt install libtool automake

Install Node.js and npm

The Intel XDK supports the development of Node.js IoT apps. This means that your IoT device must include a copy of the Node.js runtime to run those IoT apps. You will also need a copy of the "Node Package Manager" (aka npm), to facilitate installation and management of node modules required by your Node.js IoT apps.

Node.js v4.x is recommended, for best results with the Intel XDK.

The following command-lines assume you are logged in as root on your Ubuntu IoT device, thus the '#' prompt.

To retrieve the version 4.x Node.js and npm packages, type the following at the root command-line (be sure to include the dash character at the very end):

# curl -sL | bash -

When that download script runs it will generate a long list of messages. The last few lines of those messages will look something like the following:

Get:5 xenial InRelease [4,634 B]
Get:6 xenial/main Sources [763 B]
Get:7 xenial/main amd64 Packages [967 B]
Get:8 xenial/main i386 Packages [962 B]
Fetched 7,326 B in 1s (4,678 B/s)
Reading package lists... Done

## Run `apt-get install nodejs` (as root) to install Node.js v4.x LTS Argon and npm

At this point the required Node.js packages have been downloaded; but they still need to be installed onto your IoT device. Type the following at the root command-line prompt to install the Node.js and npm packages:

# apt install nodejs

You can confirm that version 4.x of node, and the associated npm utility, has been installed on your IoT device by typing the following commands at your IoT device prompt. The output of those commands is shown for reference (your exact output may vary, especially the reported version numbers):

# which nodejs

# which node

# node --version

# which npm

# npm --version

Multiple methods can be used to install Node.js and npm onto your IoT target device. We recommend you use the technique shown above; and that you only install a single version of Node.js onto your IoT target device. For alternate installation methods, see this excellent article titled How to Install Node.js on Ubuntu.

Install the Intel XDK daemon

The Intel XDK daemon (aka xdk-daemon) communicates with the Intel XDK to simplify communicating with your IoT device over the local network. The xdk-daemon facilitates transfer of your IoT Node.js app files to your IoT device and starts and stops your IoT Node.js app on behalf of the Intel XDK. It also enables the redirection needed to make the remote CDT Node.js debugger available on your development system.

Unlike the processes described above, this process requires the use of the Intel XDK and will not be performed using a remote shell command-line on your IoT device.

The basic steps that will be followed are:

  • Download, install and run the Intel XDK.
  • Create the IoT LED blink project in the Intel XDK.
  • Connect to your IoT target device from the Intel XDK.
  • Following connection, the Intel XDK will download and install the <code>xdk-daemon</code>.
  • Reboot your IoT target device; it should now be listed in the Intel XDK connection dropdown.

Following are detailed steps to install the Intel XDK daemon onto your IoT device:

  1. Download and install the Intel XDK onto your development system.
  2. Create a blank IoT project in the Intel XDK:
    Select Projects tab > Start a New Project (lower left) > Templates

  3. Open the IoT project (it should already be open) and select the Develop tab. Make sure the "Intel XDK IoT" tab is selected, it will be used to confirm that installation messages can be seen. This is also known as the "IoT console":

  4. Using the pulldown in the "Develop Drawer" directly below the editor window, select Add Manual Connection:

    Provide your IoT device's IP address, use "root" as the username and type the "root" password for your IoT device:

    If the connection was successful, you should see something similar to the following:
  5. The xdk-daemon installation process can take many minutes to complete, especially if your IoT device has limited RAM or if it is located on a network that uses a proxy server but it has not been setup to access the Internet via that proxy server.

    If things are working correctly, you should see a sequence of screens similar to the following:

    You will also see messages in the "Intel XDK IoT" console window, similar to the following:
  6. Despite what the following dialog says, your IoT device may not reboot when the xdk-daemon installation is complete.

If you see a message similar to the following, in the IoT console, it means the installation has completed (you may have to scroll down in the IoT console to see the end of the messages):

Installing Service(s)
systemd path: /lib/systemd/system/
Created symlink from /etc/systemd/system/ to /lib/systemd/system/xdk-daemon.service.
Starting xdk-daemon now!
Setup complete!

In that case, you can cancel the "Installing Intel XDK daemon" dialog (above) and reboot your IoT device.

In most cases, the installation will only take a few minutes. However, as mentioned earlier, if your IoT device is on a network that is located behind a proxy server, but has not been configured to access the Internet via that proxy server, the installation can take as long as fifteen minutes. This is due to the multiple network timeout errors that will occur when the installation script attempts to download the mDNS node module over the Internet.

In that case, the install messages in the IoT console will include errors similar to the following:

npm ERR! fetch failed
npm WARN retry will retry, error on last attempt: Error: connect ETIMEDOUT
npm ERR! fetch failed
npm WARN retry will retry, error on last attempt: Error: connect ETIMEDOUT
npm ERR! fetch failed
npm ERR! Linux 4.4.0-72-generic
npm ERR! argv "/usr/bin/nodejs" "/usr/bin/npm" "install"
npm ERR! node v4.8.2
npm ERR! npm  v2.15.11
npm ERR! errno ETIMEDOUT
npm ERR! syscall connect
npm ERR! network connect ETIMEDOUT
npm ERR! network This is most likely not a problem with npm itself
npm ERR! network and is related to network connectivity.
npm ERR! network In most cases you are behind a proxy or have bad network settings.
npm ERR! network 
npm ERR! network If you are behind a proxy, please make sure that the
npm ERR! network 'proxy' config is set properly.  See: 'npm help config'

If you see errors like these in the IoT console, the mDNS node module was not successfully installed, and the Intel XDK will not be able to automatically identify your IoT device. However, everything else needed by the Intel XDK is installed and functioning. There is a simple workaround that requires adding a special Avahi service file to your IoT device, which provides the same function as the missing mDNS node module and will not require re-installing the xdk-daemon.

To install this special Avahi service file, ssh into your IoT device and create a file (named "xdk-app-daemon.service") in the "/etc/avahi/services" folder on your IoT device. The file contents are shown below:

<?xml version="1.0" standalone='no'?><!--*-nxml-*-->
<!-- /etc/avahi/services/xdk-app-daemon.service -->
<!DOCTYPE service-group SYSTEM "avahi-service.dtd">
  <name replace-wildcards="yes">%h</name>

Set the file permissions to '644' (i.e, "-rw-r--r--") using the following command:

# chmod 644 /etc/avahi/services/xdk-app-daemon.service

You can test this workaround by opening the "Select a Device" pulldown on the Develop tab to see if your IoT device is automatically detected by the Intel XDK (you must open an IoT project to see this pulldown). See the image below for an example of an automatically detected IoT device:

You may have to restart your IoT device after adding the Avahi service file before your IoT device can be automatically detected by the Intel XDK.

Install the mraa and upm libraries

These libraries are not a required dependency for use with the Intel XDK; however, in order to use most of the IoT application samples and templates provided by the Intel XDK, they must be installed on your IoT target device.

The mraa and upm Node.js libraries provide JavaScript APIs for sensor I/O and actuator access. The libraries are actually written in C/C++ and include a JavaScript interface for use by Node.js applications. A special service called imraa is also included that makes it possible to utilize an Arduino 101 attached to your IoT target device via USB as an "I/O extender" for prototyping IoT "edge device" applications. See the MRAA doc pages and the UPM doc pages for API details. The complete source code for mraa and upm are available online.

The following command-lines assume you are logged in as root on your Ubuntu IoT device, thus the '#' prompt.

# apt install software-properties-common
# add-apt-repository ppa:mraa/mraa
# apt update
# apt install libmraa1 libmraa-dev mraa-tools mraa-imraa python-mraa python3-mraa

The update command (third line above) may take some time to complete, be patient!

To confirm that the imraa service was successfully installed, type the following on your IoT target device command-line:

# which imraa

Now install the mraa node module:

# npm -g install mraa
> mraa@1.6.1 install /usr/lib/node_modules/mraa
> node-gyp rebuild

...many compile messages, with many warnings...

  SOLINK_MODULE(target) Release/
  COPY Release/mraa.node
make: Leaving directory '/usr/lib/node_modules/mraa/build'
mraa@1.6.1 /usr/lib/node_modules/mraa

Do not be alarmed by the many warning messages during the compilation phase of the installation. This is normal.

To confirm that the mraa node modules was successfully installed as a global module, and can be "required" in a Node.js app, type the following at the IoT device prompt:

# npm -g list --depth=0
├── mraa@1.6.1
└── npm@2.15.11
# node
> var x = require('mraa')
> x.getVersion()
> .exit

Installation of UPM modules is Under Construction!

Disengage the ModemManager tool

NOTE: if you installed mraa version 1.6.1 or later (see the previous section titled Install mraa and upm), this step should not be required, since the mraa-imraa package installation should have added the following udev rule on your system. Check for the existence of a /lib/udev/rules.d/60-mraa-imraa.rules file on your system; if it is not present, take the action described in this seciton.

In order to allow the imraa service (described in the next section) to work as an IoT Gateway with an attached Arduino 101 "I/O extender," you should install the following udev rules file (named 60-mraa-imraa.rules). This file will prevent the ModemManager service from attempting to lock the USB-to-serial port that belongs to the Arduino 101 device.

# Arduino 101 in DFU Mode
SUBSYSTEM=="usb", ATTR{idVendor}=="8087", ATTR{idProduct}=="0aba", MODE="666", ENV{ID_MM_DEVICE_IGNORE}="1"
# Arduino 101 in USB Mode
SUBSYSTEM=="usb", ATTR{idVendor}=="8087", ATTR{idProduct}=="0ab6", ENV{ID_MM_DEVICE_IGNORE}="1"

This udev rules file should be copied (as root) into the following location:

# cp 60-mraa-imraa.rules /lib/udev/rules.d
# chmod 644 /lib/udev/rules.d/60-mraa-imraa.rules

If the udev rules file does not work, you can use:

# systemctl stop ModemManager
# systemctl disable ModemManager

to permanently disable the ModemManager; unfortunately, disabling means your apps will not be able to use the ModemManager service to access a cellular modem (or similar device) on your IoT device. Thus, the udev rules file is the preferred solution.

Initialize Arduino 101 with the firmata firmware

Under Construction

If you have an Arduino 101 device attached to your IoT device via a USB port, typing the following command on your IoT device prompt, should locate and initialize the Arduino 101 for use as a Gateway I/O expander:

# imraa -a
imraa version is 1.4.0 good
dfu location: /usr/bin
lock file location: /tmp/imraa.lock
Starting to flash board
Ardunio 101 Device Node Path: /dev/ttyACM0
Waiting for device...
Waiting for device...
Device found!
flash cmd: /usr/bin/dfu-util -d ,8087:0ABA -D /usr/share/mraa/firmata101.ino.bin -v -a 7 -R
dfu-util 0.9

Copyright 2005-2009 Weston Schmidt, Harald Welte and OpenMoko Inc.
Copyright 2010-2016 Tormod Volden and Stefan Schmidt
This program is Free Software and has ABSOLUTELY NO WARRANTY
Please report bugs to

dfu-util: Invalid DFU suffix signature
dfu-util: A valid DFU suffix will be required in a future dfu-util release!!!
Opening DFU capable USB device...
ID 8087:0aba
Run-time device DFU version 0011
Claiming USB DFU Interface...
Setting Alternate Setting #7 ...
Determining device status: state = dfuIDLE, status = 0
dfuIDLE, continuing
DFU mode device DFU version 0011
Device returned transfer size 2048
Copying data from PC to DFU device
Download	[=========================] 100%        62876 bytes
Download done.
Sent a total of 62876 bytes
state(2) = dfuIDLE, status(0) = No error condition is present
dfu-util: can't detach
Resetting USB to switch back to runtime mode
SUCCESS: Sketch will execute in about 5 seconds.

The precise output may vary, but will be very similar to the above.

IMPORTANT: to run the experiment below, you must substitute the name of the tty port reported by the imraa -a command (that was typed in previous step). In this example the /dev/ttyACM0 port was reported (line six above) as the tty port that is connected to the Arduino 101 device.

To confirm that imraa and the Arduino 101 are working as an "I/O extender" on your Gateway device, try the following:

# node
> var x = require('mraa')
> x.addSubplatform(x.GENERIC_FIRMATA, "/dev/ttyACM0")
> x.hasSubPlatform()
> var y = new x.Gpio(525)
Gpio {}
> y.dir(x.DIR_OUT)
> y.write(1)
> y.write(0)
> y.write(1)

As you alternate between y.write(1) and y.write(0) you should see a small green LED on the Arduino 101 change from on to off, where writing a '1' to GPIO pin '525' turns the LED on and writing a '0' turns the LED off.

For more complete information about compiler optimizations, see our Optimization Notice.