Introduction to JavaScript for Pebble Time Smart-Watch

Introduction to JavaScript for Pebble Time Smart-Watch

PebbleJS

During this tutorial, I will explain some of the basics to start programming with PebbleJS. I will use images to illustrate the concepts we will find step-by-step. Advance documentation can be found on the Pebble site.

Table of Contents

Setting up everything

  • If you are a Windows user, I recommend to use a virtual machine with Ubuntu.
  • Create a developer account on their website.
  • Follow the installation instructions for for Linux or Mac.
  • Fork or download the PebbleJS project on the development folder you are going to work with for your new project.

Once everything is set up, go to the root path of your project and use the following commands:

pebble clean
pebble build
pebble install --emulator basalt

To interact with the buttons on the emulator use the keyboard arrows.

Pebble Button Schema

At this moment, the application should show an initial example from the main developer. If the emulator doesn’t work, or it does not build correctly, revise the previous chapter before continuing.

Card, Menu and Window

The user interacts with different kinds of screens on its Pebble. Usually, when the user clicks on Select, it opens a new screen with different information. When the user clicks on Back, it goes back to the previous opened screen.

We can find some different Window on the SDK already:

  • Window: A blank screen where we can add anything at any valid coordinate
  • Card: An already prepared Window that contains a title, subtitle and body. Furthermore we can add icons
  • Menu: A menu we can scroll that also shows different items with a title, subtitle and icon

Pebble Window Types

In order to show any window, we need to invoke the method show().

var UI = require('ui');
var wind = new UI.Window({});
wind.show();

All Window has some common attributes.

Common Window Attributes

  • backgroundColor: Changes the background color. Possible colors can be found on this website
  • scrollable: it is used if the content of the screen is long. We use the up and down buttons to navigate on the screen. Cannot be used on the Menu Window
  • fullscreen: Used to hide or show the top toolbar which indicates the time on the watch
var UI = require('ui');
var wind = new UI.Window({
  fullscreen: false,
  scrollable: true,
  backgroundColor: 'yellow'
  });
wind.show();

Button events

Each Window can intercept events when the user presses any button. The possible buttons are back, up, down and select. They can be intercepted using the following code:

var UI = require('ui');
var wind = new UI.Window({});

wind.on('click', 'back', function(e) { /* Click BACK */ });
wind.on('click', 'up', function(e) { /* Click UP*/ });
wind.on('click', 'down', function(e) { /* Click DOWN */ });
wind.on('click', 'select', function(e) { /* Click SELECT */ });

wind.show();

Cards

Card Common Attributes

  • title: Shows a title at the top of the screen
  • icon: Shows an icon at the left of the title
  • subtitle: Shows a subtitle after the title with smaller font
  • subicon: Shows an icon at the left of the subtitle
  • body: Long text to display
  • banner: Big icon before the body
var UI = require('ui');
var card = new UI.Card({
  fullscreen: true,
  scrollable: true,
  title: 'Title',
  icon: 'images/one.png',  
  subtitle: 'Subtitle',
  subicon: 'images/two.png',
  body: 'Lorem ipsum dolor sit amet, consectetur adipiscing elit. Donec a diam lectus. Sed sit amet ipsum mauris. Maecenas congue ligula ac quam viverra nec consectetur ante hendrerit. Donec et mollis dolor. Praesent et diam eget libero egestas mattis sit amet vitae augue.',
  banner: 'images/watch.png',
  backgroundColor: 'yellow'
});

card.show();

If we use scrollable, the text of our body will not be cut on the screen and we will be able to read it all using the up and down buttons.

NOTE: Read the section Adding images to add an image to the project.

Menu Common Attributes

  • backgroundColor: Changes the background color
  • textColor: Changes the text color
  • highlightBackgroundColor: Changes the background color of highlight items
  • highlightTextColor: Changes the text color of highlight items
  • sections: Array with menu sections

    • title: Title of the section
    • items: Items of the section

      • title: Title of the item
      • description: Description of the item
      • icon: Icon of the item
var UI = require('ui');
var menu = new UI.Menu({
  fullscreen: true,
  backgroundColor: 'yellow',
  textColor: 'blue',
  highlightBackgroundColor: 'blue',
  highlightTextColor: 'white',
  sections: [{
    title: 'Shows',
    items: [{
      title: 'Mr. Robot',
      subtitle: 'Follows a young computer programmer who suffers from social anxiety disorder and forms connections through hacking. He is recruited by a mysterious anarchist, who calls himself Mr. Robot.',
      icon: 'images/tv.png'
    }, {
      title: 'Rick and Morty',
      subtitle: 'An animated series that follows the exploits of a super scientist and his not so bright grandson.',
      icon: 'images/tv.png'
    }]    
  },
  {
    title: 'Movies',
    items: [{
      title: 'Blade Runner',
      subtitle: 'A blade runner must pursue and try to terminate four replicants who stole a ship in space and have returned to Earth to find their creator.',
      icon: 'images/tv.png'
    },
    {
      title: 'Alien',
      subtitle: 'The commercial vessel Nostromo receives a distress call from an unexplored planet. After searching for survivors, the crew heads home only to realize that a deadly bioform has joined them.',
      icon: 'images/tv.png'
    }]
  }]
});

menu.show();

In order to intercept which item has been selected, we can attach the event select to the menu. When the user clicks in the select button, the function will be triggered and we will have the control over the item. We can access to the item using e.item (in case we named e to the first argument).

menu.on('select', function(e) {
  console.log('Selected item #' + e.itemIndex + ' of section #' + e.sectionIndex);
  console.log('The item is titled "' + e.item.title + '"');
});

Actions bar

The SDK give us the possibility to create an Action bar with 3 icons. We can attach it to any Window, but we should not attach it to the Menu Window because the buttons are used to scroll and select the items. Neither when the scrollable attribute is true.

Common Actions Attributes

  • backgroundColor: Background color of the Actions bar
  • up: Icon for the top action menu
  • down: Icon for the down action menu
  • select: Icon for the select action menu

On the chapter Button events we can see an example of how to intercept the clicks for those buttons.

NOTE: Read the section Adding images to add an image to the project.

Ajax Calls

Ajax calls with PebbleJS are straightforward. The smart-watch does not connect directly to the Internet, but it does through the mobile proxy. For us, this is totally transparent using the SDK.

var ajax = require('ajax');

ajax(
  {
    url: 'http://jsonplaceholder.typicode.com/posts',
    method: 'get', /* Can use get, post, delete, put and options */
    type: 'json',
    headers: { 'User-Agent': 'From eridem.net' }, /* Specify special headers */
    async: true, /* Set to false for a blocking call */
    cache: true,
    data: {}, /* Used to attach a payload */
  },
  function(data, status, request) {
    /* reply data inside data argument */
  },
  function(error, status, request) {
    /* error contains the error message */
  }
);

Extra: Adding images

Adding images in PNG format requires two steps:

  • Add the image to the /resources/images/ folder on the project.
  • Add an entry on the /appinfo.json under the section resources/media. E.g:
{
  "type": "png",
  "name": "IMAGE_NAME",
  "file": "images/your_added_image.png"
}

When we use it on our application, we need to do a reference using the file name. E.g.

  images/your_added_image.png

Conclusion

As we saw on this tutorial, when using the PebbleJS SDK and with knowledge of Javascript, we can start creating amazing applications. Of course, the complete documentation describe other menu features, such as accelerometer, add texts and shapes to a Window, vibrations, wake ups and more.