sync: merge upstream/main (2026-07-21) — NimBLE 1.10, picolibc, 78 commits

.agents/skills/working-with-qemu/SKILL.md

@@ -5,66 +5,13 @@ description: Use when building, launching, debugging, or capturing screenshots o
 
 # Working with QEMU
 
-PebbleOS can run under a custom QEMU version shipped with the PebbleOS SDK.
+Read `docs/development/qemu.md` — it documents the full workflow: qemu_*
+boards, `./pbl qemu` (monitor sockets, serial ports, uart1.log), `./pbl
+console`, `./pbl screenshot`, programmatic key input via `sendkey`, and
+`./pbl debug`.
 
-## Configure & build
+Agent notes:
 
-```sh
-./pbl configure --board $BOARD
-./pbl build
-```
-
-where `$BOARD` is any of the `qemu_*` boards:
-
-- `qemu_emery`
-- `qemu_flint`
-- `qemu_gabbro`
-
-QEMU boards target a specific platform, e.g. `qemu_emery` targets the Emery platform, which is the platform used by Pebble Time 2.
-
-## Launch
-
-```sh
-./pbl qemu
-```
-
-The launched QEMU exposes:
-
-- Interactive QEMU monitor on the launching terminal (`-monitor stdio`)
-- Programmatic socket monitor (`-monitor unix:build/qemu-mon.sock`)
-- Serial console over TCP on `localhost:12345` (console) and `localhost:12344` (pebble-tool)
-
-UART1 output is also captured to `build/uart1.log`.
-
-## Console
-
-```sh
-./pbl console
-```
-
-Requires QEMU to be running.
-Uses the TCP serial port to connect to the QEMU console, and provides a prompt for sending commands and receiving responses.
-
-## Screenshot
-
-```sh
-./pbl screenshot # defaults to build/screenshot.png
-./pbl screenshot --screenshot-output /tmp/foo.png
-```
-
-Requires QEMU to be running.
-Uses the programmatic socket monitor to capture a screenshot of the QEMU display and save it to disk.
-Useful to validate or iterate on UI changes.
-
-## Interaction
-
-Keyboard input is captured by QEMU, so you can interact with the PebbleOS UI.
-Keys can also be send programmatically over the socket monitor using the `sendkey` command.
-They key mapping is:
-
-| QEMU key | PebbleOS key |
-| -------- | ------------ |
-| `left`   | `back`       |
-| `right`  | `select`     |
-| `up`     | `up`         |
-| `down`   | `down`       |
+- Use `./pbl screenshot` to validate UI changes; read the resulting PNG.
+- Drive the UI over the socket monitor (`build/qemu-mon.sock`) with
+  `sendkey` rather than the interactive QEMU window.

.github/workflows/docs-linkcheck.yml

@@ -0,0 +1,30 @@
+# SPDX-FileCopyrightText: 2026 Core Devices LLC
+# SPDX-License-Identifier: Apache-2.0
+
+# Weekly sweep for dead external links in the documentation. Scheduled
+# rather than PR-gating so transient outages of third-party sites do not
+# block unrelated PRs.
+name: Docs Link Check
+
+on:
+  schedule:
+    - cron: "0 6 * * 1"
+  workflow_dispatch:
+
+jobs:
+  linkcheck:
+    runs-on: ubuntu-24.04
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v7
+
+      - name: Set up Python
+        uses: actions/setup-python@v7
+        with:
+          python-version: "3.13"
+
+      - name: Install dependencies
+        run: pip install -r docs/requirements.txt
+
+      - name: Check links
+        run: sphinx-build -b linkcheck docs _linkcheck

.github/workflows/release.yml

@@ -212,9 +212,7 @@ jobs:
           path: artifacts
 
       - name: Upload symbols to Memfault
-        # Only the upstream project has Memfault secrets; skip on forks so a
-        # release build doesn't fail on the missing org token.
-        if: github.repository == 'coredevices/PebbleOS'
+        if: ${{ github.repository == 'coredevices/PebbleOS' }}
         run: |
           pip install memfault-cli==${MEMFAULT_CLI_VERSION}
 
