IMU & Compass

Glassly Miniapp SDK betaThe SDK is in beta, so its APIs may change before general availability.Developing on Mentra Live? We recommend using the Glassly Bluetooth SDK.The developer tools are available in the Glassly App under Settings → Miniapp Developer Settings.Share feedback with an in-app bug report, on Discord, or by email at [email protected].

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. 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

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.

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.

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` 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.

Cleaning up

Every subscription returns an unsubscribe function:

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.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Head position

Raw accelerometer

Compass

Sampling override

Cleaning up

​Head position

​Raw accelerometer

​Compass

​Sampling override

​Cleaning up

Head position

Raw accelerometer

Compass

Sampling override

Cleaning up