---
title: "Architecture overview"
canonical_url: https://developer.repebble.com/pebbleos/docs/architecture/
last_updated: 2026-11-22
sdk_version: 4.44
---
# Architecture overview

Source: https://developer.repebble.com/pebbleos/docs/architecture/

PebbleOS is the operating system of the Pebble watches. It is a single firmware image, built per board, that runs the watch’s own UI and services and hosts third-party watchfaces, apps and background workers. This page gives the overall picture; each layer has its own section with the details.

## Layers

```
block-beta
  columns 2
  apps["Apps and workers"]:2
  applib["Application framework<br/>pebble/applib"]:2
  services["Services<br/>pebble/services"]:2
  subsys["Subsystems<br/>subsys/"] libs["Libraries<br/>lib/"]
  drivers["Drivers<br/>drivers/"]:2
  kernel["Kernel<br/>kernel/"]:2
  soc["SoC and HAL<br/>soc/, third_party/"]:2

  classDef app fill:#fa4a36,stroke:#fa4a36,color:#ffffff
  classDef system fill:#fd8a7c,stroke:#fd8a7c,color:#171717
  classDef base fill:#525252,stroke:#525252,color:#ffffff
  class apps,applib app
  class services,subsys,libs system
  class drivers,kernel,soc base
```

From the bottom up:

[Kernel](https://developer.repebble.com/pebbleos/docs/kernel.md)

The kernel API the rest of the firmware is written against: threads, synchronization, timers, interrupts and memory. It hides the CPU architecture and the RTOS underneath.

[Drivers](https://developer.repebble.com/pebbleos/docs/drivers.md)

One driver class per kind of peripheral (display, accelerometer, flash, …), each with a common interface and an implementation per part, built on a shared device model.

[Subsystems](https://developer.repebble.com/pebbleos/docs/subsystems.md) and [libraries](https://developer.repebble.com/pebbleos/docs/libraries.md)

Self-contained building blocks used across the firmware, such as logging, the Bluetooth host integration, the debug shell, input handling and generic utilities.

[Services](https://developer.repebble.com/pebbleos/docs/services.md)

The system’s features: they own shared resources, persist state, talk to the phone and feed events to apps.

Application framework

`pebble/applib` is the API apps are written against, from windows and layers to graphics and text. Its exported part is the [Application SDK](https://developer.repebble.com/pebbleos/docs/sdk.md).

Apps

System apps (launcher, settings, notifications, health, …) are built into the firmware from `pebble/apps`; third-party apps and workers are installed from the phone.

The public interfaces of each layer live under `include/pbl/`, documented in the API reference. Code PebbleOS builds on but does not maintain is described in [Third-party](https://developer.repebble.com/pebbleos/docs/third_party.md).

## Execution model

The firmware runs a fixed set of tasks, each a kernel thread:

| 

Task

 | 

Role

 |
| --- | --- |
| 

KernelMain

 | 

The system’s event loop: input, UI and most services

 |
| 

SysWorkq

 | 

Deferred work kept off KernelMain

 |
| 

App

 | 

The foreground app or watchface

 |
| 

Worker

 | 

The app’s background worker, if it has one

 |
| 

Bluetooth host, controller, HCI

 | 

The Bluetooth stack

 |
| 

SysWorkqHigh

 | 

Timer callbacks

 |

Services and drivers post events to KernelMain, which handles them and forwards what concerns the app to the app’s own event queue. Only one app and one worker run at a time.

Third-party apps and workers run unprivileged, confined by the MPU to their own memory; whatever needs the system goes through a syscall. System apps run privileged. [How it works](https://developer.repebble.com/pebbleos/docs/sdk/how_it_works.md) describes the boundary.

## Boot

A bootloader, outside this tree, starts the firmware image in flash. The kernel’s reset handler sets up memory and the SoC, then starts the scheduler with `main()` (`pebble/main.c`) on the main thread, KernelMain. `main()` brings up the drivers and services and launches the first app, normally the watchface. [Boot](https://developer.repebble.com/pebbleos/docs/kernel/boot.md) details the early steps.

## Firmware variants

The same tree builds three firmwares:

- **Normal** : the full firmware.

- **Recovery (PRF)**: a minimal firmware kept in its own slot, from which the phone can reinstall the normal one when it does not start. It has no third-party apps and no JavaScript engine.

- **Manufacturing** : the recovery firmware with the factory test functions.

The variant, and everything else that is optional, is chosen at build time with Kconfig, from the board’s defconfig and the firmware’s configuration; see [Build system](https://developer.repebble.com/pebbleos/docs/development/build_system.md).

## Hardware support

A **board** describes one watch, or one revision of it: its SoC, its peripherals and the drivers they need. A **platform** is what apps see: display size, shape and colors, and capabilities. Boards of the same watch model share a platform, and the emulator provides a board for each platform. [Boards](https://developer.repebble.com/pebbleos/docs/boards.md) lists them.

Generated from PebbleOS [5285d4236](https://github.com/coredevices/pebbleos/commit/5285d423600370a73ae94b619748a69933107797). This page is maintained in the pebbleos repository: [docs/architecture/index.md](https://github.com/coredevices/pebbleos/blob/5285d423600370a73ae94b619748a69933107797/docs/architecture/index.md).
