Pebble Developer Blog

Pebble.js - Pebble Package Edition!

Thu, 22 Dec 2016 00:00:00 +0000

We're pleased to announce that Pebble.js has now been published as a Pebble Package. Pebble.js lets developers easily create Pebble applications using JavaScript by executing the JavaScript code within the mobile application on a user's phone, rather than on the watch.

Making Pebble.js a Pebble Package means Pebble.js projects can be converted to standard Pebble C projects. This gives benefits like the ability to easily utilize other Pebble Packages, such as Clay for Pebble, or easily importing and exporting the project with CloudPebble.

The Pebble.js package is using the develop branch from the Pebble.js repository on Github, and can be updated independently from CloudPebble deployments.

It also supports the Diorite platform!.

Creating a New Project

The initial steps vary if you're using CloudPebble or the Local SDK. Follow the appropriate steps below to create a new project.

CloudPebble

If you're using CloudPebble, follow these initial steps:

Create a new project:
- Project Type = Pebble C SDK
- Template = Empty Project
Add the following dependency:
- Package Name = pebblejs
- Version = 1.0.0
Add a new main.c file and an index.js file.

Now continue to add the default project files.

Local SDK

If you're using the Local SDK, just create a new C project with Javascript support:

$ pebble new-project PROJECTNAME --javascript

Now continue to add the default project files.

Default Project Files

Copy and paste these default project files into your project, replacing any existing file contents:

your-main.c

#include <pebble.h>
#include "pebblejs/simply.h"

int main(void) {
  Simply *simply = simply_create();
  app_event_loop();
  simply_destroy(simply);
}

index.js

require('pebblejs');
var UI = require('pebblejs/ui');

var card = new UI.Card({
  title: 'Hello World',
  body: 'This is your first Pebble app!',
  scrollable: true
});

card.show();

At this point you should be able to compile and run your new project.

Migrating an Existing Project

Unfortunately there isn't an automated way to migrate your existing Pebble.js project, but the steps are fairly straightforward.

Create a new project, following the steps above.
Change the project settings to match your old project settings, including the UUID.
Copy your project resources (images, fonts etc.), and source files into the new project.
Compile and enjoy your new C project with Pebble.js support.

Note: index.js is a direct replacement for app.js, which may be your old Javascript file.

Next Steps?

Want to add Clay support to your project? It's now easy by following the standard Clay Getting Started instructions!

If you have any questions or problems, post the details on the developer forum or Discord.

Happy Holidays!

Jon Barlow + Team #PEBBLExFITBIT

Announcing Pebble SDK 4.3

Wed, 23 Nov 2016 00:00:00 +0000

Things have been a bit 'quiet' recently, but we're back with another fresh Pebble SDK! In this release we've included one of the most frequently requested APIs, exposed the raw HRM sensor value, released PebbleKit 4.0, plus added an exciting new BLE HRM mode.

It's. Oh. So quiet. Ssshhhhhh.

We've added an often requested method for developers to detect if Quiet Time is enabled. To say that we had a lot of requests for this would be an understatement.

Quiet Time can be enabled manually, via calendar events, or via scheduled times, so we've made a simple method for querying whether it's currently active.

All you need to do is check each minute if it's active. This is easily done within the tick event, as follows:

static void handle_tick(struct tm *tick_time, TimeUnits units_changed) {
  if (units_changed & MINUTE_UNIT) {
    if (quiet_time_is_active()) {
      // It's nice and quiet
    } else {
      // Starts another big riot
    }
  }
}

You may also peek this value, for example, to prevent your application from vibrating during Quiet Time:

static void do_vibration() {
  if (!quiet_time_is_active()) {
    vibes_short_pulse();
  }
}

Raw HRM BPM

The Pebble Health API now exposes the raw BPM value from the Heart Rate Monitor sensor. This raw value is not filtered and is useful for applications which need to display the real-time sensor value, similar to the Pebble Workout app.

For example, in order to peek the current real-time HRM sensor, you would do the following:

HealthServiceAccessibilityMask hr = health_service_metric_accessible(HealthMetricHeartRateRawBPM, time(NULL), time(NULL));
if (hr & HealthServiceAccessibilityMaskAvailable) {
  HealthValue val = health_service_peek_current_value(HealthMetricHeartRateRawBPM);
  if(val > 0) {
    // Display raw HRM value
    static char s_hrm_buffer[8];
    snprintf(s_hrm_buffer, sizeof(s_hrm_buffer), "%lu BPM", (uint32_t)val);
    text_layer_set_text(s_hrm_layer, s_hrm_buffer);
  }
}

