Applicability and identity

This page applies to protocol_version 1 in the backend and firmware proto/lilbuddy.proto copies. The two source paths are byte-identical and have SHA-256 dc64fe8a840f917fab36b710069ab46d0872068a57ef1d3bb21ba030f8948497. The backend source is commit f03ae1c7ab31c2856a96cb4e3325d81494c0f8d3; the firmware source is commit a0dd93ba02a6eb162b814fafb5921c49767b8e0a.

Connection routes

ConnectionRoute names the transport state, not a guarantee that a route is available:

• NEARBY is the local phone/device path, normally BLE in the cited Android and firmware implementations.
• RELAYED is phone-assisted delivery through a configured relay and route lease.
• CLOUD is the configured cloud/device path, including optional Wi-Fi/MQTT delivery.
• OFFLINE means no active route is available; callers must apply the operation’s retry semantics rather than assuming delivery.

Frames identify protocol version, session and message IDs, sequence and acknowledgement values, signer identity, and a payload. Payloads include typed device requests/responses, control requests/responses, events, capabilities, pairing messages, route proofs, and transfer messages.

Pairing and local providers

PairingHello carries a phone identity and nonce during commissioning. PairingGrant carries the signed grant for an approved phone. The device emits LocalPairingAccepted after it stores the local controller and proves the device identity. The approval is device-authoritative.

LocalProviderRegistration advertises an available local provider by contract ID and major version. LocalProviderRequest and LocalProviderResponse carry an operation and opaque contract payload between the device runtime and the nearby provider. An unavailable or mismatched provider is a bounded failure, not an implicit cloud fallback.

Transfers

TransferBegin, TransferData, TransferAck, and TransferFinalize describe bounded, resumable transfers. Transfer kinds include face artifacts, applet bundles, and OTA images. BlobChunk provides a chunked payload with offset, total size, digest, and final-marker semantics. Callers must honor the returned offset, credit, error, and retry class.

The protocol documentation contains no keys, tokens, credentials, Wi-Fi passwords, live identifiers, or private service locations.