2. Javascript APIs

MetaSensors are supported on Linux. Developers can create their own Apps using Node.Js on Linux.

Here is a tutorial to install Javascript/Node/NPM on Linux.

You should be comfortable with your choice of Linux distro.


Some installation steps may change or look slightly different depending on your Linux distro of choice.

2.1. Installation

Ubuntu is popular and highly recommended as the Linux distro of choice. Simply follow the Ubuntu install steps on the Ubuntu website :


The great thing about Ubuntu is that it comes with many packages installed. Please note that if you choose to install a bare-bones Linux distro, you may need to install many utilities, libraries and packages needed to support MetaWear development.

If you are going to use Raspbian OS, we recommend the “Raspbian Buster with desktop” (or similar), the lite and the max versions have either too much or too little pre-installed. Just follow the steps here.

For any other OS, simply follow the guide on their installation site.

2.1.1. OS Updates

If Ubuntu or your OS asks for an update, be kind and update! Run:

>>> sudo apt-get update

To upgrade (with caution) run: – this usually takes a while, DO NOT STOP IT.

>>> sudo apt upgrade

2.1.2. Bluetooth

Make sure that the Bluetooth hardware (adapter) is recognized by your OS by using the following command:

>>> hcitool dev

If your distro does not come with Bluetooth drivers installed, install the required packages with their dependencies:

>>> sudo apt install bluetooth pi-bluetooth bluez blueman bluez-utils

Check the bluetooth status:

>>> systemctl status bluetooth

Connect your Bluetooth device and restart the Bluetooth services:

>>> sudo /etc/init.d/bluetooth restart


>>> sudo systemctl start bluetooth

Verify your Bluetooth device is detected along with the appropriate modules:

>>> lsusb
    Device 005: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)

Finally review the output of hcitool dev:

>>> hcitool dev
        hci0    00:11:95:00:1A:CF

You can also load the Bluetooth command-line tool, you need to enter the following command on your Raspberry Pi.

>>> bluetoothctl

Now that we are in the Bluetooth command-line tool, we need to go ahead and turn the agent on.

Switching the agent on will allow us to search for and pair with other Bluetooth devices. You can do this by using the command below.

>>> agent on

The next step is to tell the Bluetooth device on our Raspberry Pi to scan for other devices.

By scanning for devices, we can retrieve their MAC address and begin the process of pairing that device with the Raspberry Pi. To start the scan process, all you need to do is enter the following command.

>>> scan on

From this command, you should start seeing a result like what we have below.

>>> [bluetooth]# scan on
    Discovery started
        [CHG] Controller DC:A6:32:05:7F:06 Discovering: yes
        [NEW] Device 51:B8:16:6A:6F:C6 51-B8-16-6A-6F-C6
        [NEW] Device 40:23:43:3F:4E:58 BRAVIA 4K UR2

If you are having difficulties, please consult the community forum and manual for your OS of choice. The Ubuntu forum has already addressed many issues you may come upon.

2.1.3. Dongles

Linux systems typically support USB to Bluetooth Dongle; they might even support multiple Dongles.

You can use these Dongles to get more sensors connected via the BLE link simultaneously.

First, plug in the USB to BLE Dongle.

Then, you can use lsusb -t to display how the USB devices and hubs are arranged and their allocated speeds.

>>> lsusb
    Bus 002 Device 005: ID 0a12:0001 Cambridge Silicon Radio, Ltd Bluetooth Dongle (HCI mode)
>>> hciconfig
    hci0:   Type: USB
>>> hciconfig -a hci0
    Manufacturer: Accel Semiconductor Ltd. (74)

If it shows up as an hci device, great, you are done!

If not, there are a couple things to consider. First, you need to make sure it is actually a Linux supported dongle: https://elinux.org/RPi_USB_Bluetooth_adapters.

If your dongle is not on this list, you are out of luck and need to purchase a new one that is on the list.


If you have two of the same dongles, sometimes the second dongle may not be recognized by the system.

Once you have determined that your BLE Dongle is Linux supported, run the following commands with the Dongles plugged-in:

>>> sudo apt-get update
>>> sudo apt-get upgrade
>>> sudo reboot now

2.1.4. Virtual Machines (VMs)

If you are running in a virtual environment, you will need to take extra care to make sure the Bluetooth drivers and adapters are working in the VM before you do anything else.

For example, VirtualBox guest OS doesn’t recognize the Bluetooth adapter by default. There are many great tutorials to get this working like this one here.


Steps you can take:

  1. Disable Bluetooth Adapter on Host OS
  2. Launch Guest OS
  3. Enable Bluetooth Adapter on Host OS
  4. Enable Bluetooth Adapter in the usb device list (Guest OS): Devices->usb->check my device

You may also need to install the VirtualBox extension Pack or similar support software, see more information here.

MbientLab is not responsible for VM support. Please consult the forum for the appropriate VM software you are using if you run into issues.

2.1.5. Internet

You also need to make sure you have internet access. The quickest way to test this is to use ping in the terminal:

>>> ping www.google.com

Also check with:

>>> ip address show
>>> ip link show

If you are having trouble, you can Google “How to connect to the internet on Ubuntu” or similar. There are many options to connect to the internet including wireless and LAN; we quickly highlight them below.

You can troubleshoot through the Ubuntu Network manager. If your local network connection isn’t working, ensure the Enable Networking and Enable Wi-Fi options are selected here in the menu:


Connect to a Wireless Network

If you have a wireless-enabled computer running the Ubuntu operating system, you can connect to a nearby wireless network to get to the internet. To do this:

  1. Open the System Menu on the right side of the top bar.
  2. Click on Wi-Fi Not Connected to expand the menu.
  3. Click on Select Network.
  4. Look through the names of the nearby networks. Select the one you want. If you don’t see the name of the network you want, click More to see additional networks. If you still don’t see the network you want, it may be hidden or you may be out of range.
  5. Enter the password for the network and click Connect.

Configure to a Wired Network

To set up most wired network connections, all you need to do is plug in a network cable. The wired network icon (settings) is displayed on the top bar with three dots while the connection is being established. The dots disappear when you are connected.

If this does not happen, you should first of all make sure that your network cable is plugged in. One end of the cable should be plugged into the rectangular Ethernet (network) port on your computer, and the other end should be plugged into a switch, router, network wall socket or similar (depending on the network setup you have). Sometimes, a light beside the Ethernet port will indicate that it is plugged in and active.

If you are still not connected, your network may not support automatic setup (DHCP). In this case you will have to configure it manually. Please consult the appropriate documentation.


2.1.6. Install Node

There are many ways to install node so choose wisely.

Install Node.js using Ubuntu official repository:

>>> sudo apt install nodejs

Install Node.js using NodeSouce repository:

>>> curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash –
>>> sudo apt-get install nodejs

Also you can pick which version you want:

Node.js v12.x:

>>> curl -sL https://deb.nodesource.com/setup_12.x | sudo -E bash -
>>> sudo apt-get install -y nodejs

Node.js v10.x:

>>> curl -sL https://deb.nodesource.com/setup_10.x | sudo -E bash -
>>> sudo apt-get install -y nodejs


It is up to you to decide which version of node you want to use with some Googlefu.

To compile and install native addons from npm you may also need to install build tools:

>>> sudo apt-get install -y build-essential
>>> sudo apt-get install npm
>>> sudo apt-get update
>>> sudo apt-get upgrade

Check with:

>>> node -v
>>> npm -v

2.2. Dependencies

The metawear libraries depend on Noble which has further dependencies.

2.2.1. Install Dev tools

These are nice to have tools as well as the latest bluetooth packages:

>>> sudo apt-get install build-essential
>>> sudo apt-get install bluez
>>> sudo apt-get install libboost-all-dev
>>> sudo apt-get install libbluetooth-dev


>>> sudo apt-get install bluetooth bluez libbluetooth-dev libudev-dev

You may also need:

>>> sudo apt-get install libusb-dev
>>> sudo apt-get install libudev-dev