Find out more in the Heart Rate Monitor API guide.

PebbleKit 4.0

PebbleKit for iOS and Android facilitates communication between Pebble watchapps and 3rd party companion phone apps. Version 4.0 introduces a number of new features and bug fixes, including:

Support for Pebble 2 (required for iOS only)
Removal of Bluetooth Classic (iOS)
Sports API - Support 3rd party HRM
Sports API - Custom data field and label
Sports API - Helper object to simplify usage, and minimize updates via Bluetooth

For further information about the specific platform changes, view the full iOS, or Android changelogs.

BLE HRM Mode

Ever wanted to use your Pebble 2 HRM as a dedicated BLE HRM device with your favourite mobile fitness app? Well now you can! Firmware 4.3 now implements the standard Bluetooth Heart Rate Service profile. In order to enable this profile, users must enable 'Pebble Health', then enable 'Heart Rate Monitoring' within the Pebble Health settings within the Pebble mobile app.

Developers who are looking to integrate directly with this profile should be aware of the following:

The Heart Rate Service UUID will be present in the advertising payload of Pebble, but you must open the Bluetooth settings on the Pebble to make it advertise and be discoverable over Bluetooth.

Because it's highly likely that the Pebble is already connected to the phone, it will not be advertising. Therefore, we recommend that your mobile app also enumerates already connected devices, to see if any of them support the Heart Rate Service. This is in addition to scanning for advertisements to find new devices that support HRS. By enumerating connected devices, you improve the user experience: users will not have to go into the Bluetooth settings menu on Pebble if their Pebble is already connected to the phone.

The first time an application subscribes to the Heart Rate Measurement characteristic, a UI prompt will appear on the Pebble, asking the user to allow sharing of their heart rate data. This permission is stored for the duration of the Bluetooth connection.

When HR data sharing is active, the HR sensor will run continuously at ~1Hz sample rate. This means there is a significant battery impact when using this feature for an extended period of time.

When all applications have unsubscribed from the Heart Rate Measurement characteristic, the HR sensor automatically returns to its default state.

Mobile apps should unsubscribe from the Heart Rate Measurement characteristic as soon as the data is no longer required. For example, a workout app should unsubscribe when the workout has finished and/or the application is exited.

If the Heart Rate Service is used continuously for a prolonged period of time (currently 4hrs), a notification is presented on the watch to remind the user that the HR data is still being shared.

The user can stop sharing HRM data from Settings > Bluetooth > Device. If the user chooses to stop sharing, the Bluetooth connection is briefly disconnected and reconnected to forcefully remove all subscribers. Unfortunately the Bluetooth GATT specification does not provide a better mechanism for a service to unsubscribe subscribers, only subscribers can unsubscribe themselves.

Service Characteristics Notes:

'Sensor Contact' field is used.
'Body Sensor' characteristic is used. The value is constant though (It will read "Wrist" / 0x02)
'RR Interval' is currently NOT used.
'Energy Expended' field is currently NOT used.
'Heart Rate Control Point' characteristic is currently NOT used.

What's Next

Check out the release notes for a full list of changes and fixes that were included in SDK 4.3.

Let us know on Twitter if you built something cool using the new APIs! We'd love to hear about your experiences with the SDK.

Happy Hacking!

Team Pebble

4.2-beta4 SDK - Emery Edition!

Tue, 11 Oct 2016 00:00:00 +0000

We're incredibly excited to announce the first public beta of the Pebble SDK 4.2. This is the first time that developers can experience the new 'Emery' platform which is specifically created for the upcoming Pebble Time 2.

All About Those Pixels

The new display on the Pebble Time 2 is almost 53% physically larger, and the Pixels per inch (PPI) has been increased from 182 PPI to 202 PPI. This is a massive 200x228 pixels, compared to 144x168 on the Pebble Time Steel, that's an 88% increase in the total amount of pixels!.

Take a look at our Hardware guide for further information about the specifications of the Pebble Time 2.

Watchfaces and watchapps that have not been updated for the Emery platform will run in Bezel Mode. This means they will appear centered on screen at their original resolution (144x168), but due to the change in PPI, they appear slightly smaller.

