EspruinoHub

A BLE -> MQTT bridge for Raspberry Pi and other Embedded devices for Espruino and Puck.js

Setting up

Ideally use a Raspberry Pi 3 or Zero W, as these have Bluetooth LE on them already. However the BLE USB dongles mentioned in the Puck.js Quick Start guide should work.

Get Raspbian running on your Raspberry Pi

• Download Raspbian Lite from https://www.raspberrypi.org/downloads/raspbian/
• Copy it to an SD card with sudo dd if=2017-11-29-raspbian-stretch-lite.img of=/dev/sdc status=progress bs=1M on Linux (or see the instructions on the Raspbian download page above for your platform)
• Unplug and re-plug the SD card and add a file called ssh to the boot drive - this will enable SSH access to the Pi
• If you're using WiFi rather than Ethernet, see this post on setting up WiFi via the SD card
• Now put the SD card in the Pi, apply power, and wait a minute
• ssh pi@raspberrypi.local (or use PuTTY on Windows) and use the password raspberry
• Run sudo raspi-config and set the Pi up as you want (eg. hostname, password)

Installation of everything (EspruinoHub, Node-RED, Web IDE)

These instructions install up to date Node.js and Node-RED - however it can take a while! If you just want EspruinoHub and the IDE, see the next item.

sudo apt-get update
# OPTIONAL: Update everything to latest versions
sudo apt-get upgrade -y
# Get required packages
sudo apt-get install -y build-essential python-rpi.gpio nodejs nodered git-core
# OPTIONAL: Install a modern version of nodejs and nodered
# Not recommended - The Pi's supplied Node.js version is more than good enough
# bash <(curl -sL https://raw.githubusercontent.com/node-red/raspbian-deb-package/master/resources/update-nodejs-and-nodered)
# Get dependencies
sudo apt-get install -y mosquitto mosquitto-clients bluetooth bluez libbluetooth-dev libudev-dev
# Auto start Node-RED
sudo systemctl enable nodered.service
# Start nodered manually this one time (this creates ~/.node-red)
sudo systemctl start nodered.service
# wait for the ~/.node-red directory to get created...
# Install the Node-RED UI
cd ~/.node-red && npm install node-red-contrib-ui
# Now get EspruinoHub
cd ~/
git clone https://github.com/espruino/EspruinoHub
# Install EspruinoHub's required Node libraries
cd EspruinoHub
npm install

# Give Node.js access to Bluetooth
sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)

# You may need to run the setcap line above again if you update Node.js

You can now type ./start.sh to run EspruinoHub, but it's worth checking out the Auto Start section to see how to get it to run at boot.

Installation of EspruinoHub and Web IDE

# Install Node, Bluetooth, etc
sudo apt-get update
# OPTIONAL: Update everything to latest versions
sudo apt-get upgrade -y
# Get required packages
sudo apt-get install -y git-core nodejs npm build-essential mosquitto mosquitto-clients bluetooth bluez libbluetooth-dev libudev-dev
# Now get EspruinoHub
git clone https://github.com/espruino/EspruinoHub
# Install EspruinoHub's required Node libraries
cd EspruinoHub
npm install

# Give Node.js access to Bluetooth
sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)

# You may need to run the setcap line above again if you update Node.js

You can now type ./start.sh to run EspruinoHub, but it's worth checking out the Auto Start section to see how to get it to run at boot.

Auto Start

There are a 2 main ways to run EspruinoHub on the Raspberry Pi.

Headless Startup

This is the normal way of running services - to configure them as a system start-up job using systemd:**

    sudo cp systemd-EspruinoHub.service /etc/systemd/system/EspruinoHub.service

and edit it as necessary to match your installation directory and user configuration. Then, to start it for testing:

    sudo systemctl start EspruinoHub.service && sudo journalctl -f -u EspruinoHub

If it works, Ctrl-C to break out and enable it to start on login:

    sudo systemctl enable EspruinoHub.service

Console Startup

If you have a video output on your Pi then you can run EspruinoHub at boot - on the main display - so that you can see what it's reporting.

• Edit .bashrc and add the following right at the bottom:

if [ $(tty) == /dev/tty1 ]; then
  while true; do
    EspruinoHub/start.sh
    sleep 1s
  done
fi

• Now run sudo raspi-config, choose Boot Options, Desktop / CLI, and Console Autologin

• Next time you reboot, the console will automatically run EspruinoHub

Notes

