README.md

PebbleOS

This repository contains the source code of PebbleOS.

How PebbleOS works

Read more in the very detailed PebbleOS architecture presentation

Then read this presentation on how PebbleOS works!

Join the Rebble Discord #firmware-dev channel to discuss.

Watch the Podcast

Several original PebbleOS firmware engineers recorded a podcast about the OS.

Podcast	Gemini Summary

Architecture

WARNING: Codebase is being refactored/modernized, so only certain features may work right now.

Getting Started

• Use Linux (tested: Ubuntu 24.04, Fedora 41) or macOS (tested: Sequoia 15.2)

• Clone the submodules:

  git submodule init
  git submodule update

• Install GNU ARM Embedded toolchain from https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads. Make sure it is available on your PATH by checking arm-none-eabi-gcc --version returns the expected version.

• If using Ubuntu, install gcc-multilib and gettext

• Create a Python venv:

  python -m venv .venv

• Activate the Python venv (also every time you start working):

  source .venv/bin/activate

• Install dependencies:

  pip install -r requirements-linux.txt

• Install local dependencies:

  pip install -e \
    python_libs/pblprog \
    python_libs/pebble-commander \
    python_libs/pulse2 \
    python_libs/pebble-loghash

• Install emscripten

  • If you're on Mac and using Homebrew, you can run brew install emscripten.
  • If you're on Linux, follow the instructions here and install version 4.0.1.
  • You can skip this if you wish by configuring with --nojs but beware the built-in clock for several devices requires JS and will render a blank screen when disabled.

Building

First, configure the project like this:

./waf configure --board <board>

Note: If you wish to debug, you're likely to want --nowatchdog --nostop --nosleep also.

At this moment, only the following boards are supported/tested:

• asterix_evt1
• snowy_bb2 (no Bluetooth)
• silk_bb2 (no Bluetooth)

Then build:

./waf build

PRF can be also be built:

./waf build_prf

Flashing firmware (silk/snowy bigboards)

Make sure openocd is installed, then run:

./waf flash

If bootloader image is not available, or you simply want to flash the firmware image, use:

./waf flash_fw

Note that you may change the default probe using the --jtag option when configuring the project.

Note: If using nRF52 based board, make sure Nordic S140 Softdevice is flashed. You can find it here.

Flashing resources

The first time you boot you may see a "sad watch" screen because resources are not flashed. To flash resources, run:

./waf image_resources

You don't need to do this every time, only when resources are changed.

Viewing logs

./waf console

Building for QEMU

The same QEMU binary found in the SDK can be used to build and develop the firmware.

If you're using an Apple Silicon Mac, you might find it easier to build QEMU from source.

The steps here are similar that of real hardware:

./waf configure --board=snowy_bb2 --qemu
./waf build
./waf qemu_image_spi
./waf qemu

You can then launch a console using:

./waf qemu_console

Finally, you can debug with GDB using:

./waf qemu_gdb