Left: Pebble Time Steel, Middle: Pebble Time 2 - Bezel Mode, Right: Optimized for Pebble Time 2.
Concentricity Watchface

The increased number of pixels would immediately make you think that you can just add more elements to your watchface design, but due to the increase in PPI, existing elements and fonts may feel slightly smaller than expected when viewed on an actual device.

The image below simulates how the PPI difference makes a bezel mode application feel smaller on the Pebble Time 2.

Left: Pebble Time Steel, Right: Pebble Time 2 - Bezel Mode.

We've now seen that the increased amount of pixels doesn't necessarily equate to bigger text on our devices, due to the change in PPI, that's why we've created the new ContentSize API.

Introducing the ContentSize API

All existing Pebble smartwatches provide the ability for users to change the size of text for notifications and some system UI components using Settings > Notifications > Text Size.

The new ContentSize API now exposes this setting to developers, in order for them to adapt their application design and layout based on this user preference.

In the previous section, we saw how the PPI increase on Pebble Time 2 affected the relative size of a watchface. In the image below you can see precisely how text sizes are affected by the PPI change.

Yellow: Pebble Time Steel, Green: Pebble Time 2.

To negate the effects of this reduced font size, the Emery platform uses larger fonts by default. Developers can use the ContentSize API to match this behaviour within their own applications.

The following table explains how the text size setting affects the content size on each platform:

Platform	Text Size: Small	Text Size: Medium	Text Size: Large
Aplite, Basalt, Chalk, Diorite	ContentSize: Small	ContentSize: Medium	ContentSize: Large
Emery	ContentSize: Medium	ContentSize: Large	ContentSize: Extra Large

Developers should aim to implement designs which adapt to the capabilities of the device, but also the accessibility requirements of the user. The ContentSize API satisfies both of these goals.

For more information, read the ContentSize guide.

New for Rocky.js

With the release of SDK 4.2, we're extremely proud to announce that Rocky.js watchfaces can be published into the Pebble appstore! As usual, don't publish apps with the beta SDK into the appstore, please wait for the final release.

In addition to finalizing the memory contract for Rocky.js apps, we've also added a few new APIs to work with:

Memory Pressure

The memorypressure event has been added to allow developers to handle the situations which occur when the amount of memory available to their application has changed. Initially we've only implemented the high memory pressure level, which occurs right before your application is about to be terminated, due to a lack of memory. If you can free sufficient memory within the callback for this event, your application will continue to run. Please refer to the Rocky.js documentation and the memory pressure example application.

UserPreferences

The first watchface setting exposed in the new UserPreferences object is contentSize. This exposes the new ContentSize API to Rocky.js watchface developers. Find out more in the Rocky.js UserPreferences documentation.

What's Next

Check out the release notes for a full list of changes and fixes that were included in SDK 4.2-beta4.

Let us know on Twitter if you built something cool using the new APIs! We'd love to hear about your experiences with the SDK.

Happy Hacking!

Team Pebble

Ready for Pebble 2

Tue, 04 Oct 2016 00:00:00 +0000

The latest 4.1 releases of the firmware, mobile apps and SDK bring support for the new Pebble 2 smartwatches, which have started appearing on the wrists of developers and reviewers around the globe.

Pebble 2 smartwatches are on their way to Kickstarter backers, and firmware 4.1 will be ready and waiting for them.

Heart Rate Monitor API

The HRM APIs allow allow developers to query the user's current and historical heart rates. We've provided a simple to use API which caters for the most common use-cases.

Find out more in the Heart Rate Monitor API guide.

AppGlance REST API

The AppGlance REST API enables developers to programmatically set the icon and subtitle that appears alongside their app in the launcher. Developers can push slices to the their app's glance using their own backend servers by sending HTTPS requests to the timeline endpoint.

Find out more about App Glance in the SDK documentation, or read the AppGlance REST API guide.

What's Next

Check out the release notes for a full list of changes and fixes that were included in SDK 4.1.

Let us know on Twitter if you built something cool using the new APIs! We'd love to hear about your experiences with the SDK.

Happy Hacking!

Team Pebble

Timeline - The Future of the Past!

Tue, 06 Sep 2016 00:00:00 +0000

