EvenHub Simulator

A development tool for rapid iteration and early-stage debugging of EvenHub applications. This simulator lets developers preview UI layouts and logic before running on physical hardware.

This simulator is a supplement to, not a replacement for, hardware testing, because inconsistencies between the simulator and real glasses can occur. Always validate on actual hardware before deployment. If you find discrepancies that affect coding logic, please file a bug report (in Discord for now) so we can reduce the differences.

Installation

npm install -g @evenrealities/evenhub-simulator

Usage

EvenHub simulator

Usage: evenhub-simulator [OPTIONS] [targetUrl]

Arguments:
  [targetUrl]  The URL to load on startup

Options:
  -c, --config <CONFIG>           Path to config file (use --print-config-path to see the default)
  -g, --glow                      Enable glow effect on glasses display
      --no-glow                   Disable glow effect (overrides config)
  -b, --bounce <BOUNCE>           Bounce animation type [possible values: default, spring]
      --list-audio-input-devices  List available audio input devices
      --aid <AID>                 Choose the specified audio input device instead of default
      --no-aid                    Use default audio device (overrides config)
  -V, --version                   Print version
      --print-config-path         Print the default config file path and exit
      --automation-port <PORT>    Start automation HTTP server on this port (e.g. 9898)
      --completions <SHELL>       Print shell completion script [possible values: bash, elvish, fish, powershell, zsh]
  -h, --help                      Print help

example to generate zsh completions:

evenhub-simulator --completions zsh > ~/.zsh/completions/_evenhub-simulator

Options

| Option | Description | |------------------------------|----------------------------------------------------------------------------------------| | -c, --config <config> | Path to a config file. Defaults to the OS config dir | | --print-config-path | Print the default config file path and exit. | | -g, --glow / --no-glow | Enable or disable the glow effect on the glasses display. | | -b, --bounce <bounce> | Sets bounce animation type: default or spring. | | --list-audio-input-devices | Lists available audio input devices and exits. | | --aid <aid> / --no-aid | Select a specific audio input device, or force the system default device. | | --automation-port <port> | Start an HTTP automation server on the given port. See Automation. | | --completions <shell> | Prints a shell completion script for bash, elvish, fish, powershell, or zsh. |

Default config file path:

| Platform | Value | Example | | ------- | ------------------------------------- | ---------------------------------------- | | Linux | $XDG_CONFIG_HOME or $HOME/.config | /home/<user>/.config | | macOS | $HOME/Library/Application Support | /Users/<user>/Library/Application Support | | Windows | {FOLDERID_RoamingAppData} | C:\Users\<user>\AppData\Roaming |

Caveats

Display & UI Rendering

Due to implementation differences, overall display characteristics (such as font rendering) may not perfectly match the hardware. The current fidelity should still be sufficient for layout validation and logic testing.

List Behavior

List scrolling behavior, especially focused-item positioning on screen, can vary. This happens because the simulator re-implements drawing logic instead of sharing embedded source code directly.

Error Handling

Under normal conditions, the simulator behaves similarly to the hardware. Error-response handling (for example, invalid inputs) may still differ, but should converge as the codebase matures.

Image Processing

The simulator processes images faster and currently does not enforce constraints such as hardware image-size limits. Future versions may introduce stricter checks to better simulate hardware behavior.

Events

• Status Events: Not emitted; user profiles and device statuses are hardcoded.
• Supported Inputs: Up, Down, Click, Double Click.

Audio

The simulator now emits audioEvents. The data specification for each event is:

• Sample rate: 16000
• Signed 16-bit little-endian PCM
• 100 ms of data per event (3200 bytes, 1600 samples)

Screenshot

Starting with v0.5.0, the simulator supports exporting the glasses display as an RGBA PNG file. This is intended for uploading apps to the Evenhub web portal in the future (maybe), though it can be used for any other suitable scenario.

Upon clicking, the simulator will export the current screen to your Current Working Directory (CWD) with a filename based on the current time. The full file path is printed to:

• Simulator stdout (as a warn log)
• Glasses web inspector console

Note: The image is not affected by the 'glow' flags, as that is a visual post-processing effect only.

Automation

Starting with v0.7.0, the simulator can expose an HTTP API for programmatic control, which is intended to make it easier for scripts (and AI agents) to drive the simulator — send input, capture screenshots, and read console output.

