Bangle.js Development

You may also be interested in the Bangle.js 1 or Bangle.js 2 Hardware reference pages.

Don't have a watch?

You can work along using the Bangle.js online Emulator however you won't get access to the sensors, Bluetooth, or vibration motor!

If your watch isn't connectable by Bluetooth:

Bangle.js 1

When you're at the clock screen on Bangle.js, press the middle button (BTN2)
Use the bottom button (BTN3) to scroll down until you get to Settings
Press BTN2 to select
Either: Ensure BLE and Programmable are On to enable programming permanently, and then choose Back to exit settings
Or: Scroll down to Make Connectable, select it, and leave Bangle.js displaying on the Connectable screen

Bangle.js 2

When you're at the clock screen on Bangle.js, press the button
Scroll down until you get to Settings and then tap on it
Now you can drag your finger up and down to scroll, and then tap to select the Bluetooth menu item.
Either: Ensure BLE and Programmable are checked to enable programming permanently, and press the button repeatedly exit settings
Or: Tap Make Connectable, and leave Bangle.js displaying on the Connectable screen

Then...

Head to https://espruino.com/ide in Chrome
Click Connect up the top left of the screen
Click Web Bluetooth (if you don't see 'Web Bluetooth' check out the Bluetooth Getting Started Guide)
Search for your Bangle.js in the list of devices. Devices will be called Bangle.js abcd in the connection menu, and the code abcd is displayed (by default) in the top right of your Bangle.js's widget bar.

You should hopefully be connected now! If not, take a look at http://www.espruino.com/Quick+Start+BLE#banglejs

If you just want to get started and have an Android phone, you can use that too! If you don't have an external keyboard then you might want to install the free 'Hackers Keyboard' app to get access to arrow keys via touchscreen.

Note: If you've used Espruino before, make sure the Upload button (middle of the screen) shows RAM underneath it. Otherwise by writing to Flash you can remove the watch's built-in menu (you can just re-add it by removing and installing bootloader using https://banglejs.com/apps)

Once connected

The Web IDE is made up out of two parts - there's the black REPL on the left, and a white editor on the right.

The REPL on the left is a direct connection to the watch and executes anything you type immediately - but be careful, it uses bracket counting to detect when to execute, so:

if (true) {
  Bangle.buzz();
}

will make your watch vibrate, but:

if (true)
  Bangle.
    buzz();

With Enter rather than Alt-Enter will run three commands, the last two of which will cause an error. If you write your code in a K&R style (with the opening brackets at the end of a line rather than on their own line) then you're unlikely to hit issues - and if you write your code on the right hand side of the IDE, the line endings are handled automatically.

When writing on the right, you can click the button in the middle of the IDE to reset Bangle.js (temporarily!) and upload the code on the right hand side.

You can now try some commands:

First, let's (temporarily) reset the watch and get rid of the connectable window (if you'd had to choose Make Connectable initially)...

Type:

reset();

on the left-hand side of the IDE. The Bangle.js logo will be displayed.

Bangle.buzz();

Note: Bangle.js 2 devices do not contain a speaker, but instead use the vibration motor for sound (which is very quiet). So Bangle.beep(); will beep, but extremely quietly.

You'll notice the functions return promises, so you can chain them:

Bangle.buzz().then(() => {
  console.log("Done!");
});

You might want to clear the screen, in which case you can use g.clear(). A full list of Graphics commands is at: https://espruino.com/Reference#Graphics

If you want to write a message on the screen, you can use E.showMessage:

E.showMessage("Hello","A Title")

In general, Bangle.js specific functions/events are in the Bangle object, and Espruino-specific functions are in the E object

The screen itself contains a VT100 terminal, so you can use Terminal.print and Terminal.println if you just want to log data:

Terminal.println("Hello World")

But these will scroll the screen up, which may make currently running apps look a bit strange!

It's worth noting that when you're disconnected from Bluetooth, Bangle.js will write any messages from console.log (as well as any Exceptions) to the display only if Debug info is set to Show in Settings. This can be a great way of seeing if your app is failing in unexpected ways when in every day use.

Want to react to user input on the buttons? You can query the button state.

Bangle.js 1 - BTN1/BTN is the top button, BTN2 is the middle, BTN3 is the bottom
Bangle.js 2 - BTN1 or BTN refers to the single button on the side

BTN1.read();

Will output true or false depending on the state of the button, but usually we don't want to poll because running code all the time would use battery.

On Espruino devices you can use the setWatch function. This sets up the hardware to watch for a button press, and calls a function when it is pressed:

setWatch(() => {
  E.showMessage("You\npressed\nthe button!");
  setTimeout(()=>g.clear(), 1000);
}, BTN1, {repeat:true, edge:"falling"});

This code does work on Bangle.js, but isn't recommended. As you start to do more with your Bangle, showing menus and responding to touchscreen events, it can be hard to keep track of setWatch and other events and disable them when they're not needed. It's also more tricky to account for hardware differences between devices (Bangle.js 1 has 3 buttons with the middle being BTN2, and Bangle.js 2 has just one button, called BTN/BTN1).

To work around this, Bangle.js provides the Bangle.setUI method, which keeps track of your event handlers and disables all the 'old' ones the next time it is called.

The equivalent of the above would be:

function waitForButton() {
  g.clear();
  Bangle.setUI({
    mode : "custom",
    btn : ()=>{
      Bangle.setUI(); // remove old handler
      E.showMessage("You\npressed\nthe button!");
      setTimeout(waitForButton, 1000);
    }
  });
}
waitForButton();

This is a bit longer, but it is easily extendable to add other handlers, for instance for touch events.

At this point the code's getting longer, so you might want to copy this to the right-hand side of the IDE and then use the Upload button...

Using the Right-hand side of the IDE

The right-hand side of the IDE is a syntax-highlighted editor with code completion (press Ctrl-Space for suggestions). To send the code you have written in the editor on the right to Bangle.js you must click the upload button:

This preprocesses the code you wrote, loading any modules you included with require(...), and the uploads it to Bangle.js. The destination is written underneath, and can be changed either by pressing the down arrow, or by going to Settings and Communications:

RAM - you should normally try and use this - it writes nothing permanently to Bangle.js so is quick and safe to develop with.
Flash - DO NOT USE THIS ON BANGLE.JS because you will overwrite the existing Bangle.js bootloader with your own app (if you do, you can re-install the bootloader app using https://banglejs.com/apps).
Storage - you can use this to select a file on Storage to write to. This is great for developing your own apps - see Bangle.js: First Application