• On non-Raspberry Pi devices, Mosquitto (the MQTT server) may default to not allowing anonymous (un-authenticated) connections to MQTT. To fix this edit /etc/mosquitto/conf.d/local.conf and set allow_anonymous to true.
• By default the HTTP server in EspruinoHub is enabled, however it can be disabled by setting http_port to 0 in config.json
• The HTTP Proxy service is disabled by default and needs some configuration - see HTTP Proxy below
• You used to need a local copy of the Espruino Web IDE, however now EspruinoHub just serves up an IFRAME which points to the online IDE, ensuring it is always up to date.

Uninstalling

Assuming you followed the steps above (including for 'Headless Startup') you can uninstall EspruinoHub using the following commands:

sudo systemctl stop EspruinoHub.service
sudo systemctl disable EspruinoHub.service
sudo rm /etc/systemd/system/EspruinoHub.service
sudo rm -rf ~/EspruinoHub

Run with Docker

More information how work Bluetooth in docker you can read in article "How to run containerized Bluetooth applications with BlueZ" by Thomas Huffert

Currently, espruinohub has support for multiple architectures:

• amd64 : based on linux Alpine - for most desktop computer (e.g. x64, x86-64, x86_64)
• arm32v6 : based on linux Alpine - (i.e. Raspberry Pi 1 & Zero)
• arm32v7 : based on linux Alpine - (i.e. Raspberry Pi 2, 3, 4)
• arm64v8 : based on linux Alpine - (i.e. Pine64)

Install:

docker pull ghcr.io/espruino/espruinohub

Run from the directory containing your config.json:

docker run -d -v $PWD/config.json:/data/config.json:ro --restart=always --net=host --privileged --name espruinohub ghcr.io/espruino/espruinohub

Example for docker-compose.yml

  espruinohub:
    image: ghcr.io/espruino/espruinohub
    hostname: espruinohub
    container_name: espruinohub
    privileged: true
    environment:
      - TZ=Europe/Amsterdam
      - NOBLE_HCI_DEVICE_ID=0
    network_mode: host
    volumes:
      - /home/twocolors/espruinohub:/data
    restart: unless-stopped

Manual build:

docker build -t espruino/espruinohub https://github.com/espruino/EspruinoHub.git

Usage

Once started, you then have a few options...

Status / Websocket MQTT / Espruino Web IDE

By default EspruinoHub starts a web server at http://localhost:1888 that serves the contents of the www folder. You can disable this by setting http_port to 0 in config.json.

With that server, you can:

• See the Intro page
• See the status and log messages at http://localhost:1888/status
• Access the Espruino Web IDE at http://localhost:1888/ide. You can then connect to any Bluetooth LE device within range of EspruinoHub.
• View real-time Signal Strength data via WebSockets at http://localhost:1888/rssi.html
• View real-time MQTT data via WebSockets at http://localhost:1888/mqtt.html
• View any of your own pages that are written into the www folder. For instance you could use TinyDash with the code from www/mqtt.html to display the latest BLE data that you have received.

MQTT / Node-RED

If set up, you can access Node-RED using http://localhost:1880

Once you add UI elements and click Deploy they'll be visible at http://localhost:1880/ui

The easiest way to get data is to add an MQTT listener node that requests /ble/advertise/# (# is a wildcard). This will output all information received via advertising (see 'Advertising Data' below).

For more info on available MQTT commands see the 'MQTT Bridge' section below.

Check out http://www.espruino.com/Puck.js+Node-RED for a proper introduction on using Node-RED.

MQTT Command-line

You can use the Mosquitto command-line tools to send and receive MQTT data that will make EspruinoHub do things:

# listen to all, verbose
mosquitto_sub -h localhost -t "/#" -v

# listen to any device advertising a 1809 temperature characteristic and
# output *just* the temperature
mosquitto_sub -h localhost -t "/ble/advertise/+/temp"

# Test publish
mosquitto_pub -h localhost -t test/topic -m "Hello world"

For more info on available MQTT commands see the 'MQTT Bridge' section below.

MQTT bridge

Advertising

Data that is received via bluetooth advertising will be relayed over MQTT in the following format:

• /ble/presence/DEVICE - 1 or 0 depending on whether device has been seen or not
• /ble/advertise/DEVICE - JSON for device's broadcast name, rssi and manufacturer-specific data (if mqtt_advertise=true in config.json - the default)
• /ble/advertise/DEVICE/manufacturer/COMPANY - Manufacturer-specific data (without leading company code) encoded in base16. To decode use var data = Buffer.from(msg.payload, 'hex'); (if mqtt_advertise_manufacturer_data=true in config.json - the default)
• /ble/advertise/DEVICE/rssi - Device signal strength
• /ble/advertise/DEVICE/SERVICE - Raw service data (as a JSON Array of bytes) (if mqtt_advertise_service_data=true in config.json