If you’ve been living under a rock, or have just been sunning yourself on the beach for the past week, you might have missed the launch of Pebble OS 4.0. This new version introduced some fantastic new features, such as the updated health app, timeline quick view, app glances, Rocky.js and a new system launcher.

The Past and the Furious

However, there was one change which was met with mixed feedback from both users and developers alike, the removal of timeline past. Previously accessible via the UP button, timeline past was removed as part of the new 4.0 user experience (UX). In 4.0 we introduced new APIs to give developers more options to improve their application’s UX and potentially shift away from using the past for interactions

Unfortunately, this change prevented users from accessing any timeline pin which wasn’t in the present or future, negatively affecting a number of apps and their use cases for the timeline.

We carefully listened to feedback and suggestions from our developer community via the forums, Reddit, Twitter and Discord, and we are happy to announce that timeline past has returned in the v4.0.1 update. Users who need to access the timeline past can now assign it to one of their quick launch buttons.

And so, with the reintroduction of timeline past, balanced was restored, and that was the end of the story. Or was it?

Back to the Future!

If you’re the developer of an application which relies upon timeline past, you will probably want to inform your users about how they can access timeline past, as it will not be enabled by default. Fortunately, there are multiple ways in which you can do this easily.

1. App Store Description

Use the app store description of your app to explain that your application utilizes timeline past and that users will need to assign it to quick launch. For example:

This application utilizes pins in the timeline past. On your Pebble, go to ‘Settings’, ‘Quick Launch’, ‘Up Button’, then select ‘Timeline Past’. You can then access timeline past by long pressing UP.

2. Display a Splash Screen

Add a splash screen to your application which only runs once, and display a message informing users how to enable timeline past. You could use the ‘about-window’ Pebble package for a really quick and easy solution.

3. Display a One-Time Notification

Display a system notification which only fires once, and display a message informing users how to enable timeline past.

4. Display a Timeline Notification

Display a timeline notification, and display a message informing users how to enable timeline past.

The Future of the Past

For now, developers can continue to utilize timeline past, but over time we would like to provide a more diverse set of functionality that allows developers to surface information to their users. For example, some use cases of timeline past may be more appropriate as using an app glance, or timeline quick view instead.

We’re Listening!

Your feedback is incredibly important to us, it’s how we keep making awesome things. We love to receive your product and feature suggestions too.

We’re particularly interested to hear about your use cases and ideas for timeline as we travel further into the future! Let us know via the forums, Twitter and Discord!

Announcing Pebble SDK 4.0

Tue, 30 Aug 2016 00:00:00 +0000

Today we have the pleasure of announcing the release of Pebble SDK 4.0. We have published an updated version of the Pebble Tool, the SDK itself, and we've deployed 4.0 onto CloudPebble. It's time to get busy!

What's New

Pebble OS 4.0 has been released and users with Pebble Time, Pebble Time Steel and Pebble Time Round will be receiving the update today.

We covered the new features in detail very recently, but let's have a quick reminder of the new APIs and functionality that's included.

Rocky.js

Javascript on the freakin' watch! Although still in beta, Rocky.js lets you start developing watchfaces in JavaScript using standard Web APIs, which you can then run directly on your watch. It's an embedded JavaScript revolution!

Read the updated Rocky.js blog post to get started.

Timeline Quick View

Timeline Quick View displays upcoming information from your timeline on your watchface. We introduced the UnobstructedArea API to allow developers to detect if the screen is being obstructed by a system modal, such as Timeline Quick View. Developers can use this new API to adapt their watchface layout according to the available screen real estate.

Read the UnobstructedArea guide to get started.

AppGlances

With the new AppGlance API, developers can dynamically change the icon and subtitle of their watchapp within the system launcher, at runtime. This allows developers to provide meaningful feedback to users without the need for their application to be launched.

Read the AppGlance C guide and the AppGlance PebbleKit JS guide to get started.

Diorite Platform

The new Pebble 2 devices use apps built for the Diorite platform, so you'll need SDK 4.0 to develop applications which target those devices.

Take a look at the Hardware Information guide to find out about the capabilities of the Pebble 2.

One Click Action application

The One Click Action application pattern promotes a type of watchapp which serves a single purpose. It launches, performs an action, and then terminates. This pattern utilizes the new AppGlance and AppExitReason APIs.

Take a look at the One Click Actions guide to get started.

