235 lines
13 KiB
Markdown
235 lines
13 KiB
Markdown
# Faceclaw - An unofficial user interface for the Even Realities G2 smart glasses
|
||
|
||
This is an unofficial user interface for the Even Realities G2 smart glasses.
|
||
It is entirely unofficial, and comes with no support or warranty from Even
|
||
Realities or from anyone.
|
||
|
||
This app runs on Android, and requires installing custom firmware on the
|
||
glasses. The Android app itself can install and uninstall the custom firmware;
|
||
it downloads the stock firmware from Even and applies patches generated from
|
||
https://github.com/jimrandomh/g2flash.
|
||
|
||
User-facing documentation lives at https://faceclaw.org/.
|
||
|
||
|
||
## Screenshots
|
||
|
||

|
||

|
||

|
||

|
||

|
||

|
||
|
||
## Installation
|
||
|
||
Download faceclaw-<version>.apk from the GitHub releases section on the phone
|
||
that will be paired with the glasses and install it. On first run, the app will
|
||
walk you through pairing with the glasses and installing custom firmware.
|
||
|
||
|
||
## Compiling
|
||
|
||
For the NativeScript iOS port, see [iOS development](notes/ios-development.md).
|
||
Use `scripts/pull_config_ios.sh` and `scripts/push_config_ios.sh` to transfer iPhone
|
||
settings. Android and iOS share one JSON config format, so a config pulled from either
|
||
platform can be pushed to the other; see [config transfer](scripts/config-transfer.md).
|
||
The instructions below build the Android app.
|
||
|
||
If you want to customize faceclaw, the best way to do it is to download the
|
||
source code and using a coding agent such as Codex or Claude Code.
|
||
|
||
To compile, you will need an Android SDK environment with SDK version 36
|
||
installed and licenses accepted, and the ANDROID_HOME pointing to the install.
|
||
You will need Nativescript installed, and a JDK environment (v21), with the
|
||
JAVA_HOME environment variable pointed at it. You will also need a reasonably
|
||
up to date npm and nodejs installed. You can put environment variables in
|
||
build_paths.sh and they will be used by all build commands.
|
||
|
||
To install a version that you compiled, you will need developer mode enabled on
|
||
your phone, and `adb` connected. To enable developer mode, go to Settings>About
|
||
phone and tap the "Build number" field seven times. Then plug the phone's USB-C
|
||
port into your computer, authorize access on the phone, and run
|
||
`./build_and_run.sh` to install.
|
||
|
||
Note that if you have installed a signed release build, you will have to
|
||
uninstall it before installing a customized version. Use scripts/pull_config.sh
|
||
to export a copy of your configuration first, and scripts/push_config.sh to
|
||
import it into the new version (see [config transfer](scripts/config-transfer.md)).
|
||
|
||
|
||
## Features
|
||
|
||
<!-- Generated from website/content/features.md by scripts/sync-site.mjs; edit there. -->
|
||
<!-- BEGIN GENERATED: features -->
|
||
* **A voice assistant** that wakes up when you say "Hey Even", transcribes
|
||
text with an on-device model, OpenAI Whisper, ElevenLabs, or Soniox API,
|
||
and responds to queries and commands using an onboard model (Qwen3 4B,
|
||
slow) or with an Anthropic, OpenAI, or OpenAI-compatible Chat Completions
|
||
model (including Venice and private Open WebUI servers; model ID and
|
||
usually an API key required), with optional Venice web search for supported
|
||
models, or using your own long-running OpenClaw agent.
|
||
* **Multitasking**, with an app-switcher sidebar and app launcher.
|
||
* **Glanceboard**, a dashboard with widgets that you can quickly view with a
|
||
* **Mostly-compatible with EvenHub.** Install and runapps from the Even app
|
||
store.
|
||
* **A lock screen**; glasses lock automatically when you take them off and
|
||
unlock when you unlock your phone.
|
||
* **The full display.** Full-screen apps can use the full 640x480 display
|
||
area, rather than the 576x288 that EvenHub apps can use.
|
||
* **Integration with Android notifications**: shows the same notification
|
||
icons your phone does, and popups when notifications arrive.
|
||
* **Terminal mirroring.** Mirror terminal apps such as Claude Code or Codex
|
||
CLI with [g2mirror](https://github.com/jimrandomh/g2mirror), or attach to
|
||
tmux sessions over SSH (no server-side setup beyond tmux 3.2+), view them
|
||
on the glasses, and send them inputs with the voice assistant. g2mirror
|
||
can also be tunnelled over SSH instead of a VPN.
|
||
* **Media player controls** including playlist and media library navigation,
|
||
compatible with most Android media players.
|
||
* **Turn-by-turn directions** (requires a Mapbox API token).
|
||
* **Nightscout**, an app for viewing blood-glucose data (requires a cloud
|
||
server and API token).
|
||
* **Power management**: the glasses go to sleep properly when the screen is
|
||
off, and wake when you double-tap the ring or speak the wakeword, allowing
|
||
battery life similar to the stock Even app.
|
||
* **A Wear OS watch app** that replaces (and outdoes) the R1 ring: tap,
|
||
swipe, hold and crown gestures, side buttons, app launching and window
|
||
switching, voice or keyboard queries to the assistant with the reply on
|
||
your wrist, typing into apps, and glasses status/lock/display control.
|
||
* **On-phone screen mirroring**: Your phone screen shows the same contents as
|
||
the glasses, and you can use the phone touchscreen as an input device..
|
||
<!-- END GENERATED: features -->
|
||
|
||
## OpenAI-compatible assistant providers (Venice / Open WebUI)
|
||
|
||
The assistant can call an OpenAI-compatible **Chat Completions** endpoint directly
|
||
from the phone. This uses the same conversation history and glasses tool loop as
|
||
the built-in cloud providers; it does not require different glasses firmware.
|
||
|
||
In **Settings > Assistant**:
|
||
|
||
1. **Assistant model** — choose **OpenAI-compatible**. Auto never selects it.
|
||
The settings in steps 2–4 appear only while it is selected.
|
||
2. **Compatible API URL** — the explicit API root.
|
||
3. **Compatible API key** — optional; when set, it is sent only to the configured
|
||
compatible endpoint as a Bearer token, not to OpenAI's Whisper service.
|
||
4. **Compatible model ID** — the exact model identifier accepted by the server.
|
||
Or choose **Discover models** and pick one from the server catalog. The
|
||
picker shows tool capability when advertised and hides offline models by
|
||
default. Refresh never changes the saved model by itself.
|
||
|
||
Provider examples:
|
||
|
||
| Provider | Compatible API URL | Notes |
|
||
| --- | --- | --- |
|
||
| Venice | `https://api.venice.ai/api/v1` | Use a current Venice model ID. Choose one with function-calling support if you want glasses tools. |
|
||
| Open WebUI | `https://your-openwebui-host/api` | This produces `/api/chat/completions`. Use the model ID exposed by your server and an Open WebUI API key if required. |
|
||
|
||
You may paste the full `/chat/completions` endpoint instead; Faceclaw removes
|
||
that suffix. It otherwise preserves the path you enter and does not guess `/v1`
|
||
or `/api`. Discovery requests `{API root}/models` only when you choose it; there
|
||
is no background discovery or automatic model selection. Manual model entry
|
||
remains available for servers without a compatible model-list endpoint.
|
||
|
||
When **OpenAI-compatible** is the assistant model and its URL is the official
|
||
Venice URL, **Settings > Assistant** also shows **Venice web search**. It is off
|
||
by default and hidden otherwise. When enabled, supported Venice models may
|
||
search the web for current information; the search model must support the
|
||
feature. Open WebUI and other compatible servers never receive Venice-specific
|
||
parameters, including after an endpoint switch.
|
||
|
||
The same provider can supply Calculator's rewrite fallback and Translate.
|
||
Actual tool calling depends on the selected model and server. Use HTTPS where
|
||
possible; mobile cleartext policies may block plain HTTP. For a private server,
|
||
make it reachable from the phone (for example through your tailnet) without
|
||
exposing it publicly. Exported settings contain API keys and must be treated as
|
||
secrets.
|
||
|
||
## Watch remote (Wear OS)
|
||
|
||
The `wear/` directory holds a companion app for Wear OS 3+ watches that turns
|
||
the watch into a remote for the glasses. The whole watch face is a touchpad
|
||
that mirrors the ring (tap, double-tap, hold, swipe, crown scrolling, side
|
||
buttons), and beyond the ring it can launch apps, switch and close windows,
|
||
wake/sleep/lock the display, send spoken or typed queries straight to the
|
||
assistant (using the watch's own microphone) and show the reply on the wrist,
|
||
and type text into apps such as the terminal. Its swipes are a spatial
|
||
control scheme the ring never had, with no mode to enter first: the
|
||
launcher highlights one app and moves it by rows and columns, right goes
|
||
into things (sidebar → window, settings section → items, next track in
|
||
Music), left backs out, tap selects, hold opens the context menu, double-tap
|
||
or a two-finger tap is back everywhere, and two wrist twists go back; up/down
|
||
scroll and right/left select/back everywhere else. The ring's own scheme is
|
||
unchanged — watch input is tagged as a separate source. Faceclaw's Settings > Watch
|
||
section has the phone-side switches. See [wear/README.md](wear/README.md) for
|
||
building and installing it; it is a separate Gradle build, sideloaded over
|
||
adb, and needs no Play Store. The phone side requires Google Play services.
|
||
|
||
The iOS app has the same remote for Apple Watch, with the same pad and screens;
|
||
see [apple-watch/README.md](apple-watch/README.md).
|
||
|
||
## Connecting an external agent (OpenClaw)
|
||
|
||
Instead of calling an LLM API directly from the phone, the voice assistant
|
||
can route queries to your own long-running agent, which also gets access to
|
||
the glasses' tools (show alerts, read notifications, control media, type
|
||
into apps including terminals) both during conversations and proactively. This
|
||
works through the faceclaw-agent-bridge OpenClaw plugin
|
||
(https://github.com/jimrandomh/faceclaw-agent-bridge): the phone dials out to
|
||
it over a websocket (typically across a tailnet).
|
||
|
||
Setup lives in the faceclaw-agent-bridge repository's README. It covers
|
||
both the OpenClaw-host side (plugin install and configuration) and the
|
||
phone side, which can be configured either by hand in Settings > Assistant
|
||
on the glasses, or over adb using scripts/pull_config.sh and
|
||
scripts/push_config.sh from this repo; the instructions are written so an
|
||
OpenClaw agent with the phone plugged into its host can perform the whole
|
||
setup itself. Note that a pulled settings file contains your API keys, so
|
||
treat it as a secret (the default output path is gitignored here).
|
||
|
||
## EvenHub App Notes
|
||
|
||
Faceclaw is mostly compatible with EvenHub apps. If you are developing an
|
||
app or using an open source app, you can package it into an EHPK file, send
|
||
it to your phone, and open it in the file browser to install. Or, you can log
|
||
into EvenHub and download apps there.
|
||
|
||
Faceclaw runs EvenHub apps through an emulation layer; you may run into bugs
|
||
and differences in behavior. If you run into bugs, please try tunning them in
|
||
the stock Android app before you report them to the app's creator. If you're
|
||
developing your own app and plan to submit it to the Hub, be sure to test it in
|
||
the stock Android app before submitting.
|
||
|
||
## Additional Caveats
|
||
|
||
Some permissions are used, but may not reliably prompted for. Go to Android
|
||
Settings > Apps > Faceclaw to ensure permissions are available or things may
|
||
not work.
|
||
|
||
Being a background app on a locked Android phone is fraught, and there may be
|
||
issues with manufacturer-psecific battery optimization software that lead to
|
||
it getting paused, throttled to low CPU usage, etc.
|
||
|
||
## Contributing
|
||
|
||
Be bold. Modify Faceclaw into the app that you want it to be for yourself,
|
||
without worrying about whether other people will like your version. Then if you
|
||
think your changes might be useful to others, make a pull request at
|
||
https://github.com/jimrandomh/faceclaw. Consider joining the Discord server
|
||
to talk to other developer: https://discord.gg/XVFDFSwek3
|
||
|
||
The Typescript and Java code in this repository runs on your phone, not on the
|
||
glasses themselves, and (with the narrow exception of the firmware-updating
|
||
tool), can't hurt your hardware. For changes to the glasses firmware, refer to
|
||
[g2flash](https://github.com/jimrandomh/g2flash); changes there require more
|
||
caution.
|
||
|
||
Faceclaw is Free Software (GPLv3). Please only contribute code that you wrote
|
||
(or prompted an agent to write), hold the copyright to, and have tested on
|
||
physical hardware under real-world conditions. If you make any changes that
|
||
involve integration with a third party's API or services, modify PRIVACY to
|
||
mention them and link to that provider's privacy policy. For services that
|
||
involve a user-provided API key, we assume that the user agreed to any terms
|
||
associated with that service when they generated the key. For services that
|
||
don't involve API keys, more caution may be required.
|