inkemu 0.1.0__tar.gz

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.
Files changed (43) hide show
  1. inkemu-0.1.0/.gitignore +6 -0
  2. inkemu-0.1.0/LICENSE +21 -0
  3. inkemu-0.1.0/PKG-INFO +226 -0
  4. inkemu-0.1.0/README.md +194 -0
  5. inkemu-0.1.0/examples/hello/index.lua +115 -0
  6. inkemu-0.1.0/examples/hello/lockscreen.lua +27 -0
  7. inkemu-0.1.0/examples/hello/manifest.json +16 -0
  8. inkemu-0.1.0/pyproject.toml +68 -0
  9. inkemu-0.1.0/src/inkemu/__init__.py +3 -0
  10. inkemu-0.1.0/src/inkemu/__main__.py +5 -0
  11. inkemu-0.1.0/src/inkemu/cli.py +190 -0
  12. inkemu-0.1.0/src/inkemu/clock.py +90 -0
  13. inkemu-0.1.0/src/inkemu/ctx_basic.py +656 -0
  14. inkemu-0.1.0/src/inkemu/ctx_ui.py +196 -0
  15. inkemu-0.1.0/src/inkemu/daemon.py +386 -0
  16. inkemu-0.1.0/src/inkemu/draw.py +297 -0
  17. inkemu-0.1.0/src/inkemu/emu.py +791 -0
  18. inkemu-0.1.0/src/inkemu/fonts.py +34 -0
  19. inkemu-0.1.0/src/inkemu/lockscreen.py +85 -0
  20. inkemu-0.1.0/src/inkemu/lua_env.py +159 -0
  21. inkemu-0.1.0/src/inkemu/mcp_server.py +228 -0
  22. inkemu-0.1.0/src/inkemu/net.py +411 -0
  23. inkemu-0.1.0/src/inkemu/paths.py +23 -0
  24. inkemu-0.1.0/src/inkemu/window.py +277 -0
  25. inkemu-0.1.0/tests/conftest.py +48 -0
  26. inkemu-0.1.0/tests/test_budget.py +120 -0
  27. inkemu-0.1.0/tests/test_cli.py +147 -0
  28. inkemu-0.1.0/tests/test_clock.py +71 -0
  29. inkemu-0.1.0/tests/test_ctx_basic.py +442 -0
  30. inkemu-0.1.0/tests/test_ctx_ui.py +308 -0
  31. inkemu-0.1.0/tests/test_daemon.py +264 -0
  32. inkemu-0.1.0/tests/test_dialogs.py +97 -0
  33. inkemu-0.1.0/tests/test_draw.py +203 -0
  34. inkemu-0.1.0/tests/test_hello.py +35 -0
  35. inkemu-0.1.0/tests/test_input.py +169 -0
  36. inkemu-0.1.0/tests/test_lifecycle.py +328 -0
  37. inkemu-0.1.0/tests/test_lockscreen.py +184 -0
  38. inkemu-0.1.0/tests/test_mcp.py +55 -0
  39. inkemu-0.1.0/tests/test_mcp_tools.py +58 -0
  40. inkemu-0.1.0/tests/test_net.py +441 -0
  41. inkemu-0.1.0/tests/test_sandbox.py +47 -0
  42. inkemu-0.1.0/tests/test_window.py +328 -0
  43. inkemu-0.1.0/uv.lock +1047 -0
