# Build a dashboard

> Replace the glasses dashboard with your own miniapp.

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

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 dashboard runs at a time, and the running one holds the **dashboard
role**. Starting a dashboard from the Glassly App stops the one running, and
only one dashboard can be Always On: marking yours clears the flag on the
others, so it is the one that starts with the app.

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

```json 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. Only one dashboard
starts this way: if two dashboards' manifests both ask for it, the first by
package name starts, until the wearer marks one Always On in the Glassly App.

## What the role gives you

While your miniapp is running 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. That includes the
  notifications other miniapps post: they arrive on the same stream with
  `system: false` and `source` naming the miniapp (see
  [Posting notifications](https://docs.dev.glassly.ai/app-devs/core-concepts/phone.md#posting-notifications)).

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

```typescript 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", "head_up", "head_down"] : []);
  void claimShortcut();
  session.onCapabilitiesChange(() => void claimShortcut());

  session.input.onTouch((touch) => {
    if (touch.kind === "double_tap") void (open ? hide() : show());
    else if (touch.kind === "head_up") void show();
    else if (touch.kind === "head_down" && 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](https://docs.dev.glassly.ai/app-devs/core-concepts/display/layouts.md#dashboard-view) for the
view rules and [Input](https://docs.dev.glassly.ai/app-devs/core-concepts/input.md#claiming-gestures) 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 dashboard's own Open on head-up switch is on | `session.input.onTouch("head_up")` (claim `head_up` and `head_down`), the switch in `session.storage` | none |
| Clock format | `session.preferences.twelveHourTime` (the phone's 12/24-hour setting) unless the dashboard's own 12-hour switch in `session.storage` is set | none |
| Head-up angle | `session.settings` key `head_up_angle` | `PLATFORM_SETTINGS` |
| Display position | `session.system.openUrl("com.glassly://miniapps/settings/position")` opens the Glassly App's Display position screen | none |
| Glasses battery | `session.glasses.onBattery` | none |
| Controller batteries and 2D input, phone in use, miniapp on screen | `session.settings` keys `controllers`, `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` |
| Widgets from other miniapps | `session.widgets.list`, `place`, `unplace`, `send`, `onFrame` | `HOST_WIDGETS` |
| Per-app notification filter | `session.phone.notifications.installedApps` | `READ_NOTIFICATIONS` |
| Side menu of miniapps, with icons | `session.miniapps.list` (`includeIcons`), `start`, `stop` | `MANAGE_MINIAPPS` |
| Notification, Glasses Menu and clock settings | `session.settings.get`, `set`, `onChange` | `PLATFORM_SETTINGS` |
| Its own look (widget layout, clock style, close on head-down, Apps grid) | `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.

## Hosting widgets from other miniapps

A dashboard can show cards that other miniapps provide, such as the Spotify
miniapp's now playing card. Declare `HOST_WIDGETS` and use `session.widgets` to
list the available widgets, place them in boxes you assign, draw the frames the
providers push, and forward the wearer's swipes and taps. The bundled dashboard
places every external widget the wearer has put in a column. See
[Provide a dashboard widget](https://docs.dev.glassly.ai/app-devs/core-concepts/widgets.md#host-widgets).

## 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`](https://docs.dev.glassly.ai/app-devs/reference/system-apis.md#platform-settings)
or the wearer cannot change them while yours is running.

Keep your own preferences in [`session.storage`](https://docs.dev.glassly.ai/app-devs/core-concepts/storage.md),
not in platform settings.

## Trying it

Run your miniapp from the dev server and start it from the Glassly App:
starting it stops the dashboard that was running, and it holds the role until it
stops. Mark it Always On to keep it as the dashboard across launches. 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`.
