Watchface background configuration using Slate

There are two ways to learn to use Slate to create a configuration screen to change the background of your watchface. The right way involves reading the documentation for AppMessage (which will push you down the rabbit role of data structures); watching the video tutorial, that suggests you install the SDK, an http server through npm, and Slate through Bower; and possibly many other tasks which I'm not aware of because I followed a different path.

Then there is a quick way, which I'll describe in this easy tutorial. Here is what you'll need:

• a CloudPebble account
• a watchface app, written in C, with a bitmap background that you want to be configurable. The one from the Create a C Watchface tutorial is a good start.
• a web server to host static files. GitHub Pages works very well for that.

And here are the step-by-step instructions:

Publish a configuration screen

Let's start by creating the configuration page. Slate is nothing more than a front-end framework that includes CSS, JavaScript and font files to make your page look good. So instead of downloading the entire distribution file, you can simply copy the config folder from the Slate config example.

Next, you want to edit the index.html file, to show your list of background options, using a HTML select tag. In my example, I reused the id background_color_picker, but made a few changes to the function getConfigData in order to pass the value with the name gem_color. If you copy & paste my file, these are the only two strings that you may consider adapting to your watchface context.

Once ready, publish your files, for example by pushing them to a gh-pages branch in your GitHub project. Mine is available at http://bani.github.io/pebble-diamond/config.

Update Application Settings

From the Settings screen in CloudPebble you want to update the PebbleKit JS section to mark the checkboxes "Check JavaScript" and "Configurable" and to add a new message key. This is what mine looks like:

Add files to your project

You'll need to add all bitmap files you want to use in the Resources section, and add a new Source File of type JavaScript and name pebble-js-app.js. For the contents of this file, you can again copy it from the example or my file. There are three things you need to update:

• the URL where your configuration page is available;
• the name of the key in configData must match what you passed from the options in getConfigData();
• the key in the dict you'll pass as AppMessage must match the MESSAGE KEY entered above.

Update your code

Now is time for the fun part of making your background actually change when the user submits a new configuration.

Define your message key:

The same way you created a MESSAGE KEY in settings you want to define it in your C file just below the include header:

#define KEY_GEM_COLOR 0

Register the handler to receive messages inside your handle_init():

app_message_open(64, 64);
app_message_register_inbox_received(inbox_received_handler);

There is some explanation on how to calculate the actual size that you need in the dict_calc_buffer_size documentation, but let's leave that for people following "The right way"™ path. 64 works ¯\_(ツ)_/¯.

Implement the inbox_received_handler function:

Another copy & paste comes in handy here:

Again, update the references to gem_color with your variable name.

Implement the set_background function:

I've extracted some of the lines that were in the "Background Image" section of main_window_load in the example watchface to a separate function set_background_gem that I could call whenever the image needed to be updated. The lines in question were:
s_bitmap = gbitmap_create_with_resource(RESOURCE_ID_BGIMAGE);
bitmap_layer_set_bitmap(s_bitmap_layer, s_bitmap);

You just need to create a switch statement to decide which bitmap to load and then add it to the layer in the end, like in this example:

Note that before reassigning the pointer you should destroy the old one, in order to avoid leaking memory. Also in my code I decided to mark the layer dirty inside the inbox_received_handler, but here could be a good location for this code as well.

Conclusion

That's it! If everything went according to the plan, you should have a working configurable background now. I'd like to end this tutorial with a big thanks to the people in the Pebble dev Slack group who supplemented my lack of RTFM answering all my questions while I was trying to add a configuration screen to my watchface ♥. My full code is available in GitHub.