Build a dashboard

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

The dashboard is the screen the wearer summons with a head-up or a double tap on an empty display. It is a miniapp. The one bundled with the Glassly App, com.glassly.dashboard, uses only the public Glassly Miniapp SDK, so a dashboard you write can do everything it does. One installed dashboard holds the dashboard role at a time. The wearer picks it in the Glassly App under Settings > Dashboard > Dashboard app; the picker appears once a second dashboard is installed.

Manifest

Set type to "dashboard" and declare the permissions for the features you build. The type makes your miniapp eligible for the role and grants nothing else.

miniapp.json

{
  "packageName": "com.example.hud",
  "name": "Minimal HUD",
  "type": "dashboard",
  "alwaysOn": true,
  "entry": {"background": "background/index.js", "ui": "ui/index.html"},
  "permissions": [
    {"type": "READ_NOTIFICATIONS", "description": "Shows phone notifications on the glasses"},
    {"type": "MANAGE_MINIAPPS", "description": "Starts and stops miniapps from the menu"},
    {"type": "PLATFORM_SETTINGS", "description": "Edits the notification and glasses menu settings"}
  ],
  "hardwareRequirements": [{"type": "DISPLAY", "level": "REQUIRED"}]
}

alwaysOn starts the miniapp when the Glassly App launches. A dashboard that does not hold the role is not started this way.

What the role gives you

While your miniapp holds the role and the glasses can show the dashboard view (currently a G2 running Glassly CFW with the dashboard enabled):

session.capabilities.display.views includes "dashboard".
session.display.showView("dashboard") takes the overlay slot above the main content, and frames rendered with {view: "dashboard"} reach the glasses.
If you subscribe to phone notifications, you are the notification viewer: the host and the firmware leave presentation to you.

On glasses that cannot show the dashboard view, glasses with their own notification centre present notifications themselves. On the rest, the host draws a notification card (and reads it aloud on glasses without a display) on your behalf while you run and declare READ_NOTIFICATIONS. Without the role your miniapp is an ordinary miniapp: views is ["main"] and showView("dashboard") resolves {status: "unsupported", reason: "not the active dashboard"}. Watch session.onCapabilitiesChange and release your gesture claims when the dashboard view goes away.

A minimal dashboard

src/background/index.ts

import {registerMiniapp} from "@glassly/miniapp/background";

registerMiniapp((session) => {
  let open = false;
  const eligible = () => session.capabilities?.display?.views?.includes("dashboard") === true;

  const draw = () =>
    session.display.render(
      [{type: "text", id: "clock", box: {x: 24, y: 24, w: 300, h: 40}, text: new Date().toLocaleTimeString()}],
      {view: "dashboard"},
    );

  const show = async () => {
    if (!eligible() || open) return;
    const result = await session.display.showView("dashboard");
    if (result.status !== "shown") return;
    open = true;
    // Every gesture is yours while the page shows.
    await session.input.setClaimedGestures(["double_tap", "single_tap", "swipe_up", "swipe_down"], {scope: "page"});
    await draw();
  };

  const hide = async () => {
    open = false;
    await session.input.setClaimedGestures([], {scope: "page"});
    await session.display.showView("main");
  };

  // The shortcut that opens the dashboard on an empty screen.
  const claimShortcut = () => session.input.setClaimedGestures(eligible() ? ["double_tap"] : []);
  void claimShortcut();
  session.onCapabilitiesChange(() => void claimShortcut());

  session.input.onTouch((touch) => {
    if (touch.kind === "double_tap") void (open ? hide() : show());
  });
  session.imu.onHeadPosition(({position}) => {
    if (position === "up") void show();
    else if (open) void hide();
  });

  // The slot was released, lost with the role, or the glasses stopped being eligible.
  session.display.onViewChange(({view}) => {
    if (view === "main" && open) {
      open = false;
      void session.input.setClaimedGestures([], {scope: "page"});
    }
  });
});

See Display for the view rules and Input for gesture claims and scopes.

What the bundled dashboard uses

Feature	API	Permission
Overlay pages	`session.display.showView`, `render(..., {view: "dashboard"})`, `onViewChange`	the dashboard role
Open and close gestures	`session.input.setClaimedGestures`, `onTouch`	none
Head-up, when the wearer’s `contextual_dashboard` setting allows	`session.imu.onHeadPosition`, `session.settings`	`PLATFORM_SETTINGS` for the setting
Glasses battery	`session.glasses.onBattery`	none
Ring battery, phone in use, miniapp on screen	`session.settings` keys `ring_battery`, `phone_active`, `foreground_app_on_screen`	`PLATFORM_SETTINGS`
Calendar	`session.phone.calendar.listEvents`	`CALENDAR`
Notification popups and viewer	`session.phone.notifications.on`, `onDismissed`	`READ_NOTIFICATIONS`
Per-app notification filter	`session.phone.notifications.installedApps`	`READ_NOTIFICATIONS`
Side menu of miniapps	`session.miniapps.list`, `start`, `stop`	`MANAGE_MINIAPPS`
Notification, Glasses Menu and clock settings	`session.settings.get`, `set`, `onChange`	`PLATFORM_SETTINGS`
Its own look (widget layout, clock style)	`session.storage`	none
Text measuring and pixel art	`@glassly/miniapp/display`, `@glassly/miniapp/known-apps`	none

The page system that switches between its dashboard, side menu, calendar and notification pages is its own code. Write the one that suits your design.

Settings you own

The active dashboard’s phone page is where the wearer edits the notification settings, the per-app notification filter and the Glasses Menu. The Glassly App has no screens of its own for them. If your dashboard replaces the bundled one, build those screens on session.settings or the wearer cannot change them while yours holds the role. Read active_dashboard from session.settings to tell the wearer when your miniapp is installed but does not hold the role. Keep your own preferences in session.storage, not in platform settings.

Trying it

Run your miniapp from the dev server, then pick it under Settings > Dashboard > Dashboard app. Dev-loaded miniapps pass the permission checks without declaring anything, so check your manifest before you publish: a Store install without MANAGE_MINIAPPS or PLATFORM_SETTINGS rejects those calls with PERMISSION_NOT_DECLARED.

Getting Started

Core Concepts

UI Layer

Display

Audio & Speech

Sensors & Input

Camera

Phone & System

Data

Reference

Build a dashboard

Manifest

What the role gives you

A minimal dashboard

What the bundled dashboard uses

Settings you own

Trying it

​Manifest

​What the role gives you

​A minimal dashboard

​What the bundled dashboard uses

​Settings you own

​Trying it

Manifest

What the role gives you

A minimal dashboard

What the bundled dashboard uses

Settings you own

Trying it