diff --git a/.claude/skills/nextion-hmi/SKILL.md b/.claude/skills/nextion-hmi/SKILL.md new file mode 100644 index 0000000..0f66e21 --- /dev/null +++ b/.claude/skills/nextion-hmi/SKILL.md @@ -0,0 +1,46 @@ +--- +name: nextion-hmi +description: Create, inspect, edit and render Nextion display projects (.HMI files) without Nextion Editor, using the nxhmi tools in this repo. Use when the user wants to build or change a Nextion screen, page, button, text, slider, picture or font, look at how a page looks, or check an .HMI file. +--- + +# Working on Nextion .HMI projects + +Prefer the **`nxhmi` MCP tools** (configured in `.mcp.json`); fall back to the CLI +(`PYTHONPATH=src python -m nxhmi ...`) or the Python API (`src/nxhmi`) when they are not available. + +## Loop + +1. `info` -- model, display size, pages, components, pictures, fonts. +2. `get_page` -- the components of one page with readable values. +3. Change things: `set_attributes`, `set_event`, `add_component`, `remove_component`, `add_page`, + `add_picture`, `add_font`. Every call saves the file. +4. `verify` -- all checksums must be ok. +5. `render_page` -- **look at the result** (it matches Nextion Editor's canvas) before telling the + user it is done. Fix overlaps, clipped text and wrong colours you see. + +Back up the user's file first (copy it) unless they said not to; edits write in place. + +## Values + +- Attributes accept readable values: `xcen`/`ycen` `left|center|right` / `up|center|down`, + `sta` `crop image|solid color|image` (page: `no background|solid color|image`), `style` + `flat|border|3D_Down|3D_Up` (+`3D_Auto` for buttons), colours as `#rrggbb` (stored as RGB565, + so they snap to the nearest 5/6/5-bit colour). Numbers always work too. +- `schema ` lists every attribute of a component kind with defaults and allowed values; + `list_kinds` lists the kinds (`button`, `text`, `number`, `slider`, `progress_bar`, ...). +- Coordinates: `x`, `y`, `w`, `h` in pixels; `endx`/`endy` are updated automatically. +- Text needs a font: `font` is a font id. A new project has **no fonts** -- call `add_font` + first (height in px; no TrueType path = bundled CC0 font). `txt_maxl` must be >= the text length. +- Pictures: `add_picture` returns an id for `pic` / `picc` (crop) / `pic2` etc. Basic-series + displays only (Intelligent compressed pictures are not supported yet). +- Event code is Nextion script, one line per list item, e.g. `["page settings"]`, + `["n0.val++", "t0.txt=\"hi\""]`. Events: `codesdown` (press), `codesup` (release), + `codesload` / `codesloadend` (page pre/post-initialize), `codesunload`, `codestimer`, `codesslide`. +- `objname` must be unique per page; `add_component` picks `b0`, `t1`, ... if no name is given. + +## Limits (see docs/COVERAGE.md) + +- Writes projects for Nextion Editor 1.68.2; the user still compiles/uploads the `.tft` with the + Editor (or Nexus for uploading). nxhmi cannot compile `.tft` files yet. +- Rendering: radio buttons are ~95 % exact, QR codes are a placeholder, Intelligent-only + components are not drawn. diff --git a/.mcp.json b/.mcp.json new file mode 100644 index 0000000..b55cfbf --- /dev/null +++ b/.mcp.json @@ -0,0 +1,9 @@ +{ + "mcpServers": { + "nxhmi": { + "command": "python", + "args": ["-m", "nxhmi.mcp_server"], + "env": {"PYTHONPATH": "src"} + } + } +} diff --git a/CLAUDE.md b/CLAUDE.md index 1a63b41..5447ed5 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -20,7 +20,10 @@ src/nxhmi/ render.py page renderer matching the Editor canvas tft.py .tft research helpers (layout table, same-length trailer patch) cli.py python -m nxhmi ... + mcp_server.py MCP server (stdio JSON-RPC, no deps) -- tools for Claude incl. render_page images examples/make_demo.py builds demo/ (demo.HMI, decoded/, render/) +.mcp.json registers the MCP server for Claude Code in this repo +.claude/skills/nextion-hmi/SKILL.md how to use the tools on a user's project (keep in sync with mcp_server.py) tests/ unittest suite; fixtures/demo_editor_saved.HMI = the demo re-saved by the Editor tools/ template generator docs/ FORMAT.md (spec), RENDER.md, COVERAGE.md, NOTES.md (open points, what was tried) @@ -56,5 +59,6 @@ new build writes different bytes, document the difference in docs/FORMAT.md per - Every format claim in `docs/FORMAT.md` needs evidence (byte-identical Editor output, or the Editor accepting a file we wrote). Mark guesses as **OPEN**. - Keep `docs/COVERAGE.md` and the README coverage table current when something is added. +- New user-facing features get an MCP tool (with a test in `tests/test_mcp.py`) and a line in the skill. - Writers must stay byte-identical to the Editor where we have samples; add a test when a new rule is learned (see `tests/test_render.py` for the style: one rule, one measured expectation). diff --git a/README.md b/README.md index aaa2007..8a70e3f 100644 --- a/README.md +++ b/README.md @@ -73,6 +73,26 @@ python -m nxhmi render project.HMI pngs/ # one PNG per page python -m nxhmi kinds # component kinds for `add` ``` +## Use with Claude + +The repo is set up for Claude (Claude Code, Claude Desktop or any MCP client): + +- **MCP server** -- `python -m nxhmi.mcp_server` (stdio, no dependencies). Tools: `info`, + `get_page`, `set_attributes`, `set_event`, `add_component`, `remove_component`, `add_page`, + `new_project`, `add_picture`, `add_font`, `verify`, `list_kinds`, `schema`, and + **`render_page`, which returns the page as an image** so the model can see what it built. + Attribute values can be readable names (`"xcen": "center"`, `"bco": "#ff0000"`). + `.mcp.json` registers it automatically when Claude Code runs in this repo; elsewhere add: + + ```json + {"mcpServers": {"nxhmi": {"command": "python", "args": ["-m", "nxhmi.mcp_server"], + "env": {"PYTHONPATH": "/path/to/openhmi-nx/src"}}}} + ``` + +- **Skill** -- [.claude/skills/nextion-hmi/SKILL.md](.claude/skills/nextion-hmi/SKILL.md): the + edit -> verify -> render loop, value names, fonts/pictures, event code, limits. +- **Machine-readable CLI** -- `info --json`, `schema `, `dump --page`. + ## Python ```python diff --git a/src/nxhmi/cli.py b/src/nxhmi/cli.py index 7c81651..4debd3d 100644 --- a/src/nxhmi/cli.py +++ b/src/nxhmi/cli.py @@ -11,6 +11,10 @@ from .page import Page def cmd_info(a): + if a.json: + from .mcp_server import t_info + print(json.dumps(t_info(a.hmi), indent=1, ensure_ascii=False)) + return h = HMIFile.load(a.hmi) t0, t1 = h.table_ok() print("file table: primary %s, backup %s" % ("ok" if t0 else "BAD", "ok" if t1 else "BAD")) @@ -140,6 +144,11 @@ def cmd_render(a): print("wrote", path) +def cmd_schema(a): + from .mcp_server import t_schema + print(json.dumps(t_schema(a.kind), indent=1, ensure_ascii=False)) + + def cmd_kinds(a): from . import components for k in components.kinds(): @@ -159,7 +168,11 @@ def cmd_dump(a): def main(argv=None): ap = argparse.ArgumentParser(prog="nxhmi", description="Read, verify and write Nextion Editor .HMI projects") sub = ap.add_subparsers(dest="cmd", required=True) - s = sub.add_parser("info", help="list entries, pages and checksum status"); s.add_argument("hmi"); s.set_defaults(f=cmd_info) + s = sub.add_parser("info", help="list entries, pages and checksum status"); s.add_argument("hmi") + s.add_argument("--json", action="store_true", help="machine-readable overview (pages, components, fonts, ...)") + s.set_defaults(f=cmd_info) + s = sub.add_parser("schema", help="attributes of a component kind (types, defaults, allowed values)") + s.add_argument("kind"); s.set_defaults(f=cmd_schema) s = sub.add_parser("verify", help="check every checksum"); s.add_argument("hmi", nargs="+"); s.set_defaults(f=cmd_verify) s = sub.add_parser("decode", help="HMI -> folder of JSON/text"); s.add_argument("hmi"); s.add_argument("out") s.add_argument("--encoding", default="latin-1"); s.add_argument("--raw", action="store_true", help="numbers instead of names/colours") diff --git a/src/nxhmi/mcp_server.py b/src/nxhmi/mcp_server.py new file mode 100644 index 0000000..cff7f8c --- /dev/null +++ b/src/nxhmi/mcp_server.py @@ -0,0 +1,311 @@ +"""MCP server for Claude (and other MCP clients): work on Nextion .HMI projects through tool calls. + + python -m nxhmi.mcp_server # stdio, newline-delimited JSON-RPC 2.0 (Model Context Protocol) + +No dependencies (Pillow is only needed for render_page / add_picture / add_font). Every tool takes +the project path and reads/writes the file itself, so calls are independent. ``render_page`` +returns a PNG image so the model can look at the result. +""" +from __future__ import annotations + +import base64 +import io +import json +import os +import sys +import traceback + +from . import __version__, components as C, enums, project +from .container import HMIFile +from .page import Page + +PROTOCOL = "2025-06-18" + + +# ----------------------------------------------------------------------------- helpers +def _load(path): + return HMIFile.load(path) + + +def _pages(h): + out = {} + for e in h.live(): + if e.name.endswith(".pa"): + out[Page.parse(h.read(e.name)).name] = e.name + return out + + +def _page(h, name): + pages = _pages(h) + if name not in pages: + raise ValueError("no page %r; pages: %s" % (name, ", ".join(pages))) + return pages[name], Page.parse(h.read(pages[name])) + + +def _component_json(c): + ctype = c.get("type") + att = {} + for a in c.attrs(): + kind, value = a.decoded() + att[a.name] = enums.to_label(ctype, a.name, kind, value) + ev = {g.name: [r.decode("latin-1") for r in g.records] for g in c.groups if g.name != "att" and g.records} + kind = C.TYPES.get(ctype, {}).get("kind", "type%d" % ctype) + return {"name": c.name, "kind": kind, "attributes": att, "events": ev} + + +def _coerce(c, name, value): + a = c.attr(name) + if a is None: + raise ValueError("component %r has no attribute %r" % (c.name, name)) + kind, _ = a.decoded() + if kind in ("u8", "u16", "u32"): + value = enums.from_label(c.get("type"), name, kind, value) + return value + + +# ----------------------------------------------------------------------------- tools +def t_info(path): + h = _load(path) + main = project.parse_main(h.read("main.HMI")) + pages = [] + for name, entry in _pages(h).items(): + p = Page.parse(h.read(entry)) + pages.append({"page": name, "entry": entry, "components": [c.name for c in p.components[1:]]}) + return {"model": main.get("model", main["model_id"]), "size": project.project_size(h), "pages": pages, + "pictures": sorted(n for n in h.names() if n.endswith(".i")), + "fonts": sorted(n for n in h.names() if n.endswith(".zi")), + "program_s": h.read("Program.s").decode("latin-1")} + + +def t_get_page(path, page): + _, p = _page(_load(path), page) + return {"page": page, "components": [_component_json(c) for c in p.components]} + + +def t_set_attributes(path, page, component, attributes): + h = _load(path) + entry, p = _page(h, page) + c = p.component(component) + if c is None: + raise ValueError("no component %r on page %r" % (component, page)) + for k, v in attributes.items(): + c.set(k, _coerce(c, k, v)) + C._fix_ends(c) + h.write(entry, p.pack()) + h.save(path) + return _component_json(c) + + +def t_set_event(path, page, component, event, lines): + h = _load(path) + entry, p = _page(h, page) + c = p.component(component) + if c is None: + raise ValueError("no component %r on page %r" % (component, page)) + c.set_event(event, lines) + h.write(entry, p.pack()) + h.save(path) + return _component_json(c) + + +def t_add_component(path, page, kind, name=None, attributes=None, events=None): + h = _load(path) + entry, p = _page(h, page) + tmp = C.make(kind, "tmp", 0) + kw = {k: _coerce(tmp, k, v) for k, v in (attributes or {}).items()} + c = C.add(p, kind, name, events=events or {}, **kw) + h.write(entry, p.pack()) + h.save(path) + return _component_json(c) + + +def t_remove_component(path, page, component): + h = _load(path) + entry, p = _page(h, page) + before = len(p.components) + p.components = [c for c in p.components if c.name != component or c is p.components[0]] + if len(p.components) == before: + raise ValueError("no component %r on page %r" % (component, page)) + h.write(entry, p.pack()) + h.save(path) + return {"removed": component} + + +def t_add_page(path, name, attributes=None): + h = _load(path) + w, hh = project.project_size(h) + p = project.add_page(h, name, w=w, h=hh) + for k, v in (attributes or {}).items(): + p.components[0].set(k, _coerce(p.components[0], k, v)) + entry = _pages(h)[name] + h.write(entry, p.pack()) + h.save(path) + return {"page": name, "entry": entry} + + +def t_new_project(path, model="NX4832T035_011", first_page="page0"): + if os.path.exists(path): + raise ValueError("%s exists; refusing to overwrite" % path) + project.new_project(model, first_page).save(path) + return t_info(path) + + +def t_add_picture(path, image_path): + h = _load(path) + with open(image_path, "rb") as f: + pid = project.add_picture(h, f.read()) + h.save(path) + return {"picture_id": pid} + + +def t_add_font(path, height, ttf_path=None, encoding="ascii"): + from . import fonts + h = _load(path) + f = fonts.from_ttf(ttf_path, int(height), encoding) + fid = project.add_font(h, f) + h.save(path) + return {"font_id": fid, "name": f.name, "height": f.height} + + +def t_verify(path): + from . import checksum + import struct + h = _load(path) + problems = [] + t0, t1 = h.table_ok() + if not (t0 and t1): + problems.append("file table checksum (primary %s, backup %s)" % (t0, t1)) + for e in h.live(): + blob = h.read(e.name) + stored = struct.unpack_from(" bytes: return bytes(b) -def add_page(h: HMIFile, name: str, **attrs) -> Page: +def add_page(hmi: HMIFile, name: str, **attrs) -> Page: """Add a new empty page to an opened project (next free N.pa) and register it in main.HMI.""" from .components import new_page - used = {Page.parse(h.read(e.name)).name for e in h.live() if e.name.endswith(".pa")} + used = {Page.parse(hmi.read(e.name)).name for e in hmi.live() if e.name.endswith(".pa")} if name in used: raise ValueError("page %r exists" % name) n = 0 - while h.find("%d.pa" % n): + while hmi.find("%d.pa" % n): n += 1 p = new_page(name, **attrs) - h.write("%d.pa" % n, p.pack()) - h.write("main.HMI", main_add_resource(h.read("main.HMI"), "pa", "%d.pa" % n)) + hmi.write("%d.pa" % n, p.pack()) + hmi.write("main.HMI", main_add_resource(hmi.read("main.HMI"), "pa", "%d.pa" % n)) return p diff --git a/tests/test_mcp.py b/tests/test_mcp.py new file mode 100644 index 0000000..961fd25 --- /dev/null +++ b/tests/test_mcp.py @@ -0,0 +1,105 @@ +"""MCP server: protocol round trip over stdio and every tool.""" +import json +import os +import shutil +import subprocess +import sys +import tempfile +import unittest + +from helpers import FIXTURE, HAVE_PIL, ROOT + +from nxhmi import mcp_server as M + + +class Protocol(unittest.TestCase): + def test_stdio_session(self): + env = dict(os.environ, PYTHONPATH=os.path.join(ROOT, "src")) + msgs = [{"jsonrpc": "2.0", "id": 1, "method": "initialize", "params": {"protocolVersion": "2025-06-18"}}, + {"jsonrpc": "2.0", "method": "notifications/initialized"}, + {"jsonrpc": "2.0", "id": 2, "method": "tools/list"}, + {"jsonrpc": "2.0", "id": 3, "method": "tools/call", "params": {"name": "list_kinds", "arguments": {}}}, + {"jsonrpc": "2.0", "id": 4, "method": "nope"}] + p = subprocess.run([sys.executable, "-m", "nxhmi.mcp_server"], input="\n".join(json.dumps(m) for m in msgs) + "\n", + capture_output=True, text=True, env=env, timeout=60) + replies = [json.loads(l) for l in p.stdout.splitlines()] + self.assertEqual([r["id"] for r in replies], [1, 2, 3, 4]) + self.assertEqual(replies[0]["result"]["serverInfo"]["name"], "openhmi-nx") + self.assertIn("render_page", [t["name"] for t in replies[1]["result"]["tools"]]) + self.assertIn("button", json.loads(replies[2]["result"]["content"][0]["text"])["kinds"]) + self.assertEqual(replies[3]["error"]["code"], -32601) + + +class Tools(unittest.TestCase): + def setUp(self): + self.tmp = tempfile.mkdtemp() + self.hmi = os.path.join(self.tmp, "p.HMI") + shutil.copy(FIXTURE, self.hmi) + + def tearDown(self): + shutil.rmtree(self.tmp) + + def call(self, tool, **args): + r = M.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call", "params": {"name": tool, "arguments": args}}) + res = r["result"] + if res.get("isError"): + raise AssertionError(res["content"][0]["text"]) + return res["content"] + + def j(self, tool, **args): + return json.loads(self.call(tool, **args)[0]["text"]) + + def test_info_and_page(self): + info = self.j("info", path=self.hmi) + self.assertEqual([p["page"] for p in info["pages"]], ["home", "controls", "gallery"]) + page = self.j("get_page", path=self.hmi, page="home") + title = next(c for c in page["components"] if c["name"] == "title") + self.assertEqual(title["kind"], "text") + self.assertEqual(title["attributes"]["xcen"], "left") + + def test_edit_cycle(self): + r = self.j("set_attributes", path=self.hmi, page="home", component="title", + attributes={"txt": "edited", "xcen": "center", "pco": "#ff0000", "x": 20}) + self.assertEqual((r["attributes"]["txt"], r["attributes"]["xcen"], r["attributes"]["pco"]), ("edited", "center", "#ff0000")) + self.assertEqual(r["attributes"]["endx"], 20 + r["attributes"]["w"] - 1) + self.j("set_event", path=self.hmi, page="home", component="title", event="codesup", lines=["page 1"]) + c = self.j("add_component", path=self.hmi, page="home", kind="button", name="bNew", + attributes={"x": 1, "y": 2, "w": 40, "h": 20, "txt": "go", "style": "3D_Auto"}, + events={"codesup": ["page 0"]}) + self.assertEqual(c["events"], {"codesup": ["page 0"]}) + self.j("remove_component", path=self.hmi, page="home", component="bNew") + self.j("add_page", path=self.hmi, name="extra", attributes={"bco": "#000000"}) + self.assertTrue(self.j("verify", path=self.hmi)["ok"]) + + def test_errors_are_tool_results(self): + r = M.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call", + "params": {"name": "get_page", "arguments": {"path": self.hmi, "page": "missing"}}}) + self.assertTrue(r["result"]["isError"]) + self.assertIn("pages: home", r["result"]["content"][0]["text"]) + + def test_schema(self): + s = self.j("schema", kind="text") + xcen = next(a for a in s["attributes"] if a["name"] == "xcen") + self.assertEqual(xcen["values"], ["left", "center", "right"]) + + def test_new_project_refuses_overwrite(self): + p = os.path.join(self.tmp, "new.HMI") + self.assertEqual(self.j("new_project", path=p)["pages"][0]["page"], "page0") + with self.assertRaises(AssertionError): + self.j("new_project", path=p) + + @unittest.skipUnless(HAVE_PIL, "needs Pillow") + def test_render_and_media(self): + content = self.call("render_page", path=self.hmi, page="home") + self.assertEqual(content[0]["type"], "image") + self.assertEqual(content[0]["mimeType"], "image/png") + from PIL import Image + png = os.path.join(self.tmp, "i.png") + Image.new("RGB", (4, 4), (9, 9, 9)).save(png) + self.assertEqual(self.j("add_picture", path=self.hmi, image_path=png)["picture_id"], 6) + self.assertEqual(self.j("add_font", path=self.hmi, height=12)["font_id"], 2) + self.assertTrue(self.j("verify", path=self.hmi)["ok"]) + + +if __name__ == "__main__": + unittest.main() diff --git a/tests/test_tft_cli.py b/tests/test_tft_cli.py index 57c08f3..15455b9 100644 --- a/tests/test_tft_cli.py +++ b/tests/test_tft_cli.py @@ -60,6 +60,13 @@ class Cli(unittest.TestCase): self.assertEqual(self.run_cli("verify", self.hmi)[0], 0) self.assertIn('"title"', self.run_cli("dump", self.hmi, "--page", "home")[1]) + def test_json_info_and_schema(self): + import json + info = json.loads(self.run_cli("info", self.hmi, "--json")[1]) + self.assertEqual(info["size"], [480, 320]) + sch = json.loads(self.run_cli("schema", "slider")[1]) + self.assertIn("vertical", next(x for x in sch["attributes"] if x["name"] == "mode")["values"]) + def test_decode_encode(self): d = os.path.join(self.tmp, "dec") self.run_cli("decode", self.hmi, d)