DOCSEARCHbyAlgolia
Submit Docs

PebbleOS Documentation

repository·main·Indexed 22 days ago

https://github.com/coredevices/pebbleos

A core operating system and platform by Core Devices. It includes libOS for FreeRTOS on ARM, flash memory APIs (Main and Core Dump), and tools such as pbl-tool, pblconvert, and pebble.pulse2. The documentation covers resource generation, NimBLE configuration via the newt tool, font rendering, and activity tracking algorithms for step counting and Vector Magnitude Counts (VMC).

Tokens
28.8K
Snippets
48
Records
186
Agent score
76%

What's inside PebbleOS

  3. Overview of Resource Generation in PebbleOS

    main

    Resource Generation is a system designed to transform resource definitions into usable assets for PebbleOS. The system is built around several core design principles to ensure modularity and performance:

    • Decoupled Processing: Different resource types are processed in independent files to prevent monolithic complexity.
    • Platform Independence: The generation logic is decoupled from both the SDK and Firmware. Differences in behavior between SDK and Firmware variants are handled via parameters rather than explicit environment checks.
    • Native Execution: The system avoids shelling out to external processes, performing operations natively.
    • Filesystem-Centric State: Intermediate states are captured directly in the filesystem to avoid re-generating large data structures during every build.
    • Modular Definitions: Dynamically generated content (such as Bluetooth patches or stored apps) is kept separate from static resource definition JSON files to maintain modularity.

  4. Overview of the Pebble Font Renderer Script

    main
    The Pebble Font Renderer Script consists of Python scripts designed to process TrueType font files. The scripts render a specific set of glyphs and generate .h header files organized in a structure compatible with Pebble's text rendering routines.

  6. Understand the Activity Service code organization

    main

    The Health support logic is split between a privileged activity service and a user-land API.

    Core Files

    • src/fw/services/activity/activity.c: The main module. It provides the high-level API and glue logic. It is algorithm-agnostic and handles system-level tasks like subscribing to the accelerometer service.
    • src/fw/services/activity/activity_insights.c: Handles the generation of Health timeline pins and notifications.
    • src/fw/services/activity/kraepelin/kraepelin_algorithm.c: The core, OS-agnostic step and sleep algorithm (derived from Stanford Wearables Lab). It operates on indices of arrays rather than timestamps.
    • src/fw/services/activity/kraepelin/activity_algorithm_kraepelin.c: The wrapper that makes the core algorithm conform to the internal activity service API. It manages memory, persistent storage, and translates array indices into UTC timestamps.
    • src/fw/applib/health_service.c: The 3rd party (user-land) API. It makes calls into the privileged activity service to access raw step and sleep data.

  7. What is VMC (Vector Magnitude Counts)?

    main

    VMC (Vector Magnitude Counts) is a metric representing the overall amount of movement in the watch over time. Higher VMC values indicate more intense movement (e.g., running results in higher VMC than walking).

    Key characteristics of VMC:

    • Calibration: The VMC computation is calibrated to match the Actigraph device used in medical research.
    • Computation: Before calculation, each axis signal is passed through a bandpass filter (0.25Hz to 1.75Hz).
    • Data Availability: The algorithm computes both a 5-second VMC and a 1-minute VMC. The 1-minute VMC values are stored in persistent storage and are accessible to 3rd party applications via the Health API.
    • Medical Research: The 1-minute VMC values are specifically designed to be compatible with medical research standards.

  8. Understand Sparse Length Encoding (SLE) format

    main

    Sparse Length Encoding (SLE) is a run-length encoding format optimized for binary blobs containing long sequences of zero bytes mixed with incompressible data.

    Encoding Structure

    An SLE stream consists of:

    1. 1 header byte: An escape byte chosen by the encoder (the least frequent byte in the input, guaranteed to never be 0x00).
    2. Literal bytes: Data copied verbatim until an escape byte is encountered.
    3. Escape sequences: A 2–3 byte sequence starting with the escape byte:
      • ESC 0x00: End of stream.
      • ESC 0x01: A single literal escape byte.
      • ESC b (0x02 ≤ b ≤ 0x7f): A run of b zero bytes (length 2–127).
      • ESC b c (b ≥ 0x80): A run of ((b & 0x7f) << 8 | c) + 0x80 zero bytes (length 128–32895). Longer runs must be split into multiple sequences.

    Implementation Details

    • Single Zeros: A single isolated zero byte is emitted as a literal byte; SLE is only used for runs of 2 or more zeros.
    • Overhead: The minimum overhead for an empty stream is 3 bytes (header + end-of-stream sequence).

  9. Understand the PULSEv2 protocol suite

    main

    PULSE is the serial protocol used for communication between the PebbleOS firmware and host tooling (such as ./pbl console, flash imaging, and tools/pulse/). The protocol suite documentation covers:

    • PULSEv2: The core wire format and transport specifications.
    • Reliable Transport: Mechanisms for ensuring data integrity over the serial link.
    • Flash Imaging: The protocol used for writing images to the device.
    • Protocol History: Evolution and versioning of the PULSE protocol.

  10. Understand the Timezone database binary format

    main

    The PebbleOS timezone list is a binary resource identified by RESOURCE_ID_TIMEZONE_DATABASE. It is constructed from an IANA tzdata snapshot using tools/timezones.py and is consumed by the firmware service located at src/fw/services/timezone_database/service.c.

    The database uses a little-endian layout consisting of a 6-byte header, followed by region records, DST rules, and link records.

  11. Understand the Moddable JS Sandbox constraints

    main

    JavaScript applications (both normal applications and watchfaces) run within a lightweight sandbox that restricts access to certain JavaScript global variables and modules.

    Specifically, the sandbox prevents watchfaces from subscribing to Pebble hardware buttons. While PebbleOS also blocks these subscriptions, the sandbox is designed to throw an explicit exception rather than failing silently, providing clearer feedback to developers.

  12. Understand Pebble Draw Commands (PDC/PDCI/PDCS)

    main

    Pebble Draw Commands (PDC) is a vector-graphics format used by GDrawCommand to render images or animations at runtime via a sequence of stroke and fill commands.

    There are two primary file formats:

    • PDCI: A single static image.
    • PDCS: An animation sequence consisting of multiple frames.

    All multi-byte fields in these formats are little-endian. Files can be generated from SVG or JSON using tools/generate_pdcs/ and rendered to PNG using tools/pdc2png.