pebble-firmware/docs/getting_started.md

🚀 Getting Started

Follow this guide to:

• Set up a command-line PebbleOS development environment
• Get the source code
• Build, flash, and run PebbleOS on a watch with programming port access

Pre-requisites

First download the Arm GNU toolchain arm-none-eabi 14.2.Rel1 from here. Make sure to make it available on your path PATH and then check GCC version is reported correctly:

$ arm-none-eabi-gcc --version
arm-none-eabi-gcc (Arm GNU Toolchain 14.2.Rel1 (Build arm-14.52)) 14.2.1 20241119
Copyright (C) 2024 Free Software Foundation, Inc.
This is free software; see the source for copying conditions.  There is NO
warranty; not even for MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.

A series of system-level dependencies are required. Follow the next steps to install them.

:::::{tab-set} :sync-group: os

::::{tab-item} Ubuntu 24.04 LTS :sync: ubuntu

1. Update package list:

   sudo apt update
   

2. Install required dependencies

   sudo apt install clang gcc gcc-multilib git gettext python3-dev python3-venv
   

::::

::::{tab-item} macOS :sync: macos

1. Install brew.

2. Link brew Python:

   brew link python@3
   

::::

:::::

If building with Javascript support enabled (default), install Emscripten:

:::::{tab-set} :sync-group: os

::::{tab-item} Ubuntu 24.04 LTS :sync: ubuntu

1. Install Emscripten SDK as detailed here. Pick version 4.0.7 instead of latest when running ./emsdk install or ./emsdk activate. To conveniently access Emscripten SDK tools, the activate command will offer some suggestions. It is recommended to follow them. ::::

::::{tab-item} macOS :sync: macos

1. Install Emscripten using brew:

   brew install emscripten
   

Note that brew does not seem to offer all Emscripten versions. Versions 4.0.x should work fine. If brew versions cause issues, consider using Emscripten SDK instead.

:::: :::::

Get the source code

You can clone the PebbleOS repository by running:

git clone --recurse-submodules https://github.com/pebble-dev/pebble-firmware

Once cloned, enter the pebble-firmware directory before continuing:

cd pebble-firmware

Python dependencies

A series of additional Python dependencies are also required. Follow the next steps to install them in a Python virtual environment.

1. Create a new virtual environment:

   python3 -m venv .venv
   

2. Activate the virtual environment:

   source .venv/bin/activate
   

   Remember to activate the virtual environment before every time you start working!
   

3. Install dependencies

   pip install -r requirements.txt
   

Building

1. Configure the project:

   ./waf configure --board $BOARD
   

where $BOARD is any of the supported boards, e.g. snowy_bb2, asterix, ...

1. Build:

   ./waf build
   

Flashing

You can flash the built firmware (including pre-compiled bootloader) by running:

./waf flash

If flashing for the first time, your watch will boot into a sad watch state, indicating that resources need to be flashed:

./waf image_resources

You will need to add --tty /path/to/serial/adapter if not using a big board with built-in FTDI.

At this point you should observe the watch booting into the main application. You can also see the logs by opening the console:

./waf console

Similarly, append --tty if needed.