Getting Started with Puck.js

Your Puck.js shipped with a battery installed, but with a small plastic tab inserted to keep it turned off.

Turning On

To turn on your Puck.js, simply:

Now to get started!

Once you've your Puck.js is powered up it'll start doing two things:

If you have an NFC phone, make sure NFC is on, and then move Puck.js near the NFC receiver on it. A Web page should open that will direct you to some examples. Otherwise, you can go straight to the Puck.js website -

Note: unfortunately on the default firmware of early Puck.js devices, using NFC causes Puck.js to draw significantly more power than normal until the battery is removed and re-inserted, which can run your battery down very quickly (within a few days). Up to date firmwares for Puck.js have this fixed - but until you update your firmware please be aware that scanning Puck.js with NFC can run down your battery.

Using Puck.js

By default, Puck.js appears as a Bluetooth Low Energy device with a serial port. When you connect to this serial port you get full command-line access to the Espruino Javascript interpreter built into it.

To get started you have two options:


Puck.js uses Bluetooth LE, so 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:

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:

To be sure that you get a usable adaptor we'd recommend that you buy ONLY adaptors that explicitly mention CSR or 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:

Using the Espruino IDE

With Web Bluetooth

If your computer supports it, Web Bluetooth is the easiest way to get started with Puck.js.

You'll need an up to date version of Google Chrome or Opera Web Browsers on one of:

Mac OS

OS X Yosemite or later required, and check that your Mac supports Bluetooth Low Energy:

If it doesn't:


Windows 10 support for Web Bluetooth is under development as of late 2017.

For now there are two options:


Linux is not officially supported in Chrome. However, because ChromeOS is supported it can be possible to enable Linux support:

BlueZ 5.41+ required - you can check by typing bluetoothd --version. If it isn't there are some Bluez installation instructions here


All Chromebooks with Bluetooth should support Web Bluetooth.


Android 6 (Marshmallow) or later supported.

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

However once that is done you'll be able to access Web Bluetooth through any webpage viewed with WebBLE

Once Web Bluetooth is set up:

Web Bluetooth setting

Web Bluetooth device chooser

With an application

On some platforms (Windows, or Linux with older versions of Bluez) Web 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


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 on your Puck.js!

Via a Raspberry Pi

There are two ways of using the Raspberry Pi to control Puck.js devices.

Once set up, you can try writing some code on your Puck.js!

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! You can buy a USB-TTL converter, and can connect directly to your Puck.js.

You can then use the normal Espruino Web IDE.


You can use the Espruino command-line app. It works under Node.js, so you'll need to:

Sending Individual Commands

Using Adafruit 'Bluefruit LE' app

This is the easiest solution on iOS

nRF UART app

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).

A Website

You can use Web Bluetooth on your own website to control Puck.js 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=""></script> in your website (served off HTTPS) and you can easily execute commands just by running JS code like:


We've got a proper tutorial on it here

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 Puck.js bluetooth device and connect to the characteristic with ID 6e400002b5a3f393e0a9e50e24dcca9e. You can then write repeatedly to it to send commands to Espruino.


Type in LED1.set() and click send.

New Firmware

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

Having Trouble?

Check out the Troubleshooting page, or ask on our forums

What now?

If you're using any version of the Web IDE, you can click on the Book icon in the top right, then:

Web Bluetooth setting

Or you can follow the Quick Start guide for normal Espruino Boards.

You can check out some of the Puck.js tutorials:

However there's also much more detailed information:

Note: Espruino runs on many other devices, and caters for all of them. Unless a tutorial explicitly says it is for Puck.js it's possible that you will have to change some pin names and wiring to match the pins on the Puck.js.

Power Usage

When idle (as it comes after the battery is plugged in) Puck.js draws around 20uA, allowing it to run for around a year on a battery. When it's running a small amount of JavaScript code once a minute or when a button is pressed that figure won't be a great deal higher.

However, it's very easy to draw more power:

As a result, if you've been using Puck.js but don't intend to use the code you've uploaded it's recommended that you either unplug the battery, or connect to the Puck.js and type reset(), to ensure that no code is running in the background that might flatten the battery.

For more details on power usage, see here

This page is auto-generated from GitHub. If you see any mistakes or have suggestions, please let us know.