Skip to content
Back to search

inkemu

Desktop emulator for Xteink X4 Pro InkApp (Lua) apps: window, headless tests, mocked network, MCP server

Safety scan

A static text scan, not a guarantee. Select the badge to see what was scanned and every finding.

Checked today
Badge for your README
findsafeskills safety rating

Markdown

[![findsafeskills safety rating](/api/listings/ermakov-oleg--inkemu/badge.svg)](/listings/ermakov-oleg--inkemu)

HTML

<a href="/listings/ermakov-oleg--inkemu"><img src="/api/listings/ermakov-oleg--inkemu/badge.svg" alt="findsafeskills safety rating" /></a>

Install

i

Install instructions from the README

As written by the repo's author. findsafeskills has not verified these steps.

uv tool install inkemu      # or: pipx install inkemu

or as a dev dependency of your app project: `uv add --dev inkemu` (then prefix the commands with `uv run`).

Python 3.11+, macOS or Linux. Everything is headless except the window, which needs Tk (`python3-tk` on Debian/Ubuntu). CI runs on uv-managed Pythons (Tk 9); with the python.org builds (Tk 8.6) the window has been seen to crash on macOS 26.

What was scanned

The files the safety scan read, as written by the repository's author and shown as plain text. Lines with a finding are marked.

