This guide takes you from a fresh machine to PebbleOS running, in the emulator or on a watch.
Install the packages the build needs from your system’s package manager.
Ubuntu 24.04 LTS or later:
sudo apt update
sudo apt install \
bison \
clang \
cmake \
flex \
gcc \
gcc-multilib \
gettext \
git \
gperf \
libfreetype6-dev \
libglib2.0-dev \
libgtk-3-dev \
libncurses-dev \
librsvg2-bin \
libsdl2-dev \
make \
nodejs \
openocd \
pkg-config \
python3-dev \
python3-venv
Fedora 44 or later:
sudo dnf upgrade --refresh
sudo dnf install \
bison \
clang \
cmake \
dash \
flex \
freetype-devel \
gcc \
gettext \
git \
glib2-devel \
gperf \
gtk3-devel \
librsvg2-tools \
make \
ncurses-devel \
nodejs \
openocd \
pkgconf-pkg-config \
python3-devel \
SDL2-devel
Install Homebrew, then Python, Git and OpenOCD:
brew install python git openocd
brew link python@3
The remaining packages are listed in the repository and installed once it is cloned, in the next step.
Clone the repository with its submodules and enter it:
git clone --recurse-submodules https://github.com/coredevices/pebbleos
cd pebbleos
Nothing else to install.
Nothing else to install.
Install the remaining packages:
brew install $(cat requirements-brew.txt)
Create a virtual environment in the checkout, activate it and install the Python dependencies:
python3 -m venv .venv
source .venv/bin/activate
pip install -r requirements.txt
This also installs pbl, the developer command line the rest of this guide uses.
Tip
Activate the virtual environment (source .venv/bin/activate) in every new
shell before running pbl.
The PebbleOS SDK provides the toolchain and tools the build needs:
curl -LsSf https://github.com/coredevices/PebbleOS-SDK/releases/latest/download/pebbleos-sdk-installer.sh | sh
The build finds the installed SDK on its own; Build system explains how to pick a specific one.
Every build targets a board, either an emulated watch such as qemu_emery
or a real one; Boards lists them. Configure a build
directory for one and build it:
pbl configure --board qemu_emery
pbl build
Launch the emulator:
pbl qemu
A window opens with the emulated watch and the firmware boots to the watchface; the arrow keys are the watch buttons. The Emulator page covers everything else you can do with it.
There are two ways to get the firmware onto a watch:
Flash it with a programmer. With a programmer connected as the board’s page shows, pbl flash writes the firmware directly:
pbl flash
The first time, the system resources have to be written as well; pbl flash explains how for each board.
Sideload a bundle. Without a programmer, package the firmware with
pbl bundle, which writes a .pbz into the build directory:
pbl bundle
Copy the .pbz to the phone paired with the watch. In the Pebble
mobile app, enable Settings -> Show debug options, then go back to the
Devices tab, tap your watch, choose Firmware Update Debug -> Sideload FW, and select the file. The app starts the update and shows its
progress on the watch card.
Note
Holding Back + Up + Select reboots the watch into the recovery firmware (PRF), from which the Pebble mobile app can install a firmware again.
The pbl CLI documents every pbl command.
Emulator and simulator compares the emulator and the native simulator.
Testing covers the unit and integration test suites.
Architecture overview explains how the firmware is put together.
Generated from PebbleOS 3a7b71785. This page is maintained in the pebbleos repository: docs/getting_started/index.md.