Launch with --automation-port to enable it:

evenhub-simulator https://my-app.example.com --automation-port 9898

Base URL: http://127.0.0.1:<PORT>

| Method | Endpoint | Description | |----------|----------------------------|----------------------------------------------------------------------| | GET | /api/ping | Health check, returns pong. | | GET | /api/screenshot/glasses | Current glasses framebuffer as an RGBA PNG (576×288). | | GET | /api/screenshot/webview | Screenshot of the main webview as PNG (Linux uses WebKitGTK snapshot; macOS uses WKWebView snapshot; Windows uses WebView2 CapturePreview). | | GET | /api/console | Captured webview console.* output, uncaught errors, failed fetches. Supports ?since_id=<N> for incremental polling. | | DELETE | /api/console | Clears the console buffer. | | POST | /api/input | Send a glasses touchpad action. JSON body: { "action": "up" \| "down" \| "click" \| "double_click" }. |

Notes:

• Input is only effective when the app has an active event container (list or text). If nothing is listening, the action is silently ignored.
• Console entries are tagged with a monotonically increasing id; use since_id when polling to avoid re-reading old entries.
• Non-console sources are prefixed in the message: [uncaught] …, [unhandledrejection] …, [fetch] ….

Changelog

v0.7.3 (2026-04-18)

• Fix /api/screenshot/webview returning blank images in some cases, now using native webview capture paths on each desktop platform
• Fix: constraint list item text size to be maximum 63 bytes and 20 items

v0.7.2 (2026-04-15)

• Improved emoji rendering support (including previously missing emoji characters).
• Improved bounce/spring animation stability.
• Better compatibility with newer local build toolchains.

v0.7.1 (2026-04-09)

A few fixes to behave more like firmware:

• make it no scrollbar even if containers exceed maximum full screen
• cap width/height for single container
• add text container bytes limit to 999

v0.7.0

• New --automation-port <PORT> flag that starts an HTTP server exposing endpoints for screenshots, console logs, and glasses input — useful for scripted testing and AI-driven automation. See the Automation section.
• Default border_color is now 0 (invisible) instead of 15 (white), to match the glasses.
• Unknown-glyph handling now matches the firmware: LV_USE_FONT_PLACEHOLDER is enabled, and the underlying lvgl crate is built with the g2 feature that customizes how missing glyphs are rendered to align with the glasses.
• Internal rendering pipeline optimization: the glasses canvas is now streamed as raw PNG bytes over a Tauri channel instead of base64-encoded events (not important to users though).

v0.6.2 (2026-03-25)

• adjust container limits (trying to be in sync with firmware behavior)

v0.6.1 (2026-03-25)

With the updates of evenhub sdk (0.0.8), simulator has a few changes accordingly:

• fixes the previous borderRadius typo. Also now it is an error in simulator to have unknown property fields.
• Sys_ItemEvent has added some new fields.
  • For eventSource simulator now hardcodes the value 1 (TOUCH_EVENT_FROM_GLASSES_R).
  • imuData will always be null/None.
  • systemExitReasonCode is also ignored here for now.

v0.5.3 (2026-03-03)

• Now will log original json to stdout if parsing payload error (needs RUST_LOG=debug)
• change x_position/y_position type to i32 (previously was u32)

v0.5.2 (2026-02-28)

• Improve overall rendering accuracy: now with only 4bit colors
• Remove the brightness filter on glasses canvas

v0.5.1 (2026-02-27)

• Rendering mechanism adjustments
• Improve image rendering

v0.5.0 (2026-02-26)

• Add screenshot functionality

v0.4.1 (2026-02-20)

• Performance optimization
• New flag to print default config file location
• Fix completion command

v0.3.2 (2026-02-18)

• Fix description of config file location

v0.3.1 (2026-02-17)

• Adjust audio input device listing format

v0.3.0

• Shell completion support

v0.2.2

• Adjust audio resampling logic and ability to choose audio input device.
• Add config file support so you do not need to repeat common options.
• Add more command-line flags to override config options.

v0.2.0 (2026-02-16)

• Upgrade lvgl-sys to v9 (via a custom crate), with no obvious visual changes.
• Use a lighter font for CJK characters.
• Add preliminary audio event support.