Wire protocol

Messages

A message is a 4-byte header followed by its payload. Header fields are big endian:

Messages follow each other with nothing in between: the stream carries no other framing, and a link may split it anywhere. Payloads are in each endpoint’s own format, most of them little endian.

Endpoints

Private endpoints only accept messages from the Pebble mobile app, on a system or hybrid session; any endpoints also accept them from third party phone apps. The watch sends on any endpoint, including ones it does not receive on.

Meta endpoint

The watch answers a message it cannot take on the meta endpoint, and drops its payload:

Messages the watch accepts but has no room for, such as a large message while the kernel heap is short, are dropped without a response.

Version and capabilities

As soon as a session opens, the watch asks the phone for its version on the remote version endpoint, 0x0011. The phone’s answer sets the session’s capabilities, which code checks before using features the phone may lack. Transports that know their peer up front, the console and QEMU, set capabilities when they open the session, and the answer replaces them.

        sequenceDiagram
  participant W as Watch
  participant P as Phone
  Note over W: session opens
  W->>P: 0x0011 [0x00] version request
  P->>W: 0x0011 [0x01, response]
  Note over W: set capabilities,<br/>PBL_PP_SESSION_CAPABILITIES,<br/>PEBBLE_REMOTE_APP_INFO_EVENT (system only)
    

The phone asks for the watch’s versions the same way, on the system version endpoint, 0x0010.

The response comes in three versions, told apart by their length. Each extends the previous one:

The 1.x Android app repeats its response, so a v1 response may be as long as a v2 one; it then has no capabilities. A response shorter than v1 is ignored.

The phone OS, enum pbl_pp_remote_os, is unknown (0), iOS (1), Android (2), macOS (3), Linux (4) or Windows (5). It reaches the rest of the firmware in PEBBLE_REMOTE_APP_INFO_EVENT.