Dude, Where's my HRM API?

We had planned on shipping the Heart Rate API with 4.0, but it's been pushed back into 4.1 so that we can add even more awesomeness. Pebble 2 devices will begin to appear on wrists after firmware 4.1 ships, so you'll still have time to begin implementing HRM data into your watchapps and watchfaces. We will announce details of the HRM API as soon as it's available.

What's Next

Please remember that we will promote watchfaces and watchapps that make use of these new 4.0 APIs if you submit them to the appstore from August 31st onwards.

Let us know on Twitter if you build something cool using the new APIs! We'd love to hear about your experiences with the SDK.

Happy Hacking!

Team Pebble

Prime Time is Approaching for OS 4.0

Fri, 19 Aug 2016 00:00:00 +0000

Pebble developers of the world unite! Pebble OS 4.0 is just around the corner and it's now time to put those finishing touches on your projects, and prepare them for publishing!

Pebble Time owners will be receiving OS 4.0 before Kickstarter backers receive their Pebble 2 watches, so we're recommending that developers publish their 4.0 watchapps and watchfaces into the appstore from August 31st onwards.

We'll be promoting new and updated apps which utilize the new SDK 4.0 APIs and features by creating a brand new category in the appstore called 'Optimized for 4.0'. This is your time to shine!

If you haven't even begun to prepare for 4.0, there are some really quick wins you can use to your advantage.

The new launcher in 4.0 allows developers to provide a custom icon for their watchapps and watchfaces.

If your png file is color, we will use the luminance of the image to add some subtle gray when rendering it in the launcher, rather than just black and white. Transparency will be preserved.

You should add a 25x25 png to the resources.media section of the package.json file, and set "menuIcon": true. Please note that icons that are larger will be ignored and your app will have the default icon instead.

"resources": {
  "media": [
    {
      "menuIcon": true,
      "type": "png",
      "name": "IMAGE_MENU_ICON",
      "file": "images/icon.png"
    }
  ]
}

Timeline Quick View

This new feature really brings your timeline into the present, with your next appointment appearing as a modal notification over the active watchface.

We introduced the UnobstructedArea API in 4.0 to allow developers to detect if the screen is being obstructed by a system modal. Below you can see two examples of the Simplicity watchface. The Pebble on the left is not using the UnobstructedArea API, and the Pebble on the right is.

Watchface not updated

Respects new 4.0 unobstructed area

You can detect changes to the available screen real-estate and then move, scale, or hide their layers to achieve an optimal layout while the screen is partially obscured. This provides a fantastic experience to your users.

There's a dedicated guide which goes into more detail about the UnobstructedArea API, it contains examples and links to sample implementations.

AppGlances

While your static app icon and app title from the package.json are being used as the default to present your app to the user, AppGlances allow developers to control this content at runtime and to provide meaningful feedback to users directly from the new launcher. The API exposes the ability to dynamically change the icon and subtitle_template_string text of your application in the launcher.

Preview version of 4.0 launcher

Utilizing the App Glance API doesn't need to be difficult. We've provided guides, examples and sample applications for using the AppGlance C API and the AppGlance PebbleKit JS API.

The Diorite Platform

The Diorite platform was created for the new Pebble 2 devices. Its display is rectangular, 144x168 pixels, with 2 colors (black and white). It has a microphone and heart rate monitor, but it doesn't have a compass. If your app works with Aplite it will already work with Diorite, but there are some important considerations to note:

If you chose to limit your app to some platforms, you need to add "diorite" to your targetPlatforms in the package.json.
Check for the appropriate usage of compiler directives.

In general, it's better to use capability and feature detection, rather than platform detection. For example, when dealing with resources, use the suffix ~bw instead of ~aplite so they are picked on all black and white platforms.

What's Next

We're really excited for the release of Pebble OS 4.0 and the new features it brings. It's now time for you to take advantage of the new APIs and enhance your existing projects, or even create entirely new ones!

Why not build something like the One Click Action application, which utilizes the new App Glance and AppExitReason APIs.

Please remember that we will promote watchfaces and watchapps that make use of these new 4.0 APIs if you submit them to the appstore from August 31st onwards.

Let us know on Twitter if you build something cool using the new APIs! We'd love to hear about your experiences with the SDK.

Happy Hacking!

Team Pebble

