One command model, several routes

LilBub separates an operation from the transport carrying it. A brightness change, face preview, system query, or applet message has typed request, response, sequence, and acknowledgement semantics. The connection coordinator then selects an available route.

Nearby
  Android <-> BLE <-> LilBub

Phone-assisted
  Backend <-> WebSocket <-> Android <-> BLE <-> LilBub

Direct cloud
  Backend <-> MQTT over mutual TLS <-> LilBub

Device management
  Browser or Android <-> HTTPS API <-> Backend

The diagram shows four relationships. Nearby work stays between the approved Android companion and the device. A phone-assisted route extends that session to the backend through a WebSocket. A direct cloud route uses the device’s Wi-Fi and MQTT client certificate. Browser and Android account operations enter through the HTTPS API rather than connecting directly to the broker or database.

Route meanings

Protocol version 1 names four connection states:

• NEARBY carries work through the approved local phone/device session.
• RELAYED carries backend-authorized work through an active phone route.
• CLOUD carries work through the configured direct device route.
• OFFLINE means that no eligible route is currently available.

Callers must handle the returned route and retry classification. They must not infer device application merely from a successful request to the API.

Nearby route

Nearby pairing establishes phone and device identities, explicit approval, and a signed session. The session uses sequence and replay checks and advertises the capabilities available on that connection.

BLE is only the carrier. The application approval is LilBub’s signed handshake, not an unrelated operating-system bond. The device remains authoritative about which phone identities may control it.

Phone-assisted route

An authenticated Android companion can request a short-lived relay ticket and activate a route lease. The phone holds a WebSocket to the relay and the signed device session over BLE. Backend work travels across both links.

The route becomes usable only after the device accepts the signed backend work. The firmware then suppresses the direct MQTT application path while the phone route is active. This avoids two simultaneous command owners while leaving Wi-Fi associated for fallback.

Route tickets and leases expire. Redis stores their bounded coordination state; it does not become long-term device or account storage.

Direct cloud route

The direct route requires:

1. device-authoritative cloud services enabled;
2. station Wi-Fi;
3. a completed cloud link;
4. a device MQTT client identity and broker trust chain; and
5. reachable API and broker services.

The device connects to the broker using mutual TLS, subscribes to its downlink, publishes uplinks, and renews presence. Backend publications are routed to the device-specific path allowed by broker policy.

The device’s MQTT identity is separate from the backend broker identity. A cloud link provisions device credentials without placing backend service credentials in firmware.

HTTPS wakeup

After joining Wi-Fi, the device sends an identity-signed HTTPS wakeup. The backend records current state and returns desired account-linked configuration. The device also synchronizes its applet inventory through an authenticated HTTPS request.

The cited firmware serializes large TLS work: it pauses MQTT while performing HTTPS wakeup, applet synchronization, certificate refresh, or OTA work, then returns to MQTT. This is an ESP32-S3 memory-management decision, not a change in the logical route.

Presence is a lease

Online presence is ephemeral. The device publishes a retained status and periodic heartbeat; the backend maps that signal into a bounded Redis lease. Disconnect or lease expiry moves the user experience to offline.

Presence answers “is a route probably available?” It does not prove that a specific command reached the device. Product flows that need completion wait for the matching firmware acknowledgement.

Trace a command from button to Bub

Consider a web Face Studio preview:

1. The browser authenticates to the API and asks to start a live face session.
2. The backend verifies ownership and current route state.
3. The browser opens the authorized session socket.
4. Each preview frame is validated and routed through the active phone-assisted or direct cloud path.
5. Firmware applies the transient preview and sends a matching response.
6. The backend returns that acknowledgement to the live session.
7. Ending the session tells firmware to leave preview state.

The saved face and the live preview have different semantics. A transient preview must not silently become persistent configuration.

Applet integration relay

Applet service traffic uses a relay envelope with visible routing metadata and an encrypted application payload. The relay needs identifiers such as device, applet instance, contract, operation, correlation, and key IDs to route the message. The service payload is protected end to end for the bound integration.

Redis coordinates expiring routes, replay protection, and cross-instance delivery. MQTT carries the device side. Supabase stores approved integration and binding records through the backend.

Component ownership

Component	Owns	Does not own
LilBub	Connectivity policy, device identities, local settings, command application	Account authorization for other users
Android companion	Approved nearby identity, phone-local content, optional relay session	Broker administration
Browser	User interaction and ephemeral session state	Device or service credentials
Go API	Authorization, orchestration, route selection, database access	Physical device approval
Relay	Authenticated sockets and bounded message routing	Long-term account or device state
MQTT broker	Authenticated device message transport and topic policy	Account persistence
Redis	Expiring presence, tickets, leases, replay, and coordination	Durable product records
Supabase	Configured authentication and persistent backend data	Direct device control

Failure behavior

Failures should remain attributable:

• No BLE session means the nearby route is unavailable.
• No active phone lease means phone-assisted delivery is unavailable.
• No Wi-Fi or valid broker identity means direct cloud delivery is unavailable.
• No Redis means tickets, presence, and route coordination cannot be trusted.
• No Supabase dependency means account-backed API work cannot be authorized or persisted.
• No device acknowledgement means the caller cannot claim application.