@@ -0,0 +1,6 @@
1
+ .venv
2
+ __pycache__/
3
+ .pytest_cache/
4
+ .emu/
5
+ dist/
6
+ .DS_Store
inkemu-0.1.0/LICENSE ADDED
@@ -0,0 +1,21 @@
1
+ MIT License
2
+
3
+ Copyright (c) 2026 o.ermakov
4
+
5
+ Permission is hereby granted, free of charge, to any person obtaining a copy
6
+ of this software and associated documentation files (the "Software"), to deal
7
+ in the Software without restriction, including without limitation the rights
8
+ to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
9
+ copies of the Software, and to permit persons to whom the Software is
10
+ furnished to do so, subject to the following conditions:
11
+
12
+ The above copyright notice and this permission notice shall be included in all
13
+ copies or substantial portions of the Software.
14
+
15
+ THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
16
+ IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
17
+ FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
18
+ AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
19
+ LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
20
+ OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
21
+ SOFTWARE.
inkemu-0.1.0/PKG-INFO ADDED
@@ -0,0 +1,226 @@
1
+ Metadata-Version: 2.5
2
+ Name: inkemu
3
+ Version: 0.1.0
4
+ Summary: Desktop emulator of the Xteink X4 Pro InkApp (XTOS Licorice) Lua host
5
+ Project-URL: Homepage, https://github.com/ermakov-oleg/inkemu
6
+ Project-URL: Repository, https://github.com/ermakov-oleg/inkemu
7
+ Project-URL: Issues, https://github.com/ermakov-oleg/inkemu/issues
8
+ License-Expression: MIT
9
+ License-File: LICENSE
10
+ Keywords: e-ink,emulator,inkapp,lua,mcp,xteink
11
+ Classifier: Development Status :: 3 - Alpha
12
+ Classifier: Environment :: Console
13
+ Classifier: Intended Audience :: Developers
14
+ Classifier: Operating System :: MacOS
15
+ Classifier: Operating System :: POSIX :: Linux
16
+ Classifier: Programming Language :: Lua
17
+ Classifier: Programming Language :: Python :: 3
18
+ Classifier: Programming Language :: Python :: 3 :: Only
19
+ Classifier: Programming Language :: Python :: 3.11
20
+ Classifier: Programming Language :: Python :: 3.12
21
+ Classifier: Programming Language :: Python :: 3.13
22
+ Classifier: Programming Language :: Python :: 3.14
23
+ Classifier: Topic :: Software Development :: Embedded Systems
24
+ Classifier: Topic :: Software Development :: Testing
25
+ Classifier: Topic :: System :: Emulators
26
+ Requires-Python: >=3.11
27
+ Requires-Dist: lupa>=2.8
28
+ Requires-Dist: mcp>=2.3.0
29
+ Requires-Dist: pillow>=13.0
30
+ Requires-Dist: segno>=1.6.6
31
+ Description-Content-Type: text/markdown
32
+
33
+ # inkemu
34
+
35
+ [![CI](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml/badge.svg)](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml)
36
+ [![PyPI](https://img.shields.io/pypi/v/inkemu)](https://pypi.org/project/inkemu/)
37
+ [![Python](https://img.shields.io/pypi/pyversions/inkemu)](https://pypi.org/project/inkemu/)
38
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ermakov-oleg/inkemu/blob/main/LICENSE)
39
+
40
+ Run and test Lua apps for the Xteink X4 Pro e-ink reader (the "InkApp" host of the XTOS Licorice firmware) on your
41
+ desktop. inkemu loads an app folder (`manifest.json` + `index.lua`), renders its 480x800 1-bpp screen and lets you
42
+ drive it from a window, a one-shot CLI run, a pytest test or an AI agent over MCP, with virtual time and recorded
43
+ network responses.
44
+
45
+ <p align="center">
46
+ <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">
47
+ &nbsp;&nbsp;
48
+ <img src="https://raw.githubusercontent.com/ermakov-oleg/inkemu/main/docs/images/lockscreen.png" width="300" alt="The lock screen of the hello example">
49
+ </p>
50
+
51
+ The device API is not publicly documented. Everything here is built from community reverse-engineering notes, so
52
+ treat inkemu as a development aid, not as a reference of the firmware.
53
+
54
+ ## Install
55
+
56
+ ```bash
57
+ uv tool install inkemu # or: pipx install inkemu
58
+ ```
59
+
60
+ or as a dev dependency of your app project: `uv add --dev inkemu` (then prefix the commands with `uv run`).
61
+
62
+ Python 3.11+, macOS or Linux. Everything is headless except the window, which needs Tk (`python3-tk` on
63
+ Debian/Ubuntu). CI runs on uv-managed Pythons (Tk 9); with the python.org builds (Tk 8.6) the window has been seen to
64
+ crash on macOS 26.
65
+
66
+ ## Quick start
67
+
68
+ An app is a folder with `manifest.json` and `index.lua`; [`examples/hello`](https://github.com/ermakov-oleg/inkemu/tree/main/examples/hello)
69
+ is a small one with a lock screen (it is not in the package: clone the repository or copy the folder).
70
+
71
+ ```bash
72
+ inkemu window examples/hello # a window: click = tap, drag = swipe, arrows/Enter/Esc = side buttons
73
+ ```
74
+
75
+ ```bash
76
+ # one-shot, no window: numbered PNG shots and texts.json go to .emu/run
77
+ inkemu run examples/hello --fresh --time 2026-11-20T09:41 --steps "tap-text 'Tap me'; wait 61s; shot; texts"
78
+ ```
79
+
80
+ The same app in a pytest test, with the network answered from recorded fixtures:
81
+
82
+ ```bash
83
+ inkemu run apps/weather --net record --steps "wait 5s" # once: real requests saved to tests/fixtures/<app_id>/net/
84
+ ```
85
+
86
+ ```python
87
+ from inkemu import Emu
88
+
89
+
90
+ def test_weather(tmp_path):
91
+ emu = Emu("apps/weather", state_dir=tmp_path / "state", start_time="2026-11-20T09:00:00") # net="replay"
92
+ emu.wait("5s")
93
+ assert emu.has_text("Berlin")
94
+ emu.tap_text("Refresh")
95
+ assert emu.errors == [] # Lua tracebacks are collected, never raised
96
+ ```
97
+
98
+ Other members: `emu.tap(x, y)`, `emu.double_tap()`, `emu.hold()`, `emu.swipe(direction)`, `emu.key(name)`,
99
+ `emu.type_text()`, `emu.answer(ok)`, `emu.lock()`, `emu.unlock()`, `emu.restart()`, `emu.texts()`, `emu.status()`,
100
+ `emu.log`, `emu.warnings`, `emu.shot()` (a Pillow image), `emu.save_shot(path)`.
101
+
102
+ ## Commands
103
+
104
+ ```bash
105
+ inkemu window APP # Tk window + command daemon
106
+ inkemu run APP --steps "..." # one-shot, no window
107
+ inkemu serve APP # headless daemon in the foreground
108
+ ```
109
+
110
+ Common options: `--net replay|record|live` (default `replay`), `--fresh` (wipe the app state first),
111
+ `--time ISO8601` (virtual start time), `--state DIR`, `--fixtures DIR`. `run` also takes `--steps` and `--out DIR`
112
+ (default `.emu/run`: numbered `NNN.png` shots and `texts.json`), prints shot paths and the output of `texts`, `log`
113
+ and `state` steps as they run, and exits 1 if the app raised a Lua error. `window` and `serve` take `--port`
114
+ (default 7480, `0` = any free port).
115
+
116
+ While a daemon runs, the same verbs work as client commands (`inkemu tap-text 'Tap me'`):
117
+
118
+ `tap X Y`, `tap-text TEXT`, `double-tap X Y`, `swipe up|down|left|right`, `hold X Y [MS]`,
119
+ `key up|down|left|right|ok|back`, `type TEXT`, `answer yes|no`, `wait DURATION` (`500ms`, `61s`, `2m`),
120
+ `lock`, `unlock`, `reload`, `restart`, `shot [PATH]`, `texts`, `log`, `state`, `resume`, `stop`.
121
+
122
+ `tap-text` taps the last drawn occurrence of the text; if it is not on screen it fails and lists the visible texts.
123
+ Every input advances virtual time by 350 ms. Daemon discovery goes through `<state root>/daemon.json`.
124
+
125
+ An open dialog (`ctx.dialog:confirm`, `ctx.input:text`/`edit`, the host's "Leave app?") is drawn as a plate with its
126
+ title, text or field and `Yes`/`No` or `OK`/`Cancel`, so it shows in shots and `texts`. While it is open, input does
127
+ not reach the app (the log says so); tapping a button (`tap-text Yes`) answers it, as do `answer` and `type`.
128
+ The window shows the same dialogs as native Tk dialogs instead.
129
+
130
+ ### Window keys
131
+
132
+ Mouse: click = tap, drag = swipe, long press = hold. Arrows = side buttons, Enter = ok, Esc = back,
133
+ `L` lock/unlock, `R` reload the app, `]` +1 minute, `}` +1 hour, `S` save a screenshot, `P` pause/resume the clock.
134
+
135
+ ## MCP server
136
+
137
+ `inkemu-mcp` is a stdio MCP server, so an agent can start the app, tap, wait and look at screenshots. In Claude Code,
138
+ from your app project:
139
+
140
+ ```bash
141
+ claude mcp add inkemu -- inkemu-mcp # inkemu installed with uv tool / pipx
142
+ claude mcp add --scope project inkemu -- uv run inkemu-mcp # inkemu is a dev dependency; writes .mcp.json
143
+ ```
144
+
145
+ Other clients take the same command, e.g. `{"mcpServers": {"inkemu": {"command": "inkemu-mcp"}}}`. App paths are
146
+ relative to the server's working directory, which is the project for Claude Code.
147
+
148
+ Tools: `emu_start(app, window=None, net=None, fresh=False, port=0)` (starts a detached daemon, headless and `replay`
149
+ unless asked otherwise, or reuses the running one for the same app; it refuses with `ok: false` when that daemon
150
+ runs in another `window`/`net` mode or `fresh=True` is asked, so call `emu_stop` first), `emu_tap`, `emu_tap_text`,
151
+ `emu_double_tap`, `emu_swipe`, `emu_hold`, `emu_key`, `emu_type`, `emu_answer`, `emu_wait`, `emu_lock`,
152
+ `emu_unlock`, `emu_reload`, `emu_restart`, `emu_screenshot` (PNG image), `emu_texts`, `emu_log`, `emu_resume`,
153
+ `emu_stop`. The daemon listens on 127.0.0.1 only and rejects requests with a foreign `Host`, an `Origin` header or a
154
+ non-JSON content type.
155
+
156
+ ## Network
157
+
158
+ `ctx.net:request` goes through one of three modes:
159
+
160
+ - `replay` (default): answers from fixtures; a request without a fixture gets `err='no_fixture'` and a log line
161
+ naming method, URL and `--net record`. Never touches the network.
162
+ - `record`: makes the real request and saves it as a fixture.
163
+ - `live`: real requests, nothing saved.
164
+
165
+ Fixtures live in `<fixtures dir>/net/` (default `tests/fixtures/<app_id>/net/`, relative to the working directory),
166
+ one `METHOD_host_hash.json` (request key, response status/headers/`body_file`/`delay_ms`) plus a `.body` file.
167
+ POST bodies are matched by SHA-256. A fixture can be written by hand; a malformed one is ignored with a warning.
168
+
169
+ `<state root>/secrets.json` (default `.emu/secrets.json`) is a flat `{"name": "value"}` object. Values are replaced by
170
+ `{{name}}` in recorded URLs, bodies and headers, and `{{name}}` in app files seeded from the project is replaced
171
+ back for `live` and `record` requests, including their percent-encoded forms. A password in the URL
172
+ (`https://user:pass@host`) is always recorded as `{{userinfo}}`. Sensitive headers (`authorization`, `cookie`,
173
+ `*token*`, `*key*`, ...) are never recorded. Keep `secrets.json` out of git.
174
+
175
+ ## State on disk
176
+
177
+ `<state root>/<app_id>/` holds `state.json` (`ctx.state`), `files/` (`ctx.storage`), `lock.json` and `shots/`.
178
+ The state root is `.emu/` in the working directory, or `$INKEMU_STATE_ROOT`. `--fresh` wipes the app state first.
179
+
180
+ ## Supported API
181
+
182
+ Callbacks: `on_load`, `on_resume`, `on_draw(ctx, g)`, `on_input(ctx, ev)` (pointer taps, double taps, swipes and
183
+ holds; side-button keys), `on_tick`, `on_leave`. A `lockscreen` block in the manifest runs its own entry file on
184
+ lock and on every `interval_sec` wake, with `ctx.lock` (`reason`, `done`, `set_interval`, ...).
185
+
186
+ Drawing (`g`): `clear`, `rect`, `round_rect`, `line`, `circle`, `arc`, `polygon`, `polyline`, `text`, `text_box`,
187
+ `image`, `pattern_rect`, `fill_pattern`, plus layers via `ctx.layers`. The frame cap of 1024 commands is enforced.
188
+
189
+ `ctx`: `invalidate`, `after`/timers, `set_tick`, `defer_full_refresh`, `quit`, `log`, `save_state`, `state`, `api`,
190
+ `capabilities`, `clock`, `device`, `fonts`, `storage`/`files`, `package`, `net` (`request`; GET and POST),
191
+ `dialog` (`confirm`, `toast`), `input` (`text`, `edit`), `image`, `qr`, `json`, `hex`, `hash`, `url`, `zlib`,
192
+ `random`, `screen`, `display`, `frontlight`, `system`, `i18n`, `perf`, `gc`, `budget`, `reader` (answers from
193
+ `<fixtures dir>/reader.json`), `lockscreen`, `lock`. `ctx.ui` is not implemented.
194
+
195
+ ## Differences from the device
196
+
197
+ - Fonts are approximate: the system Helvetica, Arial or DejaVu (whichever exists) at fixed line heights 20/24/30,
198
+ so text widths differ from the device; `ctx.fonts:size(px)` picks the nearest of the three, there is no TTF.
199
+ - Lua is 5.5 via [lupa](https://pypi.org/project/lupa/): the firmware reports `_VERSION` "Lua 5.5" in the
200
+ reverse-engineering notes (desktop test setups often run 5.4, whose for-loop variables are not constant).
201
+ Integers are 64-bit here; the device is probably built with 32-bit integers, so keep arithmetic below 2^31.
202
+ - No `ctx.ui`, no BLE, no WebSocket; only GET and POST get a network callback.
203
+ - Layer semantics and error codes are guesses based on the notes.
204
+ - Remote commands (daemon verbs, MCP) freeze the window clock, read-only ones included, so a screenshot is stable;
205
+ `resume`, or `P` in the window, lets time run again.
206
+ - A callback (or the lock screen) that runs more than 200 million Lua instructions is aborted as an app error
207
+ ("callback exceeded the instruction budget ... - infinite loop?"); the device has its own, unknown budget.
208
+ Time spent inside C functions such as `string.rep` or pattern matching is not counted.
209
+ - The app sees `debug == false` instead of `nil` (lupa reads that global on every call into Lua), and no
210
+ `python`, `io`, `os` or `package.searchpath`. An app that sets `debug = nil` itself and then installs an erroring
211
+ metatable on `_G` can still crash the emulator process (not escape it).
212
+
213
+ ## Development
214
+
215
+ ```bash
216
+ uv sync
217
+ uv run pytest
218
+ uv run ruff check && uv run ruff format --check
219
+ uv run python docs/make_images.py # regenerate the README screenshots
220
+ ```
221
+
222
+ ## Credits
223
+
224
+ The API notes come from [omer-faruq-xteink/touch-licorice-apps](https://github.com/omer-faruq-xteink/touch-licorice-apps)
225
+ (`docs/firmware-notes.md`) and kycube/x4pro-emu. MIT licence, see
226
+ [LICENSE](https://github.com/ermakov-oleg/inkemu/blob/main/LICENSE).
inkemu-0.1.0/README.md ADDED
@@ -0,0 +1,194 @@
1
+ # inkemu
2
+
3
+ [![CI](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml/badge.svg)](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml)
4
+ [![PyPI](https://img.shields.io/pypi/v/inkemu)](https://pypi.org/project/inkemu/)
5
+ [![Python](https://img.shields.io/pypi/pyversions/inkemu)](https://pypi.org/project/inkemu/)
6
+ [![License: MIT](https://img.shields.io/badge/license-MIT-blue)](https://github.com/ermakov-oleg/inkemu/blob/main/LICENSE)
7
+
8
+ Run and test Lua apps for the Xteink X4 Pro e-ink reader (the "InkApp" host of the XTOS Licorice firmware) on your
9
+ desktop. inkemu loads an app folder (`manifest.json` + `index.lua`), renders its 480x800 1-bpp screen and lets you
10
+ drive it from a window, a one-shot CLI run, a pytest test or an AI agent over MCP, with virtual time and recorded
11
+ network responses.
12
+
13
+ <p align="center">
14
+ <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">
15
+ &nbsp;&nbsp;
16
+ <img src="https://raw.githubusercontent.com/ermakov-oleg/inkemu/main/docs/images/lockscreen.png" width="300" alt="The lock screen of the hello example">
17
+ </p>
18
+
19
+ The device API is not publicly documented. Everything here is built from community reverse-engineering notes, so
20
+ treat inkemu as a development aid, not as a reference of the firmware.
21
+
22
+ ## Install
23
+
24
+ ```bash
25
+ uv tool install inkemu # or: pipx install inkemu
26
+ ```
27
+
28
+ or as a dev dependency of your app project: `uv add --dev inkemu` (then prefix the commands with `uv run`).
29
+
30
+ Python 3.11+, macOS or Linux. Everything is headless except the window, which needs Tk (`python3-tk` on
31
+ Debian/Ubuntu). CI runs on uv-managed Pythons (Tk 9); with the python.org builds (Tk 8.6) the window has been seen to
32
+ crash on macOS 26.
33
+
34
+ ## Quick start
35
+
36
+ An app is a folder with `manifest.json` and `index.lua`; [`examples/hello`](https://github.com/ermakov-oleg/inkemu/tree/main/examples/hello)
37
+ is a small one with a lock screen (it is not in the package: clone the repository or copy the folder).
38
+
39
+ ```bash
40
+ inkemu window examples/hello # a window: click = tap, drag = swipe, arrows/Enter/Esc = side buttons
41
+ ```
42
+
43
+ ```bash
44
+ # one-shot, no window: numbered PNG shots and texts.json go to .emu/run
45
+ inkemu run examples/hello --fresh --time 2026-11-20T09:41 --steps "tap-text 'Tap me'; wait 61s; shot; texts"
46
+ ```
47
+
48
+ The same app in a pytest test, with the network answered from recorded fixtures:
49
+
50
+ ```bash
51
+ inkemu run apps/weather --net record --steps "wait 5s" # once: real requests saved to tests/fixtures/<app_id>/net/
52
+ ```
53
+
54
+ ```python
55
+ from inkemu import Emu
56
+
57
+
58
+ def test_weather(tmp_path):
59
+ emu = Emu("apps/weather", state_dir=tmp_path / "state", start_time="2026-11-20T09:00:00") # net="replay"
60
+ emu.wait("5s")
61
+ assert emu.has_text("Berlin")
62
+ emu.tap_text("Refresh")
63
+ assert emu.errors == [] # Lua tracebacks are collected, never raised
64
+ ```
65
+
66
+ Other members: `emu.tap(x, y)`, `emu.double_tap()`, `emu.hold()`, `emu.swipe(direction)`, `emu.key(name)`,
67
+ `emu.type_text()`, `emu.answer(ok)`, `emu.lock()`, `emu.unlock()`, `emu.restart()`, `emu.texts()`, `emu.status()`,
68
+ `emu.log`, `emu.warnings`, `emu.shot()` (a Pillow image), `emu.save_shot(path)`.
69
+
70
+ ## Commands
71
+
72
+ ```bash
73
+ inkemu window APP # Tk window + command daemon
74
+ inkemu run APP --steps "..." # one-shot, no window
75
+ inkemu serve APP # headless daemon in the foreground
76
+ ```
77
+
78
+ Common options: `--net replay|record|live` (default `replay`), `--fresh` (wipe the app state first),
79
+ `--time ISO8601` (virtual start time), `--state DIR`, `--fixtures DIR`. `run` also takes `--steps` and `--out DIR`
80
+ (default `.emu/run`: numbered `NNN.png` shots and `texts.json`), prints shot paths and the output of `texts`, `log`
81
+ and `state` steps as they run, and exits 1 if the app raised a Lua error. `window` and `serve` take `--port`
82
+ (default 7480, `0` = any free port).
83
+
84
+ While a daemon runs, the same verbs work as client commands (`inkemu tap-text 'Tap me'`):
85
+
86
+ `tap X Y`, `tap-text TEXT`, `double-tap X Y`, `swipe up|down|left|right`, `hold X Y [MS]`,
87
+ `key up|down|left|right|ok|back`, `type TEXT`, `answer yes|no`, `wait DURATION` (`500ms`, `61s`, `2m`),
88
+ `lock`, `unlock`, `reload`, `restart`, `shot [PATH]`, `texts`, `log`, `state`, `resume`, `stop`.
89
+
90
+ `tap-text` taps the last drawn occurrence of the text; if it is not on screen it fails and lists the visible texts.
91
+ Every input advances virtual time by 350 ms. Daemon discovery goes through `<state root>/daemon.json`.
92
+
93
+ An open dialog (`ctx.dialog:confirm`, `ctx.input:text`/`edit`, the host's "Leave app?") is drawn as a plate with its
94
+ title, text or field and `Yes`/`No` or `OK`/`Cancel`, so it shows in shots and `texts`. While it is open, input does
95
+ not reach the app (the log says so); tapping a button (`tap-text Yes`) answers it, as do `answer` and `type`.
96
+ The window shows the same dialogs as native Tk dialogs instead.
97
+
98
+ ### Window keys
99
+
100
+ Mouse: click = tap, drag = swipe, long press = hold. Arrows = side buttons, Enter = ok, Esc = back,
101
+ `L` lock/unlock, `R` reload the app, `]` +1 minute, `}` +1 hour, `S` save a screenshot, `P` pause/resume the clock.
102
+
103
+ ## MCP server
104
+
105
+ `inkemu-mcp` is a stdio MCP server, so an agent can start the app, tap, wait and look at screenshots. In Claude Code,
106
+ from your app project:
107
+
108
+ ```bash
109
+ claude mcp add inkemu -- inkemu-mcp # inkemu installed with uv tool / pipx
110
+ claude mcp add --scope project inkemu -- uv run inkemu-mcp # inkemu is a dev dependency; writes .mcp.json
111
+ ```
112
+
113
+ Other clients take the same command, e.g. `{"mcpServers": {"inkemu": {"command": "inkemu-mcp"}}}`. App paths are
114
+ relative to the server's working directory, which is the project for Claude Code.
115
+
116
+ Tools: `emu_start(app, window=None, net=None, fresh=False, port=0)` (starts a detached daemon, headless and `replay`
117
+ unless asked otherwise, or reuses the running one for the same app; it refuses with `ok: false` when that daemon
118
+ runs in another `window`/`net` mode or `fresh=True` is asked, so call `emu_stop` first), `emu_tap`, `emu_tap_text`,
119
+ `emu_double_tap`, `emu_swipe`, `emu_hold`, `emu_key`, `emu_type`, `emu_answer`, `emu_wait`, `emu_lock`,
120
+ `emu_unlock`, `emu_reload`, `emu_restart`, `emu_screenshot` (PNG image), `emu_texts`, `emu_log`, `emu_resume`,
121
+ `emu_stop`. The daemon listens on 127.0.0.1 only and rejects requests with a foreign `Host`, an `Origin` header or a
122
+ non-JSON content type.
123
+
124
+ ## Network
125
+
126
+ `ctx.net:request` goes through one of three modes:
127
+
128
+ - `replay` (default): answers from fixtures; a request without a fixture gets `err='no_fixture'` and a log line
129
+ naming method, URL and `--net record`. Never touches the network.
130
+ - `record`: makes the real request and saves it as a fixture.
131
+ - `live`: real requests, nothing saved.
132
+
133
+ Fixtures live in `<fixtures dir>/net/` (default `tests/fixtures/<app_id>/net/`, relative to the working directory),
134
+ one `METHOD_host_hash.json` (request key, response status/headers/`body_file`/`delay_ms`) plus a `.body` file.
135
+ POST bodies are matched by SHA-256. A fixture can be written by hand; a malformed one is ignored with a warning.
136
+
137
+ `<state root>/secrets.json` (default `.emu/secrets.json`) is a flat `{"name": "value"}` object. Values are replaced by
138
+ `{{name}}` in recorded URLs, bodies and headers, and `{{name}}` in app files seeded from the project is replaced
139
+ back for `live` and `record` requests, including their percent-encoded forms. A password in the URL
140
+ (`https://user:pass@host`) is always recorded as `{{userinfo}}`. Sensitive headers (`authorization`, `cookie`,
141
+ `*token*`, `*key*`, ...) are never recorded. Keep `secrets.json` out of git.
142
+
143
+ ## State on disk
144
+
145
+ `<state root>/<app_id>/` holds `state.json` (`ctx.state`), `files/` (`ctx.storage`), `lock.json` and `shots/`.
146
+ The state root is `.emu/` in the working directory, or `$INKEMU_STATE_ROOT`. `--fresh` wipes the app state first.
147
+
148
+ ## Supported API
149
+
150
+ Callbacks: `on_load`, `on_resume`, `on_draw(ctx, g)`, `on_input(ctx, ev)` (pointer taps, double taps, swipes and
151
+ holds; side-button keys), `on_tick`, `on_leave`. A `lockscreen` block in the manifest runs its own entry file on
152
+ lock and on every `interval_sec` wake, with `ctx.lock` (`reason`, `done`, `set_interval`, ...).
153
+
154
+ Drawing (`g`): `clear`, `rect`, `round_rect`, `line`, `circle`, `arc`, `polygon`, `polyline`, `text`, `text_box`,
155
+ `image`, `pattern_rect`, `fill_pattern`, plus layers via `ctx.layers`. The frame cap of 1024 commands is enforced.
156
+
157
+ `ctx`: `invalidate`, `after`/timers, `set_tick`, `defer_full_refresh`, `quit`, `log`, `save_state`, `state`, `api`,
158
+ `capabilities`, `clock`, `device`, `fonts`, `storage`/`files`, `package`, `net` (`request`; GET and POST),
159
+ `dialog` (`confirm`, `toast`), `input` (`text`, `edit`), `image`, `qr`, `json`, `hex`, `hash`, `url`, `zlib`,
160
+ `random`, `screen`, `display`, `frontlight`, `system`, `i18n`, `perf`, `gc`, `budget`, `reader` (answers from
161
+ `<fixtures dir>/reader.json`), `lockscreen`, `lock`. `ctx.ui` is not implemented.
162
+
163
+ ## Differences from the device
164
+
165
+ - Fonts are approximate: the system Helvetica, Arial or DejaVu (whichever exists) at fixed line heights 20/24/30,
166
+ so text widths differ from the device; `ctx.fonts:size(px)` picks the nearest of the three, there is no TTF.
167
+ - Lua is 5.5 via [lupa](https://pypi.org/project/lupa/): the firmware reports `_VERSION` "Lua 5.5" in the
168
+ reverse-engineering notes (desktop test setups often run 5.4, whose for-loop variables are not constant).
169
+ Integers are 64-bit here; the device is probably built with 32-bit integers, so keep arithmetic below 2^31.
170
+ - No `ctx.ui`, no BLE, no WebSocket; only GET and POST get a network callback.
171
+ - Layer semantics and error codes are guesses based on the notes.
172
+ - Remote commands (daemon verbs, MCP) freeze the window clock, read-only ones included, so a screenshot is stable;
173
+ `resume`, or `P` in the window, lets time run again.
174
+ - A callback (or the lock screen) that runs more than 200 million Lua instructions is aborted as an app error
175
+ ("callback exceeded the instruction budget ... - infinite loop?"); the device has its own, unknown budget.
176
+ Time spent inside C functions such as `string.rep` or pattern matching is not counted.
177
+ - The app sees `debug == false` instead of `nil` (lupa reads that global on every call into Lua), and no
178
+ `python`, `io`, `os` or `package.searchpath`. An app that sets `debug = nil` itself and then installs an erroring
179
+ metatable on `_G` can still crash the emulator process (not escape it).
180
+
181
+ ## Development
182
+
183
+ ```bash
184
+ uv sync
185
+ uv run pytest
186
+ uv run ruff check && uv run ruff format --check
187
+ uv run python docs/make_images.py # regenerate the README screenshots
188
+ ```
189
+
190
+ ## Credits
191
+
192
+ The API notes come from [omer-faruq-xteink/touch-licorice-apps](https://github.com/omer-faruq-xteink/touch-licorice-apps)
193
+ (`docs/firmware-notes.md`) and kycube/x4pro-emu. MIT licence, see
194
+ [LICENSE](https://github.com/ermakov-oleg/inkemu/blob/main/LICENSE).
@@ -0,0 +1,115 @@
1
+ -- Hello: the smallest useful InkApp. Clock, battery, a tap counter kept in ctx.state.
2
+ -- Screen 480x800 portrait, 1 bpp. Host callbacks: on_load, on_resume, on_draw, on_input, on_leave.
3
+
4
+ local W, H = 480, 800
5
+ local BTN = { x = 90, y = 560, w = 300, h = 80 }
6
+ local RESET = { x = 140, y = 680, w = 200, h = 56 }
7
+
8
+ local S -- ctx.state, persisted by the host between runs
9
+ local timer
10
+ local last_err
11
+
12
+ local function refresh() pcall(function() ctx:invalidate() end) end
13
+
14
+ local function font(name)
15
+ local ok, f = pcall(function() return ctx.fonts[name] end)
16
+ return ok and f or nil
17
+ end
18
+
19
+ local function now()
20
+ local ok, t = pcall(function() return ctx.clock:now() end)
21
+ if ok and type(t) == 'table' then return t end
22
+ end
23
+
24
+ local function battery()
25
+ local ok, b = pcall(function() return ctx.device:battery() end)
26
+ if ok and type(b) == 'table' then return b end
27
+ end
28
+
29
+ local function inside(b, x, y)
30
+ return x >= b.x and x < b.x + b.w and y >= b.y and y < b.y + b.h
31
+ end
32
+
33
+ -- redraw on the next minute boundary, so the clock stays right without waking every second
34
+ local function schedule()
35
+ pcall(function() if timer then timer:cancel() end end)
36
+ local t = now()
37
+ local sec = t and tonumber(t.second) or 0
38
+ local ok, h = pcall(function()
39
+ return ctx:after((60 - sec) * 1000 + 200, function() refresh(); schedule() end)
40
+ end)
41
+ timer = ok and h or nil
42
+ end
43
+
44
+ local function button(g, b, label, f)
45
+ g:rect(b.x, b.y, b.w, b.h)
46
+ g:rect(b.x + 1, b.y + 1, b.w - 2, b.h - 2)
47
+ g:text(b.x + b.w // 2, b.y + b.h // 2, label, { font = f, align = 'center', valign = 'middle' })
48
+ end
49
+
50
+ function on_load(c)
51
+ c = c or ctx
52
+ if type(c.state) ~= 'table' then c.state = {} end
53
+ S = c.state
54
+ S.taps = tonumber(S.taps) or 0
55
+ schedule()
56
+ end
57
+
58
+ function on_resume(c)
59
+ refresh(); schedule()
60
+ end
61
+
62
+ function on_draw(c, g)
63
+ if not g then return end
64
+ local ok, e = pcall(function()
65
+ g:clear(0)
66
+ local L, M, Sm = font('large'), font('medium'), font('small')
67
+
68
+ g:text(W // 2, 40, 'Hello, X4 Pro!', { font = L, align = 'center' })
69
+ g:line(24, 90, W - 24, 90)
70
+
71
+ local t = now()
72
+ if t then
73
+ g:text(W // 2, 160, string.format('%02d:%02d', t.hour or 0, t.minute or 0), { font = L, align = 'center' })
74
+ else
75
+ g:text(W // 2, 160, 'clock not set', { font = M, align = 'center' })
76
+ end
77
+
78
+ local b = battery()
79
+ if b then
80
+ local s = 'Battery ' .. tostring(b.percent or '?') .. '%' .. (b.charging and ' (charging)' or '')
81
+ g:text(W // 2, 230, s, { font = M, align = 'center' })
82
+ end
83
+
84
+ g:text(W // 2, 380, 'Taps: ' .. tostring(S and S.taps or 0), { font = L, align = 'center' })
85
+
86
+ button(g, BTN, 'Tap me', L)
87
+ button(g, RESET, 'Reset', M)
88
+ g:text(W // 2, H - 40, 'Home pad: leave app', { font = Sm, align = 'center' })
89
+
90
+ if last_err then g:text(10, H - 80, 'err: ' .. tostring(last_err):sub(1, 50), { font = Sm }) end
91
+ end)
92
+ if not ok then pcall(function() g:text(10, 10, 'draw error: ' .. tostring(e):sub(1, 40)) end) end
93
+ end
94
+
95
+ function on_input(c, ev)
96
+ if type(ev) ~= 'table' then return false end
97
+ local ok, handled = pcall(function()
98
+ if ev.type == 'pointer' and ev.phase == 'up' and ev.gesture == 'tap' then
99
+ local x, y = ev.x or 0, ev.y or 0
100
+ if inside(BTN, x, y) then S.taps = S.taps + 1; refresh(); return true end
101
+ if inside(RESET, x, y) then S.taps = 0; refresh(); return true end
102
+ return true
103
+ end
104
+ if ev.type == 'key' and ev.phase ~= 'up' and (ev.key == 'up' or ev.key == 'right') then
105
+ S.taps = S.taps + 1; refresh(); return true
106
+ end
107
+ return false
108
+ end)
109
+ if not ok then last_err = handled; refresh(); return true end
110
+ return handled
111
+ end
112
+
113
+ function on_leave(c)
114
+ pcall(function() if timer then timer:cancel() end end)
115
+ end
@@ -0,0 +1,27 @@
1
+ -- Lock screen for Hello: big clock, date and the tap count. Woken every interval_sec by the host.
2
+
3
+ local W, H = 480, 800
4
+ local DAYS = { 'Sunday', 'Monday', 'Tuesday', 'Wednesday', 'Thursday', 'Friday', 'Saturday' }
5
+ local MONTHS = { 'January', 'February', 'March', 'April', 'May', 'June',
6
+ 'July', 'August', 'September', 'October', 'November', 'December' }
7
+
8
+ function on_load(c) end
9
+
10
+ function on_draw(c, g)
11
+ if not g then return end
12
+ local ok, e = pcall(function()
13
+ g:clear(0)
14
+ local t = c.clock:now()
15
+ g:round_rect(90, 240, W - 180, 120, 16)
16
+ g:text(W // 2, 300, string.format('%02d:%02d', t.hour, t.minute), { font = c.fonts.large, align = 'center', valign = 'middle' })
17
+ g:text(W // 2, 400, string.format('%s, %d %s', DAYS[t.wday], t.day, MONTHS[t.month]),
18
+ { font = c.fonts.large, align = 'center' })
19
+ g:line(120, 460, W - 120, 460)
20
+ local taps = type(c.state) == 'table' and tonumber(c.state.taps) or 0
21
+ g:text(W // 2, 490, 'Taps so far: ' .. taps, { font = c.fonts.medium, align = 'center' })
22
+ local b = c.device:battery()
23
+ g:text(W // 2, H - 60, 'Battery ' .. tostring(b.percent) .. '%', { font = c.fonts.small, align = 'center' })
24
+ end)
25
+ if not ok then g:text(10, 10, 'lock error: ' .. tostring(e):sub(1, 40)) end
26
+ c.lock:done()
27
+ end
@@ -0,0 +1,16 @@
1
+ {
2
+ "app_id": "hello",
3
+ "display_name": "Hello",
4
+ "version": "0.1.0",
5
+ "author": "inkemu",
6
+ "description": "Hello world for XTOS Licorice: clock, battery and a tap counter.",
7
+ "entry": "index.lua",
8
+ "api": "2.2",
9
+ "permissions": [],
10
+ "lockscreen": {
11
+ "enabled": true,
12
+ "entry": "lockscreen.lua",
13
+ "interval_sec": 60,
14
+ "net": false
15
+ }
16
+ }