Introducing Rocky.js Watchfaces!

Mon, 15 Aug 2016 00:00:00 +0000

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.

Appstore Publishing

Rocky.js JavaScript watchfaces must not be published into the appstore at this time.

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 or the Pebble developer forums.

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

Creating Native Companion Apps with JS and Cordova

Fri, 01 Jul 2016 00:00:00 +0000

Creating companion apps using PebbleKit Android and PebbleKit iOS is a great way to extend the functionality of your Pebble watchfaces and apps, but what if Java or Objective C just isn't your thing? What if you love JavaScript? What if you just don't want to write the same companion app twice?

Now you don't have to! Enter Cordova - an open source framework for building cross-platform mobile apps using web technologies such as HTML5 and JavaScript. What does this mean for you? One framework, and one codebase for building Pebble companion apps for iOS and Android!

Cordova allows developers to create plugins that wrap native functionality such as accessing the phone's contacts, calendar, camera, and other phone APIs. Plugins allow you to interface with these APIs through JavaScript, and use them in your Cordova projects. Needless to say, PebbleKit Android and PebbleKit iOS are now available as a singular Cordova plugin.

In this blog post, we'll look at how to use Cordova to create a companion app that allows you to retrieve the next upcoming calendar event for the current day.

Setup

The first step will be installing Cordova and creating a new project. Cordova provides these steps generically here, but if you want to follow along down to the T, here are the steps listed below.

$ npm install -g cordova
$ cordova create calendar-example com.pebble.calendarexample "Calendar Example"
$ cd calendar-example
$ cordova platform add android
$ cordova platform add ios
$ cordova plugin add cordova-plugin-calendar
$ cordova plugin add cordova-plugin-pebblekit

Note, this assumes you have node/npm already installed and avaiable on your machine. If not, head on over to nodejs.org to install node.

Doesn't seem too bad! If the cordova create command seems a little scary to you, don't be afraid to ask for help with cordova create --help.

Querying Events

The next step is to use the calendar plugin we added earlier in order to fetch the next event for the day. Before we do that though, we'll need to to setup the Cordova PebbleKit plugin, as shown below. Fire up your favourite text editor and open www/js/index.js file. This is the JavaScript file that runs when your app starts up, your application's control logic will go here.

Upon opening the file, you'll notice there's already a fair bit of code generated by Cordova. What's important here is the onDeviceReady function, this is a callback you can use to be notified once the plugins for your Cordova project have been loaded and are ready to be called. Let's create our own function called fetchCalendarEvent to be called once the PebbleKit plugin has been setup. We'll also declare a variable uuid with our Pebble app's UUID, which is required when communicating with our watchapp via AppMessage.

var uuid = "ebc92429-483e-4b91-b5f2-ead22e7e002d";
var app = {

  /* ... */

  onDeviceReady: function () {
    app.receivedEvent('deviceready');
    window.pebblekit.setup(uuid, function () {
      app.fetchCalendarEvent();
    });
  },

  fetchCalendarEvent: function () {
    var startDate = new Date(); // Now
    var endDate = new Date();
    endDate.setHours(24, 0, 0, 0); // Nearest midnight in the future

    window.plugins.calendar.findEvent(
      undefined, // title
      undefined, // eventLocation
      undefined, // notes
      startDate,
      endDate,
      app.calendarSuccessCallback,
      app.calendarFailureCallback
    );
  },

  calendarSuccessCallback: function (events) {
    // TODO
  },

  calendarFailureCallback: function (err) {
    console.error('Failed to fatch calendar events', err);
  }

  /* ... */

}

Note, the calendar plugin recommends checking that you have sufficient permissions before using its APIs. For the sake of brevity, the permission workflow has been omitted in this post.

The first 3 parameters we passed to the calendar.findEvent function are undefined, since we don't want to filter out events with specific titles, locations, or notes. The last two parameters are callback functions that will be executed when the app has succeeded or failed to fetch calendar data. Our calendarFailureCallback will log a simple message, and our calendarSuccessCallback will sort through the events and find the earliest event in the list.

calendarSuccessCallback: function (events) {
  if (events.length == 0) {
    // TODO
    return;
  }

  // Find the earliest returned event
  var earliestEvent = events[0];
  for (var i = 1; i < events.length; i++) {
    var tempDate = events[i];
    var date1 = Date.parse(earliestEvent.startDate);
    var date2 = Date.parse(tempDate.startDate);

    if (date2 < date1) {
      earliestEvent = tempDate;
    }
  }
},

