forked from Blendman974/faceclaw
228 lines
12 KiB
Markdown
228 lines
12 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 35
|
|
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), view them on
|
|
the glasses, and send them inputs with the voice assistant.
|
|
* **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**, set:
|
|
|
|
1. **Compatible API URL** — the explicit API root.
|
|
2. **Compatible model ID** — the exact model identifier accepted by the server.
|
|
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. Optional: choose **Discover models**, then pick a model 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.
|
|
5. **Assistant model** — choose **OpenAI-compatible**. Auto never selects it.
|
|
|
|
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.
|
|
|
|
For the official Venice URL, **Settings > Assistant** also shows **Venice web
|
|
search**. It is off by default and visible only for that URL. 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.
|
|
|
|
## 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.
|