tft: text (plain) and touch cap; 55 Editor samples reproduced byte for byte

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Fable 5.2 committed 2026-11-16 18:29:12 +01:00
1 parent 0532a59120
commit b5eaa68298
7 files changed
+101 -15

No files matched your search

+2 -1
View File
@@ -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.
+1 -1
View File
@@ -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
+1 -1
View File
@@ -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 |
+13 -6
View File
@@ -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,<font>,<pco>,<bco>,<xcen>,<ycen>,1,<txt>,0,0,<isbr>,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,<font>,<pco>,<bco>,<xcen>,<ycen>,1,<isbr>,0,0,<pw>,0`
then `09 13 04` with four `03 7FFF` numbers and `<txt>`; 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 <val>,<lenth>,<format>`. Button (default 3D style) has a
long generated script with conditional jumps on `val`.
- Progress bar draw section: `<sys 0005/04>=<val>*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.
+1 -1
View File
@@ -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"]),
+52 -5
View File
@@ -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("<BB", pi, cid) if t["owner"] else b"\xff\xff"
slot0 = len(prec) // tft.REC_SIZE
@@ -176,7 +202,16 @@ def compile_pages(pages: list[Page], program: str):
recs[slot] = struct.pack("<Iiii2sBBBBH", group, _s(a[name], lo < 0), hi, lo, owner, 0, 0, kind, size, 0)
amap[MAP[name]] = slot0 + slot
for name, (slot, kind, size, hi, lo) in t["ram"].items():
if kind == 0x3F: # string: txt_maxl + 1 bytes, not aligned
size = _u(a["txt_maxl"]) + 1
if size > 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("<Iiii2sBBBBH", group, g + 4 + len(ram), hi, lo, owner, 0,
t.get("action", {}).get(name, 0), kind, size, 0)
amap[MAP[name]] = slot0 + slot
@@ -197,14 +232,25 @@ def compile_pages(pages: list[Page], program: str):
section([])
section([])
else:
if "draw" in t:
draw = len(blob)
table_ = {**t["const"], **t["ram"]}
for raw in t["draw"](rect, lambda name: b"\x01" + struct.pack(
"<I", rec_base + slot0 + table_[name][0])):
blob += _chunk(raw)
section([])
if t["flag"] & 0x10:
erase = len(blob)
blob += _chunk(fill)
section([])
code_at = [0xFFFFFFFF] * 4 # down, up, timer, unload (object +0x0C..)
touch = t["flag"] & 0x10 or t.get("events")
if "init" in t:
if t["init"] in init:
raise Unsupported("two %s components on one page" % t["name"])
init.append(t["init"])
for i, (label, group_name, wanted) in enumerate((
(b"down", "codesdown", t["flag"] & 0x10), (b"up", "codesup", t["flag"] & 0x10),
(b"down", "codesdown", touch), (b"up", "codesup", touch),
(None, None, False), (b"unload", "codesunload", tid == 121))):
if wanted:
if ev.get(group_name):
@@ -257,7 +303,8 @@ def build_tft(hmi: HMIFile, editor_dir: str = DEFAULT_EDITOR_DIR) -> 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
+31
View File
@@ -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")