Sending An AppMessage

All we have to do now is send the relevent bits of information down to our Pebble app. This is where the Pebble plugin is going to come in handy. At the end of the function, we'll call sendAppMessage which works in a similar manner to PebbleKit JS' sendAppMessage function.

The title is easy to snag - it's a property on the event object, available via event.title. The hours and minutes will take a bit of work since they only exist within a string property on the object (event.startDate). Luckily the format for the date is fixed, so we know where in the string it will be.

With this in mind, we can use the String.prototype.substring method to extract the numbers we want. The method takes two parameters, the first is the starting index (inclusive) of the substring, and the second is the the end index (exclusive). So if we want the hour, we'd pass 11 as the starting index, and 13 as the end index. This will create a substring containing the 11th and 12th characters of the string.

Also in this example, the data object represents our AppMessage, where 10, 11, and 12 are the AppMessage keys.

// Format is in YYYY-MM-DD HH:mm:ss
var hourString = earliestEvent.startDate.substring(11, 13);
var hour = parseInt(hourString);
var minuteString = earliestEvent.startDate.substring(14, 16);
var minute = parseInt(minuteString);

// AppMessage keys
var data = {
  '10': earliestEvent.title,
  '11': hour,
  '12': minute
};

window.pebblekit.sendAppMessage(uuid, data, function () {
  console.log('sent AppMessage', data);
}, function (err) {
  console.error('Couldn\'t send AppMessage', err);
});

The only thing left is to read the AppMessage on the C side. To quote every university professor I've ever had: "We leave this as an exercise to the reader". (Just kidding, you can see the watchface's full C code here, or consult the documentation).

While we only used two of the APIs of the PebbleKit Cordova plugin here, there is much more available to you, all with new and shiny documentation

For folks that are interested, our Cordova plugin is completely open source, and hosted on Github. We welcome bug reports, feature requests, and contributions with open arms :).

And that's all there is to it! If you've been holding back on writing a companion app for your amazing app, now's the time to try it!

Introducing Clay - App configuration made easy

Fri, 24 Jun 2016 00:00:00 +0000

It is with great pleasure that I present to you, Clay, a Pebble package that makes it easy to add offline configuration pages to your Pebble apps. All you need to get started is a couple lines of JavaScript and a JSON file; no servers, HTML or CSS required.

How to get started

This post aims to provide high level explanation of how the framework works and how it came to be. Below is a quick overview of how easy it is to make your app configurable with Clay. If you would like to learn how to integrate Clay into your project, read our guide on app configuration or read the full documentation on the project GitHub repository.

1) Install the module via Pebble Packages - SDK: $ pebble package install pebble-clay - CloudPebble: Add pebble-clay, version ^1.0.0 to your project dependencies.

2) Create a configuration file that looks something like:

module.exports = [
  {
    "type": "heading",
    "defaultValue": "Example App"
  },
  {
    "type": "section",
    "items": [
      {
        "type": "color",
        "messageKey": "BackgroundColor",
        "defaultValue": "0x000000",
        "label": "Background Color"
      },
      {
        "type": "toggle",
        "messageKey": "Animations",
        "label": "Enable Animations",
        "defaultValue": false
      }
    ]
  },
  {
    "type": "submit",
    "defaultValue": "Save Settings"
  }
];

3) Update your project settings with the matching messageKeys from the config above.

4) Add a few lines to your index.js

var Clay = require('pebble-clay');
var clayConfig = require('./config');
var clay = new Clay(clayConfig);

5) Retrieve the values on the C side using standard app messages or alternatively let enamel do the work for you.

Why I created Clay

Clay began as a side project of mine. Whilst developing my Segment watchface, I wanted to add a configuration page to allow users to customize the colors of the watchface. However, I soon discovered this process to be rather fiddly. The old way of doing things required you to create and host HTML pages even for simple things like changing a background color or toggling an option. You would also need to write a bunch of boilerplate JavaScript to serialize and send the settings to the watch. Best case, for developers, this is super tedious. Worst case, it is terrifying. By day, I work as a web developer (mainly front-end) so if I was finding the process tiresome, I could only imagine how challenging it would be for someone who wasn't familiar with web technologies. And so I decided to create a framework that would alleviate this barrier for developers. I had a number of requirements that needed to be met in order for the framework to achieve my goals:

