# IMU & Compass

> Head position, raw accelerometer, and compass heading from the glasses.

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

`session.imu` reports which way the wearer is looking. The glasses' inertial
measurement unit resolves head pose into two states, `"up"` and `"down"`, and
fires an event each time that state changes. Use it to wake content when someone
glances up, or to dismiss it when they look back down. `session.compass` reports
which way they are facing, as a magnetic heading in degrees.

This module needs the `IMU` hardware requirement in your
[manifest](https://docs.dev.glassly.ai/app-devs/core-concepts/miniapp-manifest.md). Mark it `REQUIRED` and
glasses without an IMU won't list your miniapp; mark it `OPTIONAL` and they still
run it without head-position events. There is no runtime permission to request.

## Head position

Head position is an input like a tap: the glasses report `head_up` when the
wearer lifts their head past the head-up angle and `head_down` when it returns,
and both go through the gesture claims (`session.input.setClaimedGestures`).
The dashboard claims them while it runs, so claim them yourself to receive them
while it is up. `imu.onHeadPosition` is a convenience over
`input.onTouch(["head_up", "head_down"], handler)`.

```typescript src/background/index.ts
const off = session.imu.onHeadPosition(({ position }) => {
  if (position === "up") session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: "Welcome back"}]);
  else session.display.render([]);
});
```

Each `HeadPositionData` has:

| Field | Type | Notes |
|---|---|---|
| `position` | `"up" \| "down"` | The new head pose. Fires on each transition, not continuously. |

## Raw accelerometer

`onAccel` streams raw accelerometer readings, `{x, y, z}` in g plus a timestamp.
This is G2-only today. On glasses without an exposed IMU stream the subscription
succeeds and no events arrive.

```typescript src/background/index.ts
const off = session.imu.onAccel(({ x, y, z, timestamp }) => {
  // x, y, z in g; timestamp is Unix ms.
});
```

Each `AccelData` has:

| Field | Type | Notes |
|---|---|---|
| `x`, `y`, `z` | `number` | Accelerometer axes in g (gravity-normalized). |
| `timestamp` | `number` | Unix ms timestamp of the reading. |

Subscribing turns the sensor on and unsubscribing turns it off, so most callers
never touch it directly. `session.imu.setEnabled(true)` drives the sensor by hand
when you want to, for instance, a diagnostic toggle. It's a no-op on glasses
without an exposed IMU stream.

Gyroscope and raw magnetometer XYZ aren't exposed yet.

## Compass

`session.compass.onUpdate()` streams the glasses' fused magnetic heading.
Subscribe like any other stream: the phone runs the sensor while at least one
miniapp is subscribed and stops it when the last one leaves.

```typescript src/background/index.ts
const off = session.compass.onUpdate(({ degrees }) => {
  session.display.render([{type: "text", id: "msg", box: {x: 0, y: 0, w: 576, h: 288}, text: `${Math.round(degrees)}°`}]);
});
```

What you get depends on the firmware:

| Glasses | Behavior |
|---|---|
| G2 custom firmware (Glassly CFW, upstream g2flash) | The raw compass starts on subscribe at 1000 ms / 5°. `diagnostics` is present. |
| G2 stock firmware | Headings arrive only while the glasses' native navigation UI is open, during a [`session.navigation`](https://docs.dev.glassly.ai/app-devs/core-concepts/navigation.md) trip. |
| Other glasses | The subscription succeeds and no events arrive. |

Each `CompassData` has:

| Field | Type | Notes |
|---|---|---|
| `degrees` | `number` | Magnetic heading, `0` = north, `90` = east. Fused heading, not raw magnetometer XYZ. |
| `timestamp` | `number` | Phone reception time, Unix ms. |
| `diagnostics` | `CompassDiagnostics?` | Custom firmware only: `accuracy` (0–3 or null), `anomalies` (0–2 or null), `source`, per-source validity, `magneticDataFresh`, and `sampleTimestampMs` (firmware uptime, wraps at 2^32 ms). |

`session.compass.onCalibration()` fires `{status: "start" | "complete"}` when the
firmware recalibrates. Ask the wearer to look around until it completes.

### Sampling override

`session.compass.start({intervalMs, minChangeDegrees})` records the sampling
this miniapp wants. Everyone subscribed is served the **smallest** interval and
the **smallest** change threshold requested across miniapps, so one miniapp
asking for 50 ms speeds up every subscriber. `stop()` drops your override; live
subscriptions keep the sensor running. Both are custom firmware only.

| Option | Range | Default |
|---|---|---|
| `intervalMs` | 50–2000 ms | 1000 |
| `minChangeDegrees` | 0–359° | 5 |

For the phone's own compass, see
[`session.phone.heading`](https://docs.dev.glassly.ai/app-devs/core-concepts/phone.md#phone-heading).

## Cleaning up

Every subscription returns an unsubscribe function:

```typescript
const off = session.imu.onHeadPosition(handler);
off(); // stop listening
```

Subscriptions are ref-counted, so the SDK only talks to the phone on the first
subscribe and last unsubscribe of a stream.
