Sessions

"Session" means two related things in Extentos, depending on the transport. On real glasses it's the connection between your app and the hardware, modeled by a six-state machine you observe through glasses.connection.state. In the browser simulator it's additionally a backend session that multiple parties join with distinct roles. This page covers both, plus what survives backgrounding and reconnects.

The connection-state machine

glasses.connection.state is a StateFlow<GlassesState> (Android) / ObservableState<GlassesState> (iOS). GlassesState is a sealed type with six buckets, advancing roughly in order from "not set up" to "connected", with Disconnected reachable from anywhere:

NotRegistered ─▶ Registered ─▶ DeviceDiscovered ─▶ Connecting ─▶ Active
      ▲                                                              │
      └──────────────────── Disconnected(cause) ◀────────────────────┘
                                   (reachable from any state)

Active is the "transport is up" state — necessary for using the glasses, but not sufficient, and not a signal that glasses are present. On the vendorless audio baseline it is reported whenever audio is routable — which the phone's own mic and speaker always satisfy — so it does not by itself tell you a camera exists. Gate on state == Active and the capability: glasses.capabilities.camera. See choose your path. The transitions are driven by the transport — your code observes; it doesn't drive the machine by hand (you nudge it only via connect() / disconnect() / reconnect()).

Disconnected.cause is the actionable part — it distinguishes "the user took the glasses off" from "Bluetooth dropped" from "the simulator session expired," so you can choose the right recovery. The full branch-on-cause pattern, the retry policy, and the reconnect call live in Handle disconnects; the complete DisconnectCause and ConnectError payload shapes are in the error reference.

You rarely render this machine yourself. ExtentosConnectionPage renders the canonical pairing → connecting → connected → disconnected flow from this exact state. Observe glasses.connection.state directly only for custom in-app affordances (e.g. disabling a button while not Active).

What persists

The ExtentosGlasses instance is the durable object — construct one at app init (in your Application subclass / App) and hold it for the app's lifetime. It owns the transport, the auto-bind probe, the connection state, registration, and telemetry hooks. Constructing more than one is a bug: there's no caching, and each fires its own auto-bind probe and telemetry registration.

• Across reconnects: reconnect() re-runs registration and re-fetches device metadata (name, firmware, link state), then the state flips back to Active. Toggle state (glasses.toggles) and your registered voice phrases / assistant configuration are held by the library across the drop — you don't re-register them.
• Across app backgrounding: whether the connection survives backgrounding depends on platform plumbing — an Android foreground service or iOS background mode. That setup is its own topic: see Background sessions. Without it, the OS may tear the connection down when your app leaves the foreground, surfacing as a Disconnected.
• What does NOT persist on the device: the event log is a 512-entry ring buffer — it's mirrored to the backend during simulator mode but is not durable storage on the glasses. Assistant conversation history is an in-memory replay buffer (replayed to the provider on reconnect), not disk-persisted by the SDK; if you need it across app restarts, you persist it yourself.

Simulator sessions and roles

The browser simulator adds a second sense of "session": a backend session, identified by a sessionId, that more than one party joins. Where a real-glasses session is a 1:1 link between your app and hardware, a simulator session is a small hub with three roles (transport vs app simulation):

The app and browser roles are singletons per session (one each); observers are the only multi-party role.

hardware_ready gating

Because the surrogate (the browser role) is the simulated hardware, a simulator session isn't usable until that surrogate has joined and acknowledged. The backend tracks a hardware_ready flag and only flips it true once the browser surrogate is present and ack'd; it then fans hardware_ready out to the app and any observers. Until then, the app side behaves as "hardware not present" — the analogue of Connecting on real glasses. This is what makes the simulator faithful: there's no app-layer behavior available before the (simulated) hardware is ready, exactly as on glasses.

Simulator sessions also carry per-device facts the app reacts to — for example display_capable is true only on display-capable device models (Ray-Ban Display), so a display feature lights up in the simulator only against the right device. When a simulator session ends (idle timeout, lifetime cap, user-ended, backend restart), the app sees Disconnected(SimulatorSessionExpired(reason, …)) — a simulator-only DisconnectCause you won't encounter on hardware.

The same code on both

The point of the connection-state machine is that it's transport-independent: your handler code observes glasses.connection.state and calls glasses.camera.capturePhoto() identically whether the transport underneath is BrowserSimTransport, LocalSimTransport, or RealMetaTransport. The simulator is designed to behave like the glasses, and that fidelity is under active validation on hardware — so a session that's green in the simulator is strong evidence — the final gate is a real-hardware run. The substrate deltas (transport, audio format, STT/TTS provider) are contained at the transport layer; the session model your app sees is the same on both. See Transport vs app simulation for exactly what differs.

Related

• Handle disconnects — branching on Disconnected.cause, reconnect, and retry policy.
• Background sessions — keeping the connection alive when backgrounded.
• Transport vs app simulation — the transports and what the simulator simulates.
• Error reference — GlassesState, DisconnectCause, and ConnectError payloads.

Related