README.md · README · 194 lines
  1. # inkemu
  2. [![CI](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml/badge.svg)](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml)
  3. [![PyPI](https://img.shields.io/pypi/v/inkemu)](https://pypi.org/project/inkemu/)
  4. [![Python](https://img.shields.io/pypi/pyversions/inkemu)](https://pypi.org/project/inkemu/)
  5. [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ermakov-oleg/inkemu/blob/main/LICENSE)
  6. Run and test Lua apps for the Xteink X4 Pro e-ink reader (the "InkApp" host of the XTOS Licorice firmware) on your
  7. desktop. inkemu loads an app folder (`manifest.json` + `index.lua`), renders its 480x800 1-bpp screen and lets you
  8. drive it from a window, a one-shot CLI run, a pytest test or an AI agent over MCP, with virtual time and recorded
  9. network responses.
  10. <p align="center">
  11. <img src="https://raw.githubusercontent.com/ermakov-oleg/inkemu/main/docs/images/hello.png" width="300" alt="The hello example app: clock, battery and a tap counter">
  12. &nbsp;&nbsp;
  13. <img src="https://raw.githubusercontent.com/ermakov-oleg/inkemu/main/docs/images/lockscreen.png" width="300" alt="The lock screen of the hello example">
  14. </p>
  15. The device API is not publicly documented. Everything here is built from community reverse-engineering notes, so
  16. treat inkemu as a development aid, not as a reference of the firmware.
  17. ## Install
  18. ```bash
  19. uv tool install inkemu # or: pipx install inkemu
  20. ```
  21. or as a dev dependency of your app project: `uv add --dev inkemu` (then prefix the commands with `uv run`).
  22. Python 3.11+, macOS or Linux. Everything is headless except the window, which needs Tk (`python3-tk` on
  23. Debian/Ubuntu). CI runs on uv-managed Pythons (Tk 9); with the python.org builds (Tk 8.6) the window has been seen to
  24. crash on macOS 26.
  25. ## Quick start
  26. An app is a folder with `manifest.json` and `index.lua`; [`examples/hello`](https://github.com/ermakov-oleg/inkemu/tree/main/examples/hello)
  27. is a small one with a lock screen (it is not in the package: clone the repository or copy the folder).
  28. ```bash
  29. inkemu window examples/hello # a window: click = tap, drag = swipe, arrows/Enter/Esc = side buttons
  30. ```
  31. ```bash
  32. # one-shot, no window: numbered PNG shots and texts.json go to .emu/run
  33. inkemu run examples/hello --fresh --time 2026-11-20T09:41 --steps "tap-text 'Tap me'; wait 61s; shot; texts"
  34. ```
  35. The same app in a pytest test, with the network answered from recorded fixtures:
  36. ```bash
  37. inkemu run apps/weather --net record --steps "wait 5s" # once: real requests saved to tests/fixtures/<app_id>/net/
  38. ```
  39. ```python
  40. from inkemu import Emu
  41. def test_weather(tmp_path):
  42. emu = Emu("apps/weather", state_dir=tmp_path / "state", start_time="2026-11-20T09:00:00") # net="replay"
  43. emu.wait("5s")
  44. assert emu.has_text("Berlin")
  45. emu.tap_text("Refresh")
  46. assert emu.errors == [] # Lua tracebacks are collected, never raised
  47. ```
  48. Other members: `emu.tap(x, y)`, `emu.double_tap()`, `emu.hold()`, `emu.swipe(direction)`, `emu.key(name)`,
  49. `emu.type_text()`, `emu.answer(ok)`, `emu.lock()`, `emu.unlock()`, `emu.restart()`, `emu.texts()`, `emu.status()`,
  50. `emu.log`, `emu.warnings`, `emu.shot()` (a Pillow image), `emu.save_shot(path)`.
  51. ## Commands
  52. ```bash
  53. inkemu window APP # Tk window + command daemon
  54. inkemu run APP --steps "..." # one-shot, no window
  55. inkemu serve APP # headless daemon in the foreground
  56. ```
  57. Common options: `--net replay|record|live` (default `replay`), `--fresh` (wipe the app state first),
  58. `--time ISO8601` (virtual start time), `--state DIR`, `--fixtures DIR`. `run` also takes `--steps` and `--out DIR`
  59. (default `.emu/run`: numbered `NNN.png` shots and `texts.json`), prints shot paths and the output of `texts`, `log`
  60. and `state` steps as they run, and exits 1 if the app raised a Lua error. `window` and `serve` take `--port`
  61. (default 7480, `0` = any free port).
  62. While a daemon runs, the same verbs work as client commands (`inkemu tap-text 'Tap me'`):
  63. `tap X Y`, `tap-text TEXT`, `double-tap X Y`, `swipe up|down|left|right`, `hold X Y [MS]`,
  64. `key up|down|left|right|ok|back`, `type TEXT`, `answer yes|no`, `wait DURATION` (`500ms`, `61s`, `2m`),
  65. `lock`, `unlock`, `reload`, `restart`, `shot [PATH]`, `texts`, `log`, `state`, `resume`, `stop`.
  66. `tap-text` taps the last drawn occurrence of the text; if it is not on screen it fails and lists the visible texts.
  67. Every input advances virtual time by 350 ms. Daemon discovery goes through `<state root>/daemon.json`.
  68. An open dialog (`ctx.dialog:confirm`, `ctx.input:text`/`edit`, the host's "Leave app?") is drawn as a plate with its
  69. title, text or field and `Yes`/`No` or `OK`/`Cancel`, so it shows in shots and `texts`. While it is open, input does
  70. not reach the app (the log says so); tapping a button (`tap-text Yes`) answers it, as do `answer` and `type`.
  71. The window shows the same dialogs as native Tk dialogs instead.
  72. ### Window keys
  73. Mouse: click = tap, drag = swipe, long press = hold. Arrows = side buttons, Enter = ok, Esc = back,
  74. `L` lock/unlock, `R` reload the app, `]` +1 minute, `}` +1 hour, `S` save a screenshot, `P` pause/resume the clock.
  75. ## MCP server
  76. `inkemu-mcp` is a stdio MCP server, so an agent can start the app, tap, wait and look at screenshots. In Claude Code,
  77. from your app project:
  78. ```bash
  79. claude mcp add inkemu -- inkemu-mcp # inkemu installed with uv tool / pipx
  80. claude mcp add --scope project inkemu -- uv run inkemu-mcp # inkemu is a dev dependency; writes .mcp.json
  81. ```
  82. Other clients take the same command, e.g. `{"mcpServers": {"inkemu": {"command": "inkemu-mcp"}}}`. App paths are
  83. relative to the server's working directory, which is the project for Claude Code.
  84. Tools: `emu_start(app, window=None, net=None, fresh=False, port=0)` (starts a detached daemon, headless and `replay`
  85. unless asked otherwise, or reuses the running one for the same app; it refuses with `ok: false` when that daemon
  86. runs in another `window`/`net` mode or `fresh=True` is asked, so call `emu_stop` first), `emu_tap`, `emu_tap_text`,
  87. `emu_double_tap`, `emu_swipe`, `emu_hold`, `emu_key`, `emu_type`, `emu_answer`, `emu_wait`, `emu_lock`,
  88. `emu_unlock`, `emu_reload`, `emu_restart`, `emu_screenshot` (PNG image), `emu_texts`, `emu_log`, `emu_resume`,
  89. `emu_stop`. The daemon listens on 127.0.0.1 only and rejects requests with a foreign `Host`, an `Origin` header or a
  90. non-JSON content type.
  91. ## Network
  92. `ctx.net:request` goes through one of three modes:
  93. - `replay` (default): answers from fixtures; a request without a fixture gets `err='no_fixture'` and a log line
  94. naming method, URL and `--net record`. Never touches the network.
  95. - `record`: makes the real request and saves it as a fixture.
  96. - `live`: real requests, nothing saved.
  97. Fixtures live in `<fixtures dir>/net/` (default `tests/fixtures/<app_id>/net/`, relative to the working directory),
  98. one `METHOD_host_hash.json` (request key, response status/headers/`body_file`/`delay_ms`) plus a `.body` file.
  99. POST bodies are matched by SHA-256. A fixture can be written by hand; a malformed one is ignored with a warning.
  100. `<state root>/secrets.json` (default `.emu/secrets.json`) is a flat `{"name": "value"}` object. Values are replaced by
  101. `{{name}}` in recorded URLs, bodies and headers, and `{{name}}` in app files seeded from the project is replaced
  102. back for `live` and `record` requests, including their percent-encoded forms. A password in the URL
  103. (`https://user:pass@host`) is always recorded as `{{userinfo}}`. Sensitive headers (`authorization`, `cookie`,
  104. `*token*`, `*key*`, ...) are never recorded. Keep `secrets.json` out of git.
  105. ## State on disk
  106. `<state root>/<app_id>/` holds `state.json` (`ctx.state`), `files/` (`ctx.storage`), `lock.json` and `shots/`.
  107. The state root is `.emu/` in the working directory, or `$INKEMU_STATE_ROOT`. `--fresh` wipes the app state first.
  108. ## Supported API
  109. Callbacks: `on_load`, `on_resume`, `on_draw(ctx, g)`, `on_input(ctx, ev)` (pointer taps, double taps, swipes and
  110. holds; side-button keys), `on_tick`, `on_leave`. A `lockscreen` block in the manifest runs its own entry file on
  111. lock and on every `interval_sec` wake, with `ctx.lock` (`reason`, `done`, `set_interval`, ...).
  112. Drawing (`g`): `clear`, `rect`, `round_rect`, `line`, `circle`, `arc`, `polygon`, `polyline`, `text`, `text_box`,
  113. `image`, `pattern_rect`, `fill_pattern`, plus layers via `ctx.layers`. The frame cap of 1024 commands is enforced.
  114. `ctx`: `invalidate`, `after`/timers, `set_tick`, `defer_full_refresh`, `quit`, `log`, `save_state`, `state`, `api`,
  115. `capabilities`, `clock`, `device`, `fonts`, `storage`/`files`, `package`, `net` (`request`; GET and POST),
  116. `dialog` (`confirm`, `toast`), `input` (`text`, `edit`), `image`, `qr`, `json`, `hex`, `hash`, `url`, `zlib`,
  117. `random`, `screen`, `display`, `frontlight`, `system`, `i18n`, `perf`, `gc`, `budget`, `reader` (answers from
  118. `<fixtures dir>/reader.json`), `lockscreen`, `lock`. `ctx.ui` is not implemented.
  119. ## Differences from the device
  120. - Fonts are approximate: the system Helvetica, Arial or DejaVu (whichever exists) at fixed line heights 20/24/30,
  121. so text widths differ from the device; `ctx.fonts:size(px)` picks the nearest of the three, there is no TTF.
  122. - Lua is 5.5 via [lupa](https://pypi.org/project/lupa/): the firmware reports `_VERSION` "Lua 5.5" in the
  123. reverse-engineering notes (desktop test setups often run 5.4, whose for-loop variables are not constant).
  124. Integers are 64-bit here; the device is probably built with 32-bit integers, so keep arithmetic below 2^31.
  125. - No `ctx.ui`, no BLE, no WebSocket; only GET and POST get a network callback.
  126. - Layer semantics and error codes are guesses based on the notes.
  127. - Remote commands (daemon verbs, MCP) freeze the window clock, read-only ones included, so a screenshot is stable;
  128. `resume`, or `P` in the window, lets time run again.
  129. - A callback (or the lock screen) that runs more than 200 million Lua instructions is aborted as an app error
  130. ("callback exceeded the instruction budget ... - infinite loop?"); the device has its own, unknown budget.
  131. Time spent inside C functions such as `string.rep` or pattern matching is not counted.
  132. - The app sees `debug == false` instead of `nil` (lupa reads that global on every call into Lua), and no
  133. `python`, `io`, `os` or `package.searchpath`. An app that sets `debug = nil` itself and then installs an erroring
  134. metatable on `_G` can still crash the emulator process (not escape it).
  135. ## Development
  136. ```bash
  137. uv sync
  138. uv run pytest
  139. uv run ruff check && uv run ruff format --check
  140. uv run python docs/make_images.py # regenerate the README screenshots
  141. ```
  142. ## Credits
  143. The API notes come from [omer-faruq-xteink/touch-licorice-apps](https://github.com/omer-faruq-xteink/touch-licorice-apps)
  144. (`docs/firmware-notes.md`) and kycube/x4pro-emu. MIT licence, see
  145. [LICENSE](https://github.com/ermakov-oleg/inkemu/blob/main/LICENSE).

Ratings and comments

Sign in to rate this skill.

Sign in

Free to use. If it’s helped, pass it on.