docs: add getting started guide

Signed-off-by: Gerard Marull-Paretas <gerard@teslabs.com>

docs/getting_started.md

@@ -0,0 +1,148 @@
+# 🚀 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
+
+## Get the source code
+
+You can clone the PebbleOS repository by running:
+
+```shell
+git clone --recurse-submodules https://github.com/pebble-dev/pebble-firmware
+```
+
+Once cloned, enter the `pebble-firmware` directory before continuing:
+
+```shell
+cd pebble-firmware
+```
+
+## Pre-requisites
+
+First download the Arm GNU toolchain 14.2.Rel1 from [here](https://developer.arm.com/downloads/-/arm-gnu-toolchain-downloads).
+Make sure to make it available on your path `PATH`.
+
+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
+:sync: ubuntu
+
+1. Update package list:
+
+```shell
+sudo apt update
+```
+
+2. Install required dependencies
+
+```shell
+sudo apt install gcc-multilib gettext python3-venv
+```
+
+::::
+
+::::{tab-item} macOS
+:sync: macos
+
+1. Install [brew](https://brew.sh/).
+
+::::
+
+:::::
+
+If building with Javascript support enabled (default), install Emscripten:
+
+:::::{tab-set}
+:sync-group: os
+
+::::{tab-item} Ubuntu 24.04
+:sync: ubuntu
+
+1. Install Emscripten SDK as detailed [here](https://github.com/emscripten-core/emsdk).
+   Pick version 4.0.1.
+::::
+
+::::{tab-item} macOS
+:sync: macos
+
+1. Install Emscripten using `brew`:
+
+```shell
+brew install emscripten@4.0.1
+```
+
+::::
+:::::
+
+A series of additional Python dependencies are also required.
+Follow the next steps to install them in a [Python virtual environment](https://docs.python.org/3/library/venv.html).
+
+1. Create a new virtual environment:
+
+```shell
+python -m venv .venv
+```
+
+2. Activate the virtual environment:
+
+```shell
+source .venv/bin/activate
+```
+
+```{tip}
+Remember to activate the virtual environment before every time you start working!
+```
+
+3. Install dependencies
+
+```shell
+pip install -r requirements.txt
+```
+
+## Building
+
+1. Configure the project:
+
+```shell
+./waf configure --board $BOARD
+```
+
+where `$BOARD` is any of the supported boards, e.g. `snowy_bb2`, `asterix_evt1`, ...
+
+2. Build:
+
+```shell
+./waf build
+```
+
+## Flashing
+
+You can flash the built firmware (including pre-compiled bootloader) by running:
+
+```shell
+./waf flash
+```
+
+If flashing for the first time, your watch will boot into a _sad watch_ state, indicating that resources need to be flashed:
+
+```shell
+./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:
+
+```shell
+./waf console
+```
+
+Similarly, append `--tty` if needed.

docs/index.md

@@ -1 +1,6 @@
 # Welcome to the PebbleOS documentation!
+
+```{toctree}
+:hidden:
+getting_started.md
+```