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

• (If you want to use an nRF based board) Install nrfjprog from https://www.nordicsemi.com/Products/Development-tools/nRF-Command-Line-Tools.

• 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

Building

First, configure the project like this:

./waf configure --board <board> --nojs

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_vla_dvb1
• 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

Flashing firmware (nRF)

First make sure Nordic S140 Softdevice is flashed (only do this once):

nrfjprog --program src/fw/vendor/nrf5-sdk/components/softdevice/s140/hex/s140_nrf52_7.2.0_softdevice.hex --sectoranduicrerase --reset

Flash the firmware:

nrfjprog --program build/src/fw/tintin_fw.elf --sectorerase --reset

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 --nojs --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