From b5eaa68298193b72b103b40dc26468e440d66b7b Mon Sep 17 00:00:00 2001 From: MangaValk Date: Mon, 16 Nov 2026 18:29:12 +0100 Subject: [PATCH] tft: text (plain) and touch cap; 55 Editor samples reproduced byte for byte Co-Authored-By: Claude Fable 5.2 --- .claude/skills/nextion-hmi/SKILL.md | 3 +- README.md | 2 +- docs/COVERAGE.md | 2 +- docs/NOTES.md | 19 +++++++--- src/nxhmi/mcp_server.py | 2 +- src/nxhmi/tft_build.py | 59 ++++++++++++++++++++++++++--- tests/test_tft_build.py | 31 +++++++++++++++ 7 files changed, 102 insertions(+), 16 deletions(-) diff --git a/.claude/skills/nextion-hmi/SKILL.md b/.claude/skills/nextion-hmi/SKILL.md index c61741a..5cd3364 100644 --- a/.claude/skills/nextion-hmi/SKILL.md +++ b/.claude/skills/nextion-hmi/SKILL.md @@ -38,7 +38,8 @@ Back up the user's file first (copy it) unless they said not to; edits write in project with the same encoding to see the text readably. Pictures: `quality` 1-99 stores JPEG (Intelligent only, smaller files). - `build_tft` compiles to `.tft` without the Editor's compiler, but only for model NX4832T035 and a - small subset (pages, hotspots, int variables, timers, pictures, fonts, plain script); it says + small subset (pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts, + plain script); it says what it cannot compile. It needs the Editor's install folder for the firmware files. Its output is byte-identical to the Editor's for the test projects but has never been loaded onto a display -- tell the user, and never upload it yourself. diff --git a/README.md b/README.md index 514cef1..c11fb76 100644 --- a/README.md +++ b/README.md @@ -32,7 +32,7 @@ Every percentage is a count with a stated basis, so it can be checked (details i | Readable attribute names in JSON | **100 %** (31/31 types) | every value list the Editor documents, incl. the Intelligent-only types and load effects | | Rendering, Basic components | **100 %** (20/20 pixel-exact) | incl. gauges and QR codes (own encoder, no dependencies) | | Rendering, all components | **94 %** (29/31 pixel-exact) | Intelligent ComboBox and Switch are drawn, but their anti-aliased edges are approximate (~99 % / ~92 % of pixels exact) | -| `.tft` compilation | **81 %** (6.5/8 milestones) | `nxhmi build-tft`: byte-identical to the Editor for NX4832T035 projects with pages, hotspots, int variables, timers, pictures, fonts and script (assignments, arithmetic, 27 commands, if/else/while/for, global variables); drawing component types not yet; never tried on a display | +| `.tft` compilation | **81 %** (6.5/8 milestones) | `nxhmi build-tft`: byte-identical to the Editor for NX4832T035 projects with pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts and script (assignments, arithmetic, 27 commands, if/else/while/for, global variables); the other component types not yet; never tried on a display | ## Compatibility diff --git a/docs/COVERAGE.md b/docs/COVERAGE.md index 99d93a9..a3f4f67 100644 --- a/docs/COVERAGE.md +++ b/docs/COVERAGE.md @@ -113,7 +113,7 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th | Trailer checksum | solved for any length (`tft.trailer`); one model measured | | 3 header checksums (0x44, 0xC4, 0x18C) | solved (`tft.header_checksums`, `tft.seal`) | | Pictures and fonts inside the TFT | solved (FORMAT.md 7.2) | -| Compiled page format | structure solved (code blob, name hashes, RAM image, attribute records, page table, object records -- FORMAT.md 7.3-7.5); per-type tables done for page, hotspot, int variable, timer; the other types need their slot tables and generated draw scripts | +| Compiled page format | structure solved (code blob, name hashes, RAM image, attribute records, page table, object records -- FORMAT.md 7.3-7.5); per-type tables done for page, hotspot, text (solid background, flat style), int variable, timer, touch cap; the other types need their slot tables and generated draw scripts | | Event-code tokens | solved for what was sampled (FORMAT.md 7.6): 27 commands, 33 system variables/colours, numbers, global variables, attribute references, if/else/while/for. Not sampled: string functions and attributes, the remaining commands and system variables, `>=` op code | | Builder (`nxhmi build-tft`) | byte-identical to the Editor for the supported subset (one model: NX4832T035); refuses anything else. **Never tested on a real display** | | Licensing | every `.tft` embeds Nextion's firmware files; the repo must never ship them -- a builder would read them from the user's own Editor installation | diff --git a/docs/NOTES.md b/docs/NOTES.md index 47e812f..a671cf8 100644 --- a/docs/NOTES.md +++ b/docs/NOTES.md @@ -164,9 +164,11 @@ Script (same day): tokens, global variables, timers and control flow are in (FOR before a long number), mixed `&&`/`||`, parentheses in conditions, braces-less `if`. - The Editor appends one `page 0` chunk to the program even when Program.s already ends with it. -Not done: sliders, touch cap and every drawing component (text, number, button, progress bar, -gauge, waveform, picture, crop, checkbox, radio, QR code ...); string variables and string -functions; page backgrounds other than a solid colour; global (vscope) components; other +Added later the same day: touch cap and plain text (55 samples reproduced). + +Not done: sliders and the other drawing components (number, button, progress bar, gauge, +waveform, picture, crop, checkbox, radio, QR code ...); text with a border, picture or crop +background; string attributes in script (`t0.txt="x"`), string variables and string functions; page backgrounds other than a solid colour; global (vscope) components; other models, portrait, other series; and nothing has been loaded onto a display. Samples: `tools/make_tft_samples.py` writes the 63 study projects (`tools/tft_samples.json`); @@ -179,9 +181,14 @@ Starting points for the next component types (from those samples, not yet in the order (text: font, isbr, pco, bco, xcen, ycen, pw, then txt with `txt_maxl + 1` bytes). Kinds seen: 0x21/0x31 u8, 0x22/0x32 u16, 0x39 i32, 0x3F string (size = bytes reserved), 0x02 `txt_maxl`. -- Text draw section: `09 1C 08 x,y,w,h,,,,,,1,,0,0,,0` - then `09 13 04` with four `03 7FFF` numbers and a record reference; every `<..>` is a - record reference, so changing an attribute at run time needs no recompilation. +- Text draw section (implemented): `09 1C 08 x,y,w,h,,,,,,1,,0,0,,0` + then `09 13 04` with four `03 7FFF` numbers and ``; every `<..>` is a record reference, + so changing an attribute at run time needs no recompilation. The literal 1 and 0s are + probably sta, spax, spay and the border -- untested, so other values are refused. The `font` + record's maximum is the number of fonts - 1. +- Number looks like text but keeps `sta` and `style` in RAM (plus three unexplained bytes) and + draws with `09 1C 08` + `09 11 04 ,,`. Button (default 3D style) has a + long generated script with conditional jumps on `val`. - Progress bar draw section: `=*w/100`, then two fills (`09 0D 04`) for the filled and the empty part. Gauge: one `09 0A 08` line. QR code: one `09 08 08` line. - Slider and touch cap add the init line `09 16 04 1`; slider has a `slide` event label. diff --git a/src/nxhmi/mcp_server.py b/src/nxhmi/mcp_server.py index 9436975..d27ae25 100644 --- a/src/nxhmi/mcp_server.py +++ b/src/nxhmi/mcp_server.py @@ -260,7 +260,7 @@ TOOLS = { "should match).", {"path": S, "height": {"type": "integer"}, "ttf_path": S, "encoding": S, "chars": S}, ["path", "height"]), "build_tft": (t_build_tft, "Compile the project to a .tft firmware file. Research stage: model NX4832T035 only; " - "pages, hotspots, int variables, timers, pictures, fonts and plain script; anything else is " + "pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts and plain script; anything else is " "refused with the reason. Needs a Nextion Editor installation (editor_dir) for the firmware " "files. The output has never been tried on a real display.", {"path": S, "tft_path": S, "editor_dir": S}, ["path", "tft_path"]), diff --git a/src/nxhmi/tft_build.py b/src/nxhmi/tft_build.py index c7e7ee8..6afac31 100644 --- a/src/nxhmi/tft_build.py +++ b/src/nxhmi/tft_build.py @@ -23,12 +23,22 @@ SUPPORTED_MODEL = 0xB23BC018 # NX4832T035_011, the only model measured BLOCK = 0x10000 # attribute map positions in the object record (u16 table at +0x38) -MAP = {"vscope": 1, "sta": 2, "bco": 4, "val": 20, "tim": 33, "en": 34, "x": 42, "y": 43, "endx": 44, "endy": 45, "w": 46, "h": 47, +MAP = {"vscope": 1, "sta": 2, "bco": 4, "pco": 16, "val": 20, "font": 25, "xcen": 26, "ycen": 27, "txt": 28, + "txt_maxl": 29, "tim": 33, "en": 34, "isbr": 54, "spax": 56, "spay": 57, "pw": 58, "style": 59, "x": 42, "y": 43, "endx": 44, "endy": 45, "w": 46, "h": 47, "id": 49, "type": 62} # attribute record templates: name -> (slot, kind, size, max, min) _COMMON = {"type": (0, 0x01, 1, 255, 0), "id": (1, 0x01, 1, 255, 0), "vscope": (3, 0x01, 1, 1, 0)} _RECT = {"x": (9, 0x0B, 2, 6000, -6000), "y": (10, 0x0C, 2, 6000, -6000), "w": (11, 0x0D, 2, 2000, -2000), "h": (12, 0x0E, 2, 2000, -2000), "endx": (13, 0x08, 2, 32767, -32768), "endy": (14, 0x08, 2, 32767, -32768)} + + +def _text_draw(rect, ref): + """Draw section of a text component (solid background, no border).""" + line = (b"\x09\x1c\x08" + ("%d,%d,%d,%d," % tuple(rect[:4])).encode() + ref("font") + b"," + ref("pco") + b"," + + ref("bco") + b"," + ref("xcen") + b"," + ref("ycen") + b",1," + ref("isbr") + b",0,0," + ref("pw") + b",0") + return [line, b"\x09\x13\x04" + b"\x03\xff\x7f\x00\x00," * 4 + ref("txt")] + + # type id -> description. ``ram`` attributes live in the page's RAM image (in this order); # ``owner``: whether records name the component to refresh when the attribute changes. TYPES = { @@ -40,6 +50,17 @@ TYPES = { ram={"val": (8, 0x39, 4, 2147483647, -2147483648)}, owner=False), 51: dict(name="timer", slots=11, flag=0x27, group=16, const=dict(_COMMON), ram={"tim": (7, 0x32, 2, 65534, 50), "en": (8, 0x31, 1, 1, 0)}, owner=True, action={"tim": 1, "en": 2}), + # text: only the plain form (sta = solid colour, style = flat, no extra spacing) was measured + 116: dict(name="text", slots=41, flag=0x37, group=16, + const={**_COMMON, **_RECT, "sta": (19, 0x01, 1, 2, 0), "style": (20, 0x01, 1, 3, 0), + "txt_maxl": (29, 0x02, 2, 65534, 0), "spax": (31, 0x01, 1, 255, 0), "spay": (32, 0x01, 1, 255, 0)}, + ram={"font": (22, 0x31, 1, "fonts", 0), "isbr": (30, 0x31, 1, 1, 0), "pco": (24, 0x32, 2, 65535, 0), + "bco": (23, 0x32, 2, 65535, 0), "xcen": (25, 0x31, 1, 2, 0), "ycen": (26, 0x31, 1, 2, 0), + "pw": (27, 0x31, 1, 1, 0), "txt": (28, 0x3F, 0, 0, 0)}, + owner=True, need={"sta": 1, "style": 0, "spax": 0, "spay": 0}, draw=_text_draw), + # touch cap: down/up events without a rectangle; one init line (only one per page was measured) + 5: dict(name="touch_cap", slots=10, flag=0x27, group=16, const=dict(_COMMON), + ram={"val": (7, 0x21, 1, 65535, 0)}, owner=True, events=True, init=b"\x09\x16\x041"), } @@ -95,7 +116,7 @@ def resource_area(hmi: HMIFile, editor_dir: str) -> tuple[bytes, dict]: return area, info -def compile_pages(pages: list[Page], program: str): +def compile_pages(pages: list[Page], program: str, nfonts: int = 0): """-> (code blob, global variable descriptors, attribute records, page table, object records, program offset).""" names = sorted((tft.name_hash(p.components[0].get("objname")), i) for i, p in enumerate(pages)) @@ -135,7 +156,9 @@ def compile_pages(pages: list[Page], program: str): return None first, t = where[key] slot = {**t["const"], **t["ram"]}.get(name) - return None if slot is None else first + slot[0] + if slot is None or slot[1] == 0x3F: # string attributes in script: not measured + return None + return first + slot[0] ctx = tft_code.Context(offsets, {k[1] for k in where}, attr) @@ -166,6 +189,9 @@ def compile_pages(pages: list[Page], program: str): raise Unsupported("string variables") if _u(a["vscope"]) != 0: raise Unsupported("global components") + for name, value in t.get("need", {}).items(): + if _u(a[name]) != value: + raise Unsupported("%s with %s=%d" % (t["name"], name, _u(a[name]))) cid = _u(a["id"]) owner = struct.pack(" 255 or len(a[name].value) >= size: + raise Unsupported("text longer than txt_maxl, or txt_maxl > 254") + else: + ram += bytes(-len(ram) % min(size, 4)) + if hi == "fonts": + hi = nfonts - 1 + if _u(a[name]) > hi: + raise Unsupported("font %d does not exist" % _u(a[name])) recs[slot] = struct.pack(" bytes: raise Unsupported("display direction %d" % pm["direction"]) w, h = project_size(hmi) pages = [Page.parse(hmi.read(name)) for rtype, name in pm["resources"] if rtype == "pa"] - blob, descriptors, records, ptable, objects, program_off = compile_pages(pages, hmi.read("Program.s").decode("latin-1")) + blob, descriptors, records, ptable, objects, program_off = compile_pages( + pages, hmi.read("Program.s").decode("latin-1"), sum(1 for x in hmi.names() if re.fullmatch(r"\d+\.zi", x))) area, info = resource_area(hmi, editor_dir) base = tft.RES_START + len(area) body = blob + descriptors + records + ptable + objects diff --git a/tests/test_tft_build.py b/tests/test_tft_build.py index 0000d21..30e0c74 100644 --- a/tests/test_tft_build.py +++ b/tests/test_tft_build.py @@ -62,6 +62,30 @@ class Build(unittest.TestCase): self.assertEqual(obj[:2], bytes([109, 1])) self.assertEqual(struct.unpack_from("<6H", obj, 0x28), (10, 20, 30, 40, 39, 59)) + def test_text_timer_touch_cap_and_script(self): + from nxhmi import fonts + h = project.new_project("NX4832T035_011", program="int n=0\r\nbaud=115200\r\npage 0\r\n") + project.add_font(h, fonts.from_ttf(None, 16)) if HAVE_PIL else None + p = Page.parse(h.read("0.pa")) + if HAVE_PIL: + C.add(p, "text", x=5, y=5, w=100, h=30, txt="hi") + C.add(p, "timer") + C.add(p, "touch_cap") + tm = [c for c in p.components if c.get("objname") == "tm0"][0] + tm.set_event("codestimer", ["if(n<1000)", "{", " n++", "}else", "{", " tm0.en=0", "}"]) + h.write("0.pa", p.pack()) + out = tft_build.build_tft(h, self.tmp) + self.assertTrue(tft.verify_header(out) and tft.verify_trailer(out)) + lay = tft.layout_table(out) + self.assertEqual(lay[2], 1) # one global variable + self.assertEqual(lay[3], lay[0] + 12) # its 12-byte descriptor + blob = out[lay[5]:lay[5] + lay[0]] + self.assertIn(b"\x05\x00\x00\x00\x00++", blob) # n++ + self.assertIn(b"timer", blob) + self.assertIn(b"\x09\x16\x041", blob) # touch cap init line + if HAVE_PIL: + self.assertIn(b"\x09\x1c\x085,5,100,30,", blob) # text draw line + def test_name_hash(self): self.assertEqual(tft.name_hash("page0"), 0xAC967926) # measured in Editor output @@ -72,6 +96,13 @@ class Build(unittest.TestCase): h.write("0.pa", p.pack()) with self.assertRaises(tft_build.Unsupported): tft_build.build_tft(h, self.tmp) + # a text component without any font in the project (the Editor refuses to compile that too) + h = self.project() + p = Page.parse(h.read("0.pa")) + C.add(p, "text", x=1, y=1, w=50, h=20) + h.write("0.pa", p.pack()) + with self.assertRaises(tft_build.Unsupported): + tft_build.build_tft(h, self.tmp) def test_cli(self): hmi, out = os.path.join(self.tmp, "p.HMI"), os.path.join(self.tmp, "p.tft")