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.
- inkemu-0.1.0/.gitignore +6 -0
- inkemu-0.1.0/LICENSE +21 -0
- inkemu-0.1.0/PKG-INFO +226 -0
- inkemu-0.1.0/README.md +194 -0
- inkemu-0.1.0/examples/hello/index.lua +115 -0
- inkemu-0.1.0/examples/hello/lockscreen.lua +27 -0
- inkemu-0.1.0/examples/hello/manifest.json +16 -0
- inkemu-0.1.0/pyproject.toml +68 -0
- inkemu-0.1.0/src/inkemu/__init__.py +3 -0
- inkemu-0.1.0/src/inkemu/__main__.py +5 -0
- inkemu-0.1.0/src/inkemu/cli.py +190 -0
- inkemu-0.1.0/src/inkemu/clock.py +90 -0
- inkemu-0.1.0/src/inkemu/ctx_basic.py +656 -0
- inkemu-0.1.0/src/inkemu/ctx_ui.py +196 -0
- inkemu-0.1.0/src/inkemu/daemon.py +386 -0
- inkemu-0.1.0/src/inkemu/draw.py +297 -0
- inkemu-0.1.0/src/inkemu/emu.py +791 -0
- inkemu-0.1.0/src/inkemu/fonts.py +34 -0
- inkemu-0.1.0/src/inkemu/lockscreen.py +85 -0
- inkemu-0.1.0/src/inkemu/lua_env.py +159 -0
- inkemu-0.1.0/src/inkemu/mcp_server.py +228 -0
- inkemu-0.1.0/src/inkemu/net.py +411 -0
- inkemu-0.1.0/src/inkemu/paths.py +23 -0
- inkemu-0.1.0/src/inkemu/window.py +277 -0
- inkemu-0.1.0/tests/conftest.py +48 -0
- inkemu-0.1.0/tests/test_budget.py +120 -0
- inkemu-0.1.0/tests/test_cli.py +147 -0
- inkemu-0.1.0/tests/test_clock.py +71 -0
- inkemu-0.1.0/tests/test_ctx_basic.py +442 -0
- inkemu-0.1.0/tests/test_ctx_ui.py +308 -0
- inkemu-0.1.0/tests/test_daemon.py +264 -0
- inkemu-0.1.0/tests/test_dialogs.py +97 -0
- inkemu-0.1.0/tests/test_draw.py +203 -0
- inkemu-0.1.0/tests/test_hello.py +35 -0
- inkemu-0.1.0/tests/test_input.py +169 -0
- inkemu-0.1.0/tests/test_lifecycle.py +328 -0
- inkemu-0.1.0/tests/test_lockscreen.py +184 -0
- inkemu-0.1.0/tests/test_mcp.py +55 -0
- inkemu-0.1.0/tests/test_mcp_tools.py +58 -0
- inkemu-0.1.0/tests/test_net.py +441 -0
- inkemu-0.1.0/tests/test_sandbox.py +47 -0
- inkemu-0.1.0/tests/test_window.py +328 -0
- inkemu-0.1.0/uv.lock +1047 -0
inkemu-0.1.0/.gitignore
ADDED
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
|
+
[](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml)
|
|
36
|
+
[](https://pypi.org/project/inkemu/)
|
|
37
|
+
[](https://pypi.org/project/inkemu/)
|
|
38
|
+
[](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
|
+
|
|
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
|
+
[](https://github.com/ermakov-oleg/inkemu/actions/workflows/ci.yml)
|
|
4
|
+
[](https://pypi.org/project/inkemu/)
|
|
5
|
+
[](https://pypi.org/project/inkemu/)
|
|
6
|
+
[](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
|
+
|
|
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
|
+
}
|