@@ -262,9 +260,7 @@ jobs:
           files: artifacts-*/*
 
       - name: Deploy Memfault release
-        # Only the upstream project has Memfault secrets; skip on forks so a
-        # release build stays green without them.
-        if: github.repository == 'coredevices/PebbleOS'
+        if: ${{ github.repository == 'coredevices/PebbleOS' }}
         run: |
           pip install memfault-cli==${MEMFAULT_CLI_VERSION}
 

.gitignore

@@ -55,12 +55,15 @@ analyze_mcu_flash_usage_treemap.jsonp
 
 .vscode
 .venv
+.cache/
 *.egg-info
 
 waflib.zip
 *~
 
 docs/_build
+docs/_apidoc
+doxygen-awesome-css/
 artifacts/
 
 .claude/settings.local.json

.gitmodules

@@ -40,3 +40,6 @@
 [submodule "third_party/picolibc"]
 	path = third_party/picolibc
 	url = https://github.com/picolibc/picolibc.git
+[submodule "third_party/mbedtls/mbedtls"]
+	path = third_party/mbedtls/mbedtls
+	url = https://github.com/Mbed-TLS/mbedtls.git

.readthedocs.yaml

@@ -7,18 +7,27 @@
 version: 2
 
 build:
-  os: ubuntu-24.04
+  os: ubuntu-26.04
   tools:
     python: "3.13"
+  apt_packages:
+    - doxygen
   jobs:
     post_checkout:
       # Skip build if there are no doc changes in a PR
       # Ref. https://docs.readthedocs.com/platform/stable/build-customization.html#cancel-build-based-on-a-condition
       - |
-        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ .readthedocs.yaml;
+        if [ "$READTHEDOCS_VERSION_TYPE" = "external" ] && git diff --quiet origin/main -- docs/ include/ lib/ src/ subsys/ Doxyfile Doxyfile.rtd .readthedocs.yaml;
         then
           exit 183;
         fi
+    pre_build:
+      # Build the Doxygen API reference, published under /apidoc/ via
+      # html_extra_path (see docs/conf.py)
+      # v2.4.2, pinned by commit
+      - git clone https://github.com/jothepro/doxygen-awesome-css.git &&
+        git -C doxygen-awesome-css checkout d52eafe3e9303399fda15661f3d7bb8fe3d7eabc
+      - doxygen Doxyfile.rtd
 
 sphinx:
     configuration: docs/conf.py

AGENTS.md

@@ -8,6 +8,7 @@ PebbleOS is the operating system running on Pebble smartwatches.
 - `resources`: firmware resources (icons, fonts, etc.)
 - `sdk`: application SDK generation files
 - `src`: firmware source
+- `subsys`: OS subsystems, e.g. logging
 - `tests`: tests
 - `third_party`: third-party code in git submodules, also includes glue code
 - `tools`: a variety of tools or scripts used in multiple areas, from build
@@ -16,6 +17,14 @@ PebbleOS is the operating system running on Pebble smartwatches.
   console, etc.
 - `tools/waf`: scripts used by the waf build system
 
+## Documentation
+
+Contributor documentation lives in `docs/` (published at
+https://pebbleos-core.readthedocs.io). Prefer pointing to or extending those
+pages over duplicating knowledge here: `docs/development/contributing.md`
+(DCO, commit and AI-usage rules), `docs/development/sdk_export.md` (SDK
+export machinery), `docs/development/qemu.md` (emulator workflow).
+
 ## Code style
 
 - clang-format for C code
@@ -48,27 +57,11 @@ PebbleOS is the operating system running on Pebble smartwatches.
 
 ## Adding a new SDK function
 
-When exposing a new function to third-party apps (i.e. anything declared
-in an `applib/` header that user apps can call), three things must change
-together — the firmware build alone won't surface it to apps:
-
-1. **Implement the applib wrapper and syscall** — add the function to the
-   appropriate `src/fw/applib/.../<area>.c/.h`, declare the syscall in
-   `src/fw/syscall/syscall.h`, and define it with `DEFINE_SYSCALL` in
-   `src/fw/syscall/syscall_<area>.c`.
-2. **Register the symbol** in
-   `tools/generate_native_sdk/exported_symbols.json` under the matching
-   group, with an `addedRevision` matching the new SDK revision.
-3. **Bump the SDK revision** in
-   `src/fw/process_management/pebble_process_info.h`: increment
-   `PROCESS_INFO_CURRENT_SDK_VERSION_MINOR` and add a `// sdk.major:0xN
-   .minor:0xM -- <description> (rev <N+1>)` comment line above the
-   `#define`. The revision number in the comment must match
-   `addedRevision` from step 2.
-
-Forgetting steps 2 or 3 means the function compiles into the firmware
-but is invisible to the app SDK build, so third-party apps can't link
-against it.
+Exposing a function to third-party apps requires three coordinated changes
+(applib wrapper + syscall, `exported_symbols.json` registration, SDK
+revision bump) — the firmware build alone won't surface it to apps. Follow
+`docs/development/sdk_export.md` whenever an `applib/` function should
+become callable from user apps.
 
 ## Git rules
 

CONTRIBUTING.md

@@ -2,6 +2,10 @@
 
 Thank you for your interest in contributing to PebbleOS! We welcome contributions of all kinds, including bug fixes, new features, documentation improvements, and more. To ensure a smooth contribution process, please follow the guidelines outlined below.
 
+Developer documentation — building the firmware, running it in QEMU, exporting
+SDK functions, and more — lives in the `docs/` directory and is published at
+<https://pebbleos-core.readthedocs.io>.
+
 ## Developer Certification of Origin (DCO)
 
 To make a good faith effort to ensure licensing criteria are met, this