# Light Sensor

> Ambient light readings from the glasses, on G2 and MemoMind One custom firmware.

Source: https://docs.dev.glassly.ai/app-devs/core-concepts/light-sensor/

`session.lightSensor` reads the ambient light sensor on the glasses. It needs
custom firmware: the G2 (Glassly CFW or upstream g2flash) or the MemoMind One
(Glassly CFW). Stock firmware and other glasses reject its control requests.

```typescript src/background/index.ts
const off = session.lightSensor.onUpdate((reading) => {
  session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: `light ${reading.value}`}]);
});
await session.lightSensor.start({intervalMs: 500});
```

Subscribing only delivers events. Polling starts and stops explicitly, and
unsubscribing alone leaves the hardware running until `stop()` or the miniapp
closes.

## Reading light

`query()` asks for the driver's cached value without opening the sensor. The
answer arrives through `onUpdate()` with `reason: "query"` and may be stale.

`start(options?)` polls the sensor and, on the G2, pauses the stock automatic
brightness adjustments while polling. Calling it again re-applies new options.
`stop()` restores stock behavior without changing the brightness setting.

| Option | Range | Default |
|---|---|---|
| `intervalMs` | 100–5000 ms | 500 |
| `minDelta` | 0–65535 firmware ALS units | 1 |
| `heartbeatMs` | 0–65535 ms; `0` disables unchanged reports | 5000 |

Each `LightSensorData` has:

| Field | Type | Notes |
|---|---|---|
| `reason` | `"query" \| "started" \| "poll" \| "stopped"` | Why this report was sent. |
| `value`, `peak` | `number` | G2: stock ALS units, roughly tenths of lux, not calibrated lux. MemoMind One: the firmware's normalized light level, 0–1000. |
| `targetLevel`, `brightness`, `gear`, `scaleQ10`, `status` | `number` | Stock brightness pipeline state. MemoMind One reports only `brightness` (0–100); the others are fixed. |
| `opened`, `passive`, `autoBrightness`, `readSucceeded` | `boolean` | Driver flags. Check `readSucceeded` before trusting `value`. |
| `sampleTimestampMs` | `number` | Firmware uptime, wraps at 2^32 ms. Never compare with Unix time. |
| `timestamp` | `number` | Phone reception time, Unix ms. |

## MemoMind One

The MemoMind One firmware buffers its light readings and the phone polls that
buffer, never faster than every 500 ms, applying `minDelta` and `heartbeatMs`
itself; a reading can trail the sensor by up to one poll. On Glassly CFW
revision 14 the glasses sample the sensor at `intervalMs` themselves; on
revisions 10 to 13 they only buffer the stock reader's roughly once-a-second
samples, which stop while auto-brightness is off. Polling does not depend on the
miniapp display on these glasses.

## Ownership

One miniapp controls the sensor at a time. Others can observe readings but
cannot reconfigure or stop it; their `start()` and `stop()` reject with
`INVALID_ARGUMENT`. Closing the owning miniapp releases the sensor. A
[`session.navigation`](https://docs.dev.glassly.ai/app-devs/core-concepts/navigation.md) trip on the glasses
temporarily takes the sensor back and polling resumes afterward.

Polling is bound to the custom firmware's display lease: opening a stock screen
on the glasses or letting the miniapp display go idle stops polling. Call
`start()` again when your content returns.

Successful delivery of a command is not proof of a fresh sample. `start()`
rejects with `INTERNAL` when the firmware refuses or never acknowledges it, for
example on stock firmware or without an active miniapp display.

## Cleaning up

```typescript
await session.lightSensor.stop();
off(); // stop receiving reports
```