2.2.2. Install Git

Git is a distributed version-control system for tracking changes in source code during software development. It is designed for coordinating work among programmers, but it can be used to track changes in any set of files.

Git is nice to have if you are going to fork our repository or create your own. You can learn more about it with some Googlefu.

>>> sudo apt-get install git-core

Check that everything works:

>>> git --version

2.3. MetaWear

MetaWear and noble are available on the node package manager. Simply run the command:

>>> npm install metawear

2.3.1. Upgrade MetaWear

To check if any module in a project is ‘old’ run:

>>> npm outdated

‘outdated’ will check every module defined in package.json and see if there is a newer version in the NPM registry.

To update all dependencies, if you are confident this is desirable:

>>> npm update

To update a single dependency such as metawear:

>>> npm update metawear

2.3.2. Check Noble

Our Javascript APIs are built on the Noble Bluetooth libraries (A Node.js BLE central module). They should automatically be installed with the metawear package.

If they are not, simply run:

>>> npm install noble

2.3.3. Download the JS API Code Repository

Head over to our Javascript Github page: https://github.com/mbientlab/MetaWear-SDK-JavaScript

You can clone the repository or simply download as a ZIP file:

>>> git clone --recursive https://github.com/mbientlab/MetaWear-SDK-JavaScript

Then run install:

>>> npm install

This should install all of the dependencies for you. If there are any issues, you can download individual packages (see package.json).

2.3.4. About Javascript APIs

The Javascript APIs are build around the C++ library. There are wrapper functions to tie the C++ to the Python.

When you download our Repository, you will find:

  1. MetaWear-SDK-Cpp -> The C++ metawear library pointer
  2. examples -> This is where we have many Javascript examples for you to look at
  3. lib -> This is where the bindings reside
  4. test -> This is where the tests reside

We also have C++ API documentation here. Please keep this documentation handy.

2.4. Usage

Play with the additional example scripts to get familiar with our JS SDK and don’t forget to refer to our developer documentation.

Simply install the NPM module:

>>> npm install metawear

This will compile our CPP libraries and may take some time.

To use, simply require the metawear package:

var MetaWear = require('metawear');

Discover the first MetaWear device seen:

MetaWear.discover(function (device) { ... }

Or a specific MAC address:

MetaWear.discoverByAddress('cb:7d:c5:b0:20:8f', function(device) { ... }

There are other options too, documented in Noble Device.

After that, you must connect to the device:

device.connectAndSetUp(function (error) { ... }

At this point you can call any of the MetaWear SDK’s, for example, you can blink the LED green:

var pattern = new MetaWear.LedPattern();
MetaWear.mbl_mw_led_load_preset_pattern(pattern.ref(), MetaWear.LedPreset.BLINK);
MetaWear.mbl_mw_led_write_pattern(device.board, pattern.ref(), MetaWear.LedColor.GREEN);

Complete Example:

var MetaWear = require('metawear');

MetaWear.discover(function (device) {
    device.connectAndSetUp(function (error) {
            var pattern = new MetaWear.LedPattern();
            MetaWear.mbl_mw_led_load_preset_pattern(pattern.ref(), MetaWear.LedPreset.BLINK);
            MetaWear.mbl_mw_led_write_pattern(device.board, pattern.ref(), MetaWear.LedColor.GREEN);
            // After 5 seconds we reset the board to clear the LED, when we receive
            // a disconnect notice we know the reset is complete, so exit the program
            setTimeout(function () {
                device.on('disconnect', function () {
            }, 5000);

2.5. First Script

You can now navigate to the examples folder and run any example using the command:

>>> node led.js

Modify the commented out section of the JS file and add the specific MAC address of your MetaSensor.


Run with sudo because of Noble:

>>> sudo node led.js

The LED example will cause the led to blink green a few times. Run the other examples in the examples directory and build on top of them.

If you run into any issues, try:

>>> npm rebuild

2.6. Next Steps

Go over to our Javascript Developers Section to learn more about Javascript development.