Pebble Watch Face Development

This skill provides expert guidance for developing Pebble SDK v3 watch applications with native C code for the watchface and companion JavaScript for phone-side data fetching.

Project Architecture

This is a Pebble SDK v3 watch app consisting of:

Development Workflow

When assisting with Pebble development, follow this workflow:

Building and Running

1. **Build the app**: Use `pebble build` from repo root (runs `wscript` which calls `pbl_build`/`pbl_bundle`)

2. **Install to device/emulator**: `pebble install --phone <IP>` or via Pebble development tools

3. **View logs**: `pebble logs` captures both C `APP_LOG()` output and JS `console.log()` messages

4. **JS bundling**: Entry point is `src/pkjs/index.js` which requires `./app`; bundler outputs `build/pebble-js-app.js`

Making Code Changes

**Native C (watchface)**:

**JavaScript (companion)**:

Critical Patterns and Constraints

Message Protocol

**When modifying message keys:**

1. Update `js/message_keys.json`

2. Run `pebble build` to regenerate headers

3. NEVER hardcode mismatched keys between JS and C

AppMessage Buffer Sizes

JavaScript Networking

UI Rendering

Configuration and Settings

App Metadata

Multi-JS Build

Common Tasks

Adding New Message Keys

1. Edit `js/message_keys.json` with new key name

2. Run `pebble build` to regenerate headers

3. Update C code to use `MESSAGE_KEY_NEWNAME`

4. Update JS to send/receive using `MessageKeys.NEWNAME`

Modifying Weather Data

1. **C side**: Add text layer and buffer in `src/c/myfirstproject.c`

2. **Message key**: Add to `js/message_keys.json`

3. **JS side**: Fetch data in `src/pkjs/app.js` and add to dictionary

4. **Handler**: Process in `inbox_received_callback` with `dict_find()`

Debugging Network Issues

1. Check `pebble logs` for JS console output

2. Verify XHR timeout values (should be 8000-10000ms)

3. Test fallback behavior when network unavailable

4. Emulator may need network access configuration

Important Gotchas

1. **Message key synchronization**: Any change to `js/message_keys.json` requires rebuild and alignment between C and JS

2. **XHR timeouts**: Always include explicit timeouts; network behavior changes require timeout handling

3. **Buffer sizes**: Don't modify AppMessage buffer sizes without memory audit

4. **Platform variants**: UI layout changes may need conditional compilation for different Pebble models

5. **JS bundler**: Don't change `src/pkjs/index.js` entry point without updating `wscript`

6. **Generated files**: Never manually edit `include/message_keys.auto.h` or `src/message_keys.auto.c`

Code Examples

Message Handling (C)

```c

static void inbox_received_callback(DictionaryIterator *iterator, void *context) {

Tuple *pressure_tuple = dict_find(iterator, MESSAGE_KEY_PRESSURE);

if(pressure_tuple) {

snprintf(s_pressure_buffer, sizeof(s_pressure_buffer), "%d hPa", (int)pressure_tuple->value->int32);

text_layer_set_text(s_pressure_layer, s_pressure_buffer);

}

}

```

Message Key Fallback (JS)

```javascript

var MessageKeys;

try {

MessageKeys = require('message_keys');

} catch(e) {

MessageKeys = { TEMPERATURE: 0, CONDITIONS: 1, PRESSURE: 2, /* ... */ };

}

```

Bundler Entry (wscript)

```python

ctx.pbl_bundle(

js=True,

js_entry_file='src/pkjs/index.js'

)

```

Pre-Edit Checklist for AI Agents

Before making changes to this codebase:

1. ✓ Read `package.json` and `wscript` to understand build targets and JS entry file

2. ✓ When changing message keys, update `js/message_keys.json` and plan for rebuild

3. ✓ Verify changes don't require AppMessage buffer size modifications

4. ✓ Keep changes small and idempotent; major refactors require manual device testing

5. ✓ Use proper logging: `APP_LOG()` in C, `console.log()` in JS for debugging

6. ✓ Test network fallback behavior for JS changes

7. ✓ Verify platform-specific UI code doesn't break other Pebble models

When to Ask for Clarification

Request additional context if: