Quick Start (Bluetooth LE)
- KEYWORDS: Tutorials,Puck.js,Quick Start,Getting Started,Web Bluetooth,BLE
- USES: Puck.js,Pixl.js,MDBT42Q,Ruuvitag,Thingy52,Web Bluetooth,BLE,Only BLE
Your Puck.js shipped with a battery installed, but with a small plastic tab inserted to keep it turned off.
To turn on your Puck.js, simply:
- Remove Puck.js from its packaging
- Peel the silicone case away from the hard base using your fingers
- Tip the Puck.js circuit board out of the case
- Remove the battery by poking it out from the rear with a blunt object
- Remove the clear plastic tab that was under the battery
- Re-insert the battery - the red LED should flash once, very briefly.
- If the green LED lights or red stays lit, it is because you have accidentally pressed the button down while inserting the battery. Remove the battery and try again, making sure the button next to the battery connector isn't pressed.
- Re-assemble Puck.js. To make sure the button works correctly you need to put
the battery side facing towards the plastic case, with the
Puck.js ...text against the shelf in the case itself
While Puck.js ships with firmware that's fine for simple tasks, we're constantly improving the software and adding new features.
To get the best out of it, we'd recommend that you update Puck.js's firmware first.
To turn on your Pixl.js you have three main options:
- Use a Micro USB cable for power (there is no USB data connection on Pixl.js)
- Slide a CR2032 battery into the holder on the board (with
+facing away from the PCB)
- Connect a power source (under 16v) between the
GNDpins on Pixl.js
While Pixl.js ships with firmware that's fine for simple tasks, we're constantly improving the software and adding new features.
To get the best out of it, we'd recommend that you update Pixl.js's firmware first.
Check out the MDBT42Q page for more information about powering the MDBT42Q.
While pre-programmed MDBT42Q modules from us ship with firmware that's fine for simple tasks, we're constantly improving the software and adding new features.
To get the best out of it, we'd recommend that you update the firmware first.
Check out Ruuvi's getting started page for more information about powering MDBT42Q.
You'll need to have your Thingy:52 flashed with Espruino and powered on. Check out the Thingy:52 page for more information.
Simply plug your nRF52832DK into a USB connector. You need to have it flashed with Espruino.
Once your device is powered up it'll start advertising itself via Bluetooth Low Energy.
For Bluetooth LE you need a Bluetooth 4.0-capable adaptor in your computer (Bluetooth versions before 4.0 won't work). Pretty much all new computers come with Bluetooth 4, but you may need to get an external Bluetooth LE dongle if your computer:
- Is an Apple Mac made before 2012
- Is a Windows PC with a Windows version before 10
- Is a Desktop PC - it may not have any wireless support at all
- Is running Linux - much of the built-in Bluetooth LE functionality in laptops is still buggy. External USB adaptors will be much more reliable.
If your computer doesn't have Bluetooth LE then Bluetooth LE USB adaptors and small, cheap (~$10), and easily available. There are two main types of USB Bluetooth Adaptor available:
- Broadcom chipset (eg. BCM20702) works well on all platforms.
- Cambridge Silicon Radio (CSR) - these work great on Linux and Windows. However while they used to work on Macs, Apple removed support in the High Sierra OS update - so you're better off with a Broadcom module.
To be sure that you get a usable adaptor we'd recommend that you buy ONLY adaptors that explicitly mention
Broadcom in the descriptuon. The BlueGiga BLED112 module WILL NOT WORK - it is a serial port device, not a general purpose Bluetooth adaptor.
Common USB Bluetooth adaptors that have been tested and work are:
- iAmotus UD-400M - Broadcom BCM20702A1
- Plugable USB-BT4LE - Broadcom BCM20702A1
- Whitelabel 06Q Nano - CSR chipset
- Whitelabel BM35 - CSR chipset
- Unbranded 'CSR 4.0' - CSR Chipset
Using your Espruino device
Note: Bluetooth LE serial ports (known as 'Nordic UART') will not appear in your Operating System's list of serial devices.
To get started you have two options:
- Use the Espruino IDE or command-line tools to write code to Espruino
Using the Espruino IDE
<script></script> With Web Bluetooth
If your computer supports it, Web Bluetooth is the easiest way to get started with Espruino.
You'll need an up to date version of Google Chrome or Opera Web Browsers on one of:
OS X Yosemite or later required, and check that your Mac supports Bluetooth Low Energy:
- Click the Apple logo then
About this Macin the top left
- See if it says
Bluetooth Low Energy Supported
If it doesn't:
- Get a Bluetooth 4.0 (or later) adaptor (they cost ~$10) - see the requirements section above.
- Open a terminal and type
sudo nvram bluetoothHostControllerSwitchBehavior=always(to go back to the old behaviour type
sudo nvram -d bluetoothHostControllerSwitchBehavior)
- Reboot your Mac
- Make sure that you turn off (or un-pair) any Bluetooth devices that were using your internal Bluetooth - they may stop your Mac from using the new adaptor
Windows 10 fully supports Web Bluetooth, as long as you have an up to date version of Google Chrome (v70 or above) and your PC has a Bluetooth LE radio (all new Laptops will).
If you do not have Windows 10, you need to install the Espruino Native IDE application instead, as this is able to access the Bluetooth adaptor directly.
Linux is not officially supported in Chrome. However, because ChromeOS is supported it can be possible to enable Linux support:
BlueZ 5.41+ required (5.43 is more stable) - you can check by typing
bluetoothd --version. If it isn't there are some [Bluez installation instructions here](/Web Bluetooth On Linux)
chrome://flagsin the address bar
- You need to enable
Experimental Web Platform Features(
- Restart your browser
All Chromebooks with Bluetooth should support Web Bluetooth.
Android 6 (Marshmallow) or later are supported out of the box.
Android 5 (Lollipop) devices can use Chromium installed over ADB to a developer mode device.
iOS (iPhone, iPad)
Apple's built-in web browser does not support Web Bluetooth. Instead you'll need to install the WebBLE app
Once that is done you'll be able to access Web Bluetooth through any webpage viewed with WebBLE
Once Web Bluetooth is set up:
- Go to the Puck.js site. It should tell you that you have Web Bluetooth.
- Click the Web IDE option.
- Click the orange Connect/Disconnect icon in the Top Left: ![Connect icon](Quick Start BLE/connect.png)
- You may see a list of connection options - choose
![Web Bluetooth setting](Quick Start BLE/connect2.png)
- You should be shown a list of devices - click on
ABCDis the last 4 digits of your device's MAC address)
![Web Bluetooth device chooser](Quick Start BLE/connect3.png)
- Wait a few seconds - you should now be connected!
- You can now try writing some code!
With an application
On some platforms (Windows, or Linux with older versions of
Bluetooth isn't supported yet.
On these you'll need to install a native application. We've created a Web IDE installer for Windows - don't use the Chrome Web Store version at the top of that page, as it won't give you access to Bluetooth devices.
Once installed, you need to run
Espruino IDE - which is confusingly
similar to the
Espruino Web IDE which you may have had installed if you'd
used normal Espruino USB devices before.
![IDE Icon on Windows](Quick Start BLE/webidewindows.png)
- Bluetooth LE Serial devices (Nordic UART Service) like Espruino are not treated as serial port devices by Windows. If the IDE's connection menu shows devices beginning with the word
COM5), they are not your device and connecting to them won't work.
- If using Windows 8.1/10 or later you'll need to pair your Espruino device using the Windows Bluetooth menu before it'll appear in the Web IDE. This is not needed for Web Bluetooth devices
- If you're using a Bluetooth dongle with Windows 10 you should use Windows' built-in Bluetooth software, rather than installing the software that came with your Bluetooth Dongle. Often the Bluetooth dongle's software will not pair with Bluetooth LE devices and expose them via Windows 10's API.
- If using Windows 7 you'll need to have set up your Bluetooth adaptor with Zadig first
On Linux, Mac OS and other platforms you'll need to follow the NPM install instructions on the Web IDE GitHub Page
Once set up, you can try writing some code!
Via a Raspberry Pi
There are two ways of using the Raspberry Pi to control Espruino devices.
You can use the Espruino Hub software (which provides an MQTT bridge) and the Node-RED UI - see the [Node RED Tutorial](/Puck.js Node-RED)
Or you can [use the Raspberry Pi to host a web-based version of the Web IDE](/Raspberry Pi Web IDE).
Once set up, you can try writing some code!
By wired connection
In the worst case, you don't have any computers that allow you to communicate using Bluetooth Low Energy.
But all is not lost! With many devices you can connect directly using a USB-TTL converter:
- Connecting Serial to Puck.js
- Connecting Serial to Pixl.js
- Connecting Serial to to the MDBT42Q
- Connecting Serial to to the Thingy:52
- The nRF52832DK has USB serial built-in
You can use the Espruino command-line app. It works under Node.js, so you'll need to:
- Install Node
- In a command prompt, type
npm install -g espruino(on Linux you'll want to use
sudobefore the command)
- On Linux, you need to run
sudo setcap cap_net_raw+eip $(eval readlink -f `which node`)to give node permissions for BLE (or you'll have to run it as
- When that completes, you can type
espruino --helpfor help
- To connect, try
espruino --listto list devices, then copy your device's MAC address and type
espruino -p aa:bb:cc:dd:eeto connect.
Ctrl-Ctwice to exit.
- You can also type
espruino -p aa:bb:cc:dd:ee -w filename.jsto upload a file, enter terminal mode, and then re-upload it if it changes (so you can use your favourite editor)
- You can now start writing some code!
Sending Individual Commands
Using Adafruit 'Bluefruit LE' app
This is the easiest solution on iOS
- Start the app
- Choose the Espruino device you want to communicate with and click
- When connected you're ready to enter some commands - see
nRF UART app
- Start the app
Connectand choose your Espruino device
- Type commands into the console - see
Note: In this app, you need to manually press the
Enter key before sending a line. If you're on iOS you need to do this by copy/pasting out of code in notepad - which is much trickier (the Adafruit app above is easier).
You can use Web Bluetooth on your own website to control Espruino BLE devices, as long as you have a compatible browser.
While you can use Web Bluetooth directly, we've provided a helpful library. Just include
<script src="https://puck-js.com/puck.js"></script> in your website (served off
and you can easily execute commands just by running JS code like:
We've got [a proper tutorial on it here](/Puck.js Web Bluetooth)
Your own app
You can make your own application to control Espruino for whatever platform you need.
For the simplest control, all you need to do is connect to the Espruino bluetooth
device and the characteristic with ID
You can then write repeatedly to it to send commands to Espruino.
LED1.set() and click send.
- The red LED should light up.
- You can now type
LED1.reset()to turn it off.
- Note that responses are also being sent back. You can type in
falsewill be returned - it'll be
trueif the button is pressed
- The Bluetooth Troubleshooting page
- General Troubleshooting
- Or ask on our forums if you can't find the answer you need
Please try the walkthrough to get started writing your first code for Espruino
There's lots of detailed information on specific boards, as well as a list of tutorials for them:
There is more general information:
- Bluetooth Troubleshooting
- Language Reference, specifically:
- Instantly Search all the Espruino website's documentation (using the box in the top right)
- List of available modules
- Frequently Asked Questions
- See other ways of Programming Espruino devices
- Or check out our forums
Note: Espruino runs on many other devices, and espruino.com caters for all of them. Unless a tutorial explicitly says it is for your device it's possible that you will have to change some pin names and wiring to match the pins that you used on your device.
However, it's very easy to draw more power:
- Staying connected via Bluetooth will often draw around 10x more power than idle
- Lighting a LED can draw around 100x more power than when idle
As a result, if you've been using your device but don't intend to use the code
you've uploaded it's recommended that you either remove the battery, or connect
to your device and type
reset(), to ensure that no code is running in the
background that might flatten the battery.