KO | EN

GitLite

Minimalist Open Source Repository Search Engine

gitlite — search

#developer-tools #typescript #codex #ai-agents #claude-code #dsh #dsh-plugin #cli #deepseek-harness #open-source #macos #ai-agent

even-dev

★ 83 Open GitHub ↗

Even Realities Hub Simulator - multi application test environment

// repository documentation

Was this content helpful?

★ 0 (0 ratings)

# Unified Even Hub Simulator v0.1.0

Multi-application development environment for building and testing Even G2 apps with the Even Hub Simulator.

```bash
➜  even-dev git:(main) ./start-even.sh
Starting Even Hub development environment... http://127.0.0.1:5173

░░███
  ██████  █████ █████  ██████  ████████           ███████   ██████  █████ █████
 ███░░███░░███ ░░███  ███░░███░░███░░███  ██████ ███░░███  ███░░███░░███ ░░███
░███████  ░███  ░███ ░███████  ░███ ░███ ░░░░░░ ░███ ░███ ░███████  ░███  ░███
░███░░░   ░░███ ███  ░███░░░   ░███ ░███        ░███ ░███ ░███░░░   ░░███ ███
░░██████   ░░█████   ░░██████  ████ █████       ░░████████░░██████   ░░█████
 ░░░░░░     ░░░░░     ░░░░░░  ░░░░ ░░░░░         ░░░░░░░░  ░░░░░░     ░░░░░

Command hints:
  ./start-even.sh                        # interactive app selection
  ./start-even.sh <app-name>             # run one app directly
  ./start-even.sh --update               # refresh all git apps from apps.json
  ./start-even.sh --update <name>        # refresh one git app from apps.json
  ./start-even.sh --devenv-update        # refresh root and apps/* npm dependencies
  ./start-even.sh --reset                # remove generated caches/build outputs
  ./start-even.sh --evenhub-cli --help   # evenhub-cli launcher

Starting Vite dev server...
Available apps:
  ID   NAME                 SOURCE
  ---- -------------------- ----------------------------------------
  1    base_app             apps/base_app
  2    timer                apps/timer
  3    restapi              apps/restapi
  4    clock                apps/clock
  5    quicktest            apps/quicktest
  6    chess                .apps-cache: github.com/dmyster145/EvenChess
  7    epub                 .apps-cache: github.com/chortya/epub-reader-g2
  8    reddit               .apps-cache: github.com/fuutott/rdt-even-g2-rddit-client
  9    smart-cart           .apps-cache: github.com/bryan-datastorm/smart-cart-even-g2
  10   stars                .apps-cache: github.com/thibautrey/even-stars
  11   transit              .apps-cache: github.com/langerhans/even-transit
  12   weather              .apps-cache: github.com/nickustinov/weather-even-g2.git
  13   snake                .apps-cache: github.com/nickustinov/snake-even-g2
  14   pong                 .apps-cache: github.com/nickustinov/pong-even-g2
  15   stt                  .apps-cache: github.com/nickustinov/stt-even-g2
  16   tetris               .apps-cache: github.com/nickustinov/tetris-even-g2
  ...
Select app [1-15] (default 1): 1
```

![base\_app](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/base_app.png)