It should not require developers to write any HTML or CSS.
It should use JSON to define the generated config page.
It should all work offline
Developers should be able to add interactivity to the config page without manually manipulating DOM.
Developers should be able to create and share their own custom components.
The config page should be able to be versioned with the rest of the code in the project.
It should have extensive unit tests with 100% test coverage.

How Clay Actually Works

Clay has two main components. The first is a very long string that is compiled from all the HTML, CSS and JavaScript that forms the skeleton of the generated config page. The second is the module that gets included in your index.js. This module is in charge of bundling all the dynamic elements set by the developer into a format that can be opened using Pebble.openURL(). It is also in charge of listening for the webviewclosed event and persisting the user's settings to local storage. I use Gulp and a series of Browserify transforms to compile all these components into a single module. The advantage of using a system such as Browserify, is that later, Clay can be made into a stand alone module to be used by developers who have very advanced use cases that require Clay to be run in a hosted HTML page.

The most challenging item on the requirements list was making the whole thing work offline. Neither of the Pebble mobile apps allow file system access from the config page's webview, so I had to get a little creative. It turns out that Data URIs work with more than images. You can in fact encode an entire HTML page into the URI. This was the solution to making the config pages offline. It sounds crazy but this method actually provides other advantages for developers beyond offline access. By bundling all the HTML, CSS and JavaScript into the Clay package, the version of Clay being used by the developer will not change without the developer rebuilding their app. This means developers do not need to worry about the behavior of their app's configuration page potentially breaking as new versions of Clay get released.

Advanced Use

If developers want to add additional functionality to their config page, they can. Clay allows developers to inject, what I call a custom function into the generated config page. This allows developers control of their config page without needing to manipulate the DOM. Clay achieves this by exposing an API that provides a consistent way of interacting with the config page as well as making AJAX requests. Instead of manually updating the values of HTML elements, developers can use the much simpler Clay API.

Where to find more information

App configuration guide.
Clay GitHub repository including full documentation.
Chat to us in the #clay channel on Discord.
Visit the Pebble Forums
Tweet at @pebbledev

How to get involved

Clay is open source and welcomes pull requests from anybody. Have a look at the contributing guide for instructions on how you can help make Clay even better. Regardless of your skill level, if you have any ideas on how Clay could be improved or if you find any bugs, we would love you to submit an issue on GitHub.

Pebble Developer Blog

Pebble.js - Pebble Package Edition!

Creating a New Project

CloudPebble

Local SDK

Default Project Files

Migrating an Existing Project

Next Steps?

Announcing Pebble SDK 4.3

It's. Oh. So quiet. Ssshhhhhh.

Raw HRM BPM

PebbleKit 4.0

BLE HRM Mode

What's Next

4.2-beta4 SDK - Emery Edition!

All About Those Pixels

Introducing the ContentSize API

New for Rocky.js

Memory Pressure

UserPreferences

What's Next

Ready for Pebble 2

Heart Rate Monitor API

AppGlance REST API

What's Next

Timeline - The Future of the Past!

The Past and the Furious

Back to the Future!

1. App Store Description

2. Display a Splash Screen

3. Display a One-Time Notification

4. Display a Timeline Notification

The Future of the Past

We’re Listening!

Announcing Pebble SDK 4.0

What's New

Rocky.js

Timeline Quick View

AppGlances

Diorite Platform

One Click Action application

Dude, Where's my HRM API?

What's Next

Prime Time is Approaching for OS 4.0

Menu Icon in the Launcher

Timeline Quick View

AppGlances

The Diorite Platform

What's Next

Introducing Rocky.js Watchfaces!

It's JavaScript on the freakin' watch!

Rocky.js Projects

package.json

src/rocky/index.js

src/pkjs/index.js

Additional Scripts

common/*.js

Available APIs

System Events

Drawing Canvas

Limitations

SDK 4.0

How to Get Started

Sample Watchfaces

Feedback and Help

Creating Native Companion Apps with JS and Cordova

Setup

Querying Events

Sending An AppMessage

Introducing Clay - App configuration made easy

How to get started

Why I created Clay

How Clay Actually Works

Advanced Use

Where to find more information

How to get involved