pebble/devsite/source/_posts/2016-08-15-introducing-rockyjs-watchfaces.md

title	author	tags
Introducing Rocky.js Watchfaces!	jonb	Freshly Baked

We're incredibly excited and proud to announce the first public beta version of Rocky.js watchfaces for Pebble. Rocky.js is ECMAScript 5.1 JavaScript running natively on Pebble smartwatches, thanks to our collaboration with JerryScript. This is an incredible feat of engineering!

It's JavaScript on the freakin' watch!

var rocky = require('rocky');

rocky.on('minutechange', function(event) {
  rocky.requestDraw();
});

rocky.on('draw', function(event) {
  var ctx = event.context;
  ctx.clearRect(0, 0, ctx.canvas.clientWidth, ctx.canvas.clientHeight);
  ctx.fillStyle = 'white';
  ctx.textAlign = 'center';

  var w = ctx.canvas.unobstructedWidth;
  var h = ctx.canvas.unobstructedHeight;
  ctx.fillText('JavaScript\non the watch!', w / 2, h / 2);
});

Right now we're giving you early access to this game-changing environment to create watchfaces entirely in JavaScript. Feel free to share your code, to install it on the emulator and on your watch (with the upcoming firmware 4.0), but please don't upload apps to the appstore as they will stop working in a future release.

{% markdown %} **Appstore Publishing**

Rocky.js JavaScript watchfaces must not be published into the appstore at this time. {% endmarkdown %}

We can't wait to hear your feedback and see what amazing watchfaces you create!

Enough hype, let's dive into the eye of the tiger!

Rocky.js Projects

Things are a little different in the JavaScript world, so let's take a closer look at the structure of a Rocky.js project:

package.json
src/rocky/index.js
src/pkjs/index.js
common/*.js

package.json

The format of the package.json file remains roughly the same as existing Pebble projects, with some minor differences:

• "projectType": "rocky".
• Aplite targetPlatform is not supported.
• resources are not currently supported, but will consume space in your PBW if specified.
• messageKeys are not permitted.

src/rocky/index.js

This is now the main entry point into our application on the watch. This is where our Rocky.js JavaScript code resides. All code within this file will be executed on the smartwatch. Additional scripts may be placed in this folder, see below.

src/pkjs/index.js

This file contains our PebbleKit JS (pkjs) JavaScript code. This code will execute on the mobile device connected to the smartwatch. Additional scripts may be placed in this folder, see below.

For Rocky.js projects only, we've added a new simplified communication channel postMessage() and on('message', ...) which allows you to send and receive JavaScript JSON objects between the phone and smartwatch.

Additional Scripts

Both the rocky and pkjs folders support the use of multiple .js files, which helps to keep your code clean and modular. Use the CommonJS Module format for your additional scripts, then require() them in your index.js.

// file: src/rocky/additional.js
function test() {
  console.log('Additional File');
}

module.exports.test = test;

// file: src/rocky/index.js
var additional = require('./additional');
additional.test();

common/*.js

If you need to share code between rocky and pkjs, you can create a common folder, then add your JavaScript files.

// file: src/common/shared.js
function test() {
  console.log('Hello from shared code');
}

module.exports.test = test;

// file: src/rocky/index.js
var shared = require('../common/shared');
shared.test();

// file: src/pkjs/index.js
var shared = require('../common/shared');
shared.test();

Available APIs

In this initial release of Rocky.js, we have focused on the ability to create watchfaces only. We will be adding more and more APIs as time progresses, and we're determined for JavaScript to have feature parity with the rest of the Pebble developer ecosystem.

We've developed our API in-line with standard Web APIs, which may appear strange to existing Pebble developers, but we're confident that this will facilitate code re-use and provide a better experience overall.

System Events

We've provided a series of events which every watchface will likely require, and each of these events allow you to provide a callback method which is emitted when the event occurs.

Existing Pebble developers will be familiar with the tick style events, including: secondchange, minutechange, hourchange and daychange. By using these events, instead of setInterval, we're automatically kept in sync with the wall clock time.

We also have a message event for receiving JavaScript JSON objects from the pkjs component, and a draw event which you'll use to control the screen updates.

rocky.on('minutechange', function(event) {
  // Request the screen to be redrawn on next pass
  rocky.requestDraw();
});

Drawing Canvas

The canvas is a 2D rendering context and represents the display of the Pebble smartwatch. We use the canvas context for drawing text and shapes. We're aiming to support standard Web API methods and properties where possible, so the canvas has been made available as a CanvasRenderingContext2D.

Please note that the canvas isn't fully implemented yet, so certain methods and properties are not available yet. We're still working on this, so expect more in future updates!

rocky.on('draw', function(event) {
  var ctx = event.context;

  ctx.fillStyle = 'red';
  ctx.textAlign = 'center';
  ctx.font = '14px Gothic';

  var w = ctx.canvas.unobstructedWidth;
  var h = ctx.canvas.unobstructedHeight;
  ctx.fillText('Rocky.js Rocks!', w / 2, h / 2);
});

Limitations

We are still in the early beta phase and there are some limitations and restrictions that you need to be aware of:

• Don't publish Rocky.js watchfaces to the Pebble appstore yet, they will stop working.
• Rocky.js watchfaces only run on the 4.0 emulators/firmware. The 4.0 firmware will be available soon for Basalt, Chalk and Diorite.
• No support for custom fonts, images and other resources, yet.
• No C code allowed.
• No messageKeys.
• There are file size and memory considerations with your Rocky.js projects. If you include a large JS library, it probably won't work.

SDK 4.0

We have published an updated version of CloudPebble which now supports creating Rocky.js watchfaces in JavaScript.

If you prefer our local tools, we've also published everything you need to begin creating Rocky.js watchfaces. Run the following command to install the Pebble Tool and 4.0 SDK:

$ brew upgrade pebble-sdk
$ pebble sdk install latest

How to Get Started

We created a 2-part tutorial for getting started with Rocky.js watchfaces. It explains everything you need to know about creating digital and analog watchfaces, plus how to retrieve weather conditions from the internet.

If you're looking for more detailed information, check out the API Documentation.

Sample Watchfaces

We've already created a few sample watchfaces:

• Tictoc - Simple analog watchface.
• Tictoc Weather - Simple analog watchface with weather data from a REST API.
• Leco with Weather - Simple digital watchface with weather data from a REST API.
• Leco with Clay - Simple analog watchface which uses Clay for configurable settings.
• Simplicity - Rocky.js version of the classic Simplicity watchface.

Feedback and Help

We hope you're as exicited about Rocky.js as we are. If you need assistance, have feedback or just want to send us some love, we're in #rockyjs on [Discord]({{ site.links.discord_invite }}) or the Pebble developer forums.

We're already working on the next update of Rocky.js and your feedback will help shape the future!