For general G2 development documentation, see the [G2 development notes](https://github.com/nickustinov/even-g2-notes).

## Apps

|              App               |                      Description                               |     Visual        |
|:------------------------------:|:----------------------------------------------------------------| :---------------: |
|    [base\_app](./apps/base_app/)        | base\_app – simple one pager app template                 | ![demo](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/base_app.png) |
|    [clock](./apps/clock/)      | Clock app – app refresh test showcase                           | ![clock](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/clock.png) |
|    [timer](./apps/timer/)      | Countdown timer (1, 5 ... min, click to start, double-click to stop) | ![timer](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/timer.png) |
|    [restapi](./apps/restapi/)  | Simple REST API client (micrOS integration)                     | ![restapi](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/restapi.png) |
|    [quicktest](./apps/quicktest/) | Fast test app for UI generated by `misc/editor` | ![quicktest](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/quicktest.png) ![editor](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/editor.png) |
|                                |                                                    |                                              |
|    [chess](https://github.com/dmyster145/EvenChess) | Chess HUD app by @dmyster145 | ![chess](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/chess.png) |
|    [epub](https://github.com/chortya/epub-reader-g2) | Epub reader by @chortya | ![epub](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/epub.png) ![epub2](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/epub2.png) |
|    [make20](https://github.com/takashicompany/make20) | Make 20 puzzle game by @takashicompany | ![make20](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/make20.png) |
|    [reddit](https://github.com/fuutott/rdt-even-g2-rddit-client) | Reddit feed and comments browser by @fuutott | ![reddit](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/reddit.png) |
|    [smart-cart](https://github.com/bryan-datastorm/smart-cart-even-g2) | Glanceable, hands-free grocery list by @bryan-datastorm | ![smart-cart](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/smart-cart.png) |
|    [solitaire](https://github.com/dmyster145/EvenSolitaire) | Solitaire card game by @dmyster145 | ![solitaire](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/solitaire.png) |
|    [stars](https://github.com/thibautrey/even-stars) | Real-time sky chart by @thibautrey | ![stars](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/stars.png) |
|    [transit](https://github.com/langerhans/even-transit) | Public transport planner by @langerhans | ![stars](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/transport.png) |
|    [weather](https://github.com/nickustinov/weather-even-g2) | Weather forecast by @nickustinov | ![weather](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/weather.png) |
|    [worldclock](https://github.com/KamalQ/EvenWorldClock) | World clock app by @KamalQ | ![worldclock](https://raw.githubusercontent.com/BxNxM/even-dev/main/media/woldclock.png) |
|    [stt](https://github.com/nickustinov/stt-even-g2) | Real-time speech-to-text via [Soniox](https://soniox.com) by @nickustinov | |

---

## Requirements

* Node.js
* npm
* curl (used by `start-even.sh`)
* Even Hub Simulator

---

## Quick start

```bash
npm install
./start-even.sh
```

The launcher lists all available apps (built-in + external) and prompts you to pick one.

`misc/editor` is an auxiliary helper project tracked as a git submodule under `misc/`. It is not a runtime app in the `apps/*` selection list.

### Refresh external app cache

Use `--update` to refresh git-based apps from `apps.json`:

```bash
./start-even.sh --update
```

Update one registry app only:

```bash
./start-even.sh --update weather
```

If a cached app has local changes (for example `package-lock.json` edits), the updater auto-stashes those changes before pull and prints the stash name.

### Update even-dev launcher dependencies

Refresh npm dependencies for:
- root launcher environment (`start-even.sh`, root Vite, `vite-plugins/*`)
- built-in apps under `apps/*`

```bash
./start-even.sh --devenv-update
```

This command removes and reinstalls:
- root `node_modules` + `package-lock.json`
- each built-in app's `node_modules` + `package-lock.json`

### Select an app directly

```bash
APP_NAME=timer ./start-even.sh
```

Or as a positional argument:

```bash
./start-even.sh timer
```

### Run a local app by path

If you have an app checked out locally, point to it directly – no need to edit `apps.json`:

```bash
APP_PATH=../my-app ./start-even.sh
```

This resolves the directory, installs its dependencies if needed, and launches it. The app name is derived from the directory basename.

### Audio input

Some apps (like [stt](https://github.com/nickustinov/stt-even-g2)) need microphone audio from the simulator. Pass `AUDIO_DEVICE` with the exact device ID:

```bash
AUDIO_DEVICE="coreaudio:AppleUSBAudioEngine:Apple Inc.:Studio Display:00008030-00065D000C10802E:6,7" ./start-even.sh stt

OR

AUDIO_DEVICE="coreaudio:BuiltInMicrophoneDevice" ./start-even.sh stt
```

To find available device IDs, run:

```bash
npx @evenrealities/evenhub-simulator@latest -b default --list-audio-input-devices
```

This prints a table of IDs and names. Copy the full ID string from the left column. Note that `default` is not a valid device ID – you must use the exact ID.

The `AUDIO_DEVICE` value is passed to the simulator's `--aid` flag. When set, the simulator captures audio from that device, resamples it to 16 kHz S16LE PCM mono, and delivers it to your app via `bridge.audioControl(true)` / `event.audioEvent.audioPcm`.

---

## How apps are loaded

There are two kinds of apps:

### Built-in apps (`apps/`)

Apps under `apps/` are standalone web apps with their own `index.html`, `package.json`, and `src/main.*` entrypoint (they may share helpers from `apps/_shared`).

The launcher (`start-even.sh`) treats built-in apps as standalone-only and passes the selected app directory through `APP_PATH`.

### External apps

Standalone web apps with their own `index.html`, `package.json`, and `vite.config.ts`. They run independently – even-dev just serves their `index.html` through Vite with the correct filesystem access.

External apps are registered in `apps.json`:

```json
{
  "chess": "https://github.com/dmyster145/EvenChess",
  "weather": "https://github.com/nickustinov/weather-even-g2.git",
  "my-local-app": "../my-local-app"
}
```

Values can be:
- **Git URLs** – cloned into `.apps-cache/` on first run
- **Local paths** – resolved relative to the even-dev root

Use `./start-even.sh --update` (or `./start-even.sh --update <app>`) to refresh cloned git entries in `.apps-cache/`.

For one-off testing without editing `apps.json`, use `APP_PATH` instead (see above).

---

## Building a G2 app

A G2 app is a regular web app. There is no special framework or wrapper required – just HTML, TypeScript, and the Even Hub SDK for communicating with the glasses.

See [chess](https://github.com/dmyster145/EvenChess) and [reddit](https://github.com/fuutott/rdt-even-g2-rddit-client) for well-structured examples.

### Minimal file structure

```
my-app/
  index.html          <- entry point
  package.json        <- dependencies and scripts
  vite.config.ts      <- dev server config
  src/
    main.ts           <- app bootstrap
  app.json            <- app metadata (for packaging)
```

### `index.html`

A standard HTML page that loads your app:

```html
<!DOCTYPE html>
<html>
<head>
  <meta charset="UTF-8" />
  <meta name="viewport" content="width=device-width,initial-scale=1" />
  <title>My App</title>
</head>
<body>
  <div id="app"></div>
  <script type="module" src="/src/main.ts"></script>
</body>
</html>
```

### `package.json`

At minimum, you need the Even Hub SDK and Vite:

```json
{
  "name": "my-even-app",
  "scripts": {
    "dev": "vite --host 0.0.0.0 --port 5173",
    "build": "vite build"
  },
  "dependencies": {
    "@evenrealities/even_hub_sdk": "^0.0.7"
  },
  "devDependencies": {
    "typescript": "^5.9.3",
    "vite": "^7.3.1"
  }
}
```

### `app.json`

Metadata file used by `evenhub-cli` for packaging and deployment:

```json
{
  "package_id": "com.example.myapp",
  "edition": "202601",
  "name": "my-app",
  "version": "0.1.0",
  "min_app_version": "0.1.0",
  "tagline": "Short one-line summary for the app",
  "description": "What my app does",
  "author": "Your Name",
  "entrypoint": "index.html"
}
```

`evenhub-cli pack` validates this schema. `package_id` must be a valid lowercase dot-separated package name (for example `com.example.myapp`).

See the [reddit app's app.json](https://github.com/fuutott/rdt-even-g2-rddit-client) for a full example with permissions.

### Connecting to the Even bridge

```ts
import { waitForEvenAppBridge } from '@evenrealities/even_hub_sdk'

const bridge = await waitForEvenAppBridge()

bridge.onEvenHubEvent((event) => {
  // Handle tap, double-tap, swipe, etc.
})

// Send UI to the glasses
bridge.sendStartUpPage(container)
```

### Tips

- **Use inline styles or plain CSS** – avoid CSS frameworks like Tailwind that require build plugins, since your app may be served through even-dev's Vite config which won't have those plugins.
- **Keep it standalone** – your app should work with just `npm run dev`. Don't depend on even-dev's infrastructure.
- **If your app needs a backend server**, put it in a `server/` directory with its own `package.json`. Even-dev will auto-detect and start it (see `vite-plugins/app-server.ts`).
- **Use `@jappyjan/even-realities-ui`** for settings pages if you want consistent UI components across apps.
- **Use `@evenrealities/evenhub-cli`** for packaging and deploying to the Even Hub. See [reddit](https://github.com/fuutott/rdt-even-g2-rddit-client) for `pack` and `qr` script examples.

---

## Custom Vite plugins (`vite-plugins/`)

Even-dev autoloads Vite plugins from two places:

1. **Default plugins** (always loaded):
   - `vite-plugins/app-server.ts`
   - `vite-plugins/browser-launcher.ts`
2. **Discovered plugins**:
   - Selected app plugin (single effective load, also supports `.js/.mjs/.cjs`) resolved from:
     - `vite-plugins/<selected-app>-plugin.ts`
     - `<app-dir>/vite-plugin.ts`

`start-even.sh` keeps symlinks in sync automatically:
- Built-in apps: `apps/<name>/vite-plugin.ts` -> `vite-plugins/<name>-plugin.ts`
- External cached apps: `.apps-cache/<name>/vite-plugin.ts` -> `vite-plugins/<name>-plugin.ts`
- If names collide, built-in `apps/<name>` takes precedence and the external one is skipped with a log.

This means app plugins can live with the app code and still be discovered by the root Vite server with no manual registration.

Current plugin files in this repo:

| Plugin | Purpose |
|--------|---------|
| `app-server.ts` | Auto-starts an app's `server/` process (e.g., Tesla's Tessie API proxy) |
| `browser-launcher.ts` | Exposes helper routes to open editor/external URLs from the host |
| `chess-plugin.ts` | Serves Stockfish WASM assets for the chess app |
| `epub-plugin.ts` | Proxies Gutenberg requests for the epub app |
| `reddit-plugin.ts` | Proxies Reddit API requests to avoid CORS issues |
| `restapi-plugin.ts` | Proxies REST API requests for the restapi app |

Plugins receive a `PluginContext` with:
- `externalApps`: map of app names to resolved directory paths
- `selectedApp`: current selected app name
- `selectedAppDir`: current selected app absolute path (or `null`)

---

## Quicktest + editor workflow

Use this flow when you build UI in `misc/editor` and want to test it quickly in the simulator with `apps/quicktest`.

1. Ensure submodules are initialized once: `git submodule update --init --recursive`
2. Start the editor helper app: `./misc/editor.sh`
3. In the editor UI, generate TypeScript source.
4. Either paste that source into the quicktest textarea, or replace `apps/quicktest/src/generated-ui.ts`.
5. Start quicktest: `APP_NAME=quicktest ./start-even.sh`
6. In quicktest, click **Connect glasses** (auto-renders on connect), then use **Render Page** for rerenders.

Quicktest expectations for generated source:
- Source should define `const container = new CreateStartUpPageContainer(...)`.
- Source can include `import ... from '@evenrealities/even_hub_sdk'` and `export default container`; quicktest strips those automatically.
- First render creates startup UI; additional renders rebuild the page container.

---

## Project structure

```
apps.json           -> External app registry (git URLs or local paths)
start-even.sh       -> CLI launcher: app selection, deps, Vite, simulator
apps/               -> Standalone built-in apps (each has its own index.html + src/main.ts)
apps/_shared/       -> Shared helpers for standalone apps (dev/test/runtime utilities)
scripts/            -> Helper scripts (for example pack-app.sh)
vite-plugins/       -> Custom Vite plugins for root dev server / registry apps
.apps-cache/        -> Auto-cloned external app repositories (gitignored)
vite.config.ts      -> Root Vite config (serves the selected standalone app HTML, fs.allow, plugins)
```

---

## Architecture

```mermaid
flowchart TD
  A["start-even.sh"] --> M{"Mode flags"}
  M -->|"--reset / --update / --devenv-update / --evenhub-cli"| X["Run utility mode and exit"]
  M -->|"--sim-only"| S1["Launch simulator only with URL (+ optional AUDIO_DEVICE / SIM_OPTS)"]
  M -->|"default / --web-only"| S2["Start launcher flow"]

S2 --> D0{"App source"}
  D0 -->|"APP_PATH set"| D1["Use APP_PATH as selected app dir<br/>derive APP_NAME if missing"]
  D0 -->|"No APP_PATH"| D2["Discover apps: built-in apps/* + apps.json keys"]
  D2 --> D3["Select app (CLI arg / APP_NAME / interactive prompt)"]
  D3 --> D4{"apps.json entry is git URL?"}
  D4 -->|"yes"| D5["Clone into .apps-cache/{app} if missing"]
  D4 -->|"no"| D6["Use built-in apps/{app} or local apps.json path"]
  D5 --> D7["Resolve selected app directory + validate standalone files + install app deps if needed"]
  D6 --> D7
  D1 --> D7

D7 --> P0["Sync plugin symlinks into vite-plugins/ (built-in precedence on name collision)"]
  P0 --> V0["Start root Vite with VITE_APP_NAME + APP_NAME + APP_PATH"]

V0 --> V1["vite.config.ts loads app map from apps.json (+ APP_PATH override)"]
  V1 --> V2["Serve selected app index.html via standaloneAppHtmlPlugin"]
  V1 --> V3["Load plugins: default (app-server,browser-launcher) + selected app plugin"]
  V2 --> W["Selected app src/main.*"]
  V3 --> W

V0 --> W0["Wait until URL is reachable"]
  W0 --> W1{"--web-only?"}
  W1 -->|"yes"| W2["Keep Vite running, skip simulator launch"]
  W1 -->|"no"| W3["Launch simulator with URL (+ optional AUDIO_DEVICE / SIM_OPTS)"]

W --> B["Even Hub SDK bridge calls"]
  B <--> G["Even Hub Simulator"]
```

---

## Even developer resources

* SDK: [even_hub_sdk](https://www.npmjs.com/package/@evenrealities/even_hub_sdk)
* CLI: [evenhub-cli](https://www.npmjs.com/package/@evenrealities/evenhub-cli)
* Simulator: [evenhub-simulator](https://www.npmjs.com/package/@evenrealities/evenhub-simulator)
* Community SDK: [even-better-sdk](https://www.npmjs.com/package/@jappyjan/even-better-sdk) by @JappyJan
* UI components: [even-realities-ui](https://www.npmjs.com/package/@jappyjan/even-realities-ui) by @JappyJan
* UIUX guidelines: [Figma](https://www.figma.com/design/X82y5uJvqMH95jgOfmV34j/Even-Realities---Software-Design-Guidelines--Public-?node-id=2922-80782&t=ZIxZJDitnBnZJOwb-1)
* G2 development notes: [G2.md](https://github.com/nickustinov/even-g2-notes)

---

### Packaging (`evenhub-cli`)

Before packaging/deploying, log in to Even Hub CLI:

```bash
npx @evenrealities/evenhub-cli login
```

For built-in standalone apps under `apps/*`, use the helper script:

```bash
./scripts/pack-app.sh timer
```

This will build the app, then run `evenhub-cli pack app.json dist`, and produce `apps/timer/out.ehpk`.

Manual equivalent:

```bash
cd apps/timer
npm run build
npx @evenrealities/evenhub-cli pack app.json dist
```

---

## Disclaimer

This is a development environment intended for experimentation and building Even G2 apps. APIs and structure may change as the Even ecosystem evolves.

even-dev

Explore Similar Repositories

Was this content helpful?

Recent Feedback

Download README