tft: page section format, pictures/fonts, first builder (nxhmi build-tft)

Byte-identical to Nextion Editor 1.68.2 for NX4832T035 projects made of pages,
hotspots and int variables with any pictures and fonts. Firmware files are read
from the user's Editor folder at build time. FORMAT.md section 7 documents the
header, resource area, code blob, attribute records, page table and objects.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Fable 5.2 committed 2026-11-16 18:13:11 +01:00
1 parent 7337e693a5
commit f66c902443
10 files changed
+589 -5

No files matched your search

+223
View File
@@ -0,0 +1,223 @@
"""Build a .tft from a .HMI project -- research stage. See docs/FORMAT.md section 7.
What is reproduced byte for byte (Nextion Editor 1.68.2, model NX4832T035): header, resource
area (the firmware files are read from the user's own Editor installation; pictures, fonts), page
section for the component types in ``TYPES`` and the script subset in :mod:`nxhmi.tft_code`,
layout table and all checksums. Anything else raises :class:`Unsupported` -- never a guess.
"""
from __future__ import annotations
import os
import re
import struct
from . import tft, tft_code
from .container import HMIFile
from .page import Page
from .tft_code import Unsupported
FIRMWARE_FILES = ("input.bin", "asp0.dll", "cd0.dll", "qr0.bin", "syscom.bin", "h0-0.dll", "h1-0.dll")
DEFAULT_EDITOR_DIR = r"C:\Program Files (x86)\Nextion Editor"
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, "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)}
# 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 = {
121: dict(name="page", slots=33, flag=0x37, group=8, const={**_COMMON, **_RECT},
ram={"sta": (23, 0x21, 1, 2, 0), "bco": (24, 0x32, 2, 65535, 0)}, owner=True),
109: dict(name="hotspot", slots=27, flag=0x37, group=16, const={**_COMMON, **_RECT}, ram={}, owner=True),
52: dict(name="variable", slots=11, flag=0x07, group=16,
const={**_COMMON, "sta": (7, 0x01, 1, 1, 0)},
ram={"val": (8, 0x39, 4, 2147483647, -2147483648)}, owner=False),
}
def _chunk(b: bytes) -> bytes:
return struct.pack("<I", len(b)) + b
def _u(attr) -> int:
return int.from_bytes(attr.value, "little")
def _s(attr, signed) -> int:
v, bits = _u(attr), 8 * len(attr.value)
return v - (1 << bits) if signed and v >> (bits - 1) else v
def resource_area(hmi: HMIFile, editor_dir: str) -> tuple[bytes, dict]:
"""Directory + firmware files + pictures + fonts, zero-padded to a 64 KB multiple."""
def numbered(ext):
names = [n for n in hmi.names() if re.fullmatch(r"\d+\." + ext, n)]
return [hmi.read(n) for n in sorted(names, key=lambda s: int(s.split(".")[0]))]
def packed(blobs, head, off_pos, idx_pos=None):
heads, datas, o = [], [], head * len(blobs)
for i, b in enumerate(blobs):
h = bytearray(b[:head])
struct.pack_into("<I", h, off_pos, o)
if idx_pos is not None:
struct.pack_into("<I", h, idx_pos, i)
heads.append(bytes(h))
datas.append(b[head:])
o += len(b) - head
return b"".join(heads) + b"".join(datas)
parts = []
for n in FIRMWARE_FILES:
p = os.path.join(editor_dir, n)
if not os.path.exists(p):
raise FileNotFoundError("Nextion Editor file not found: %s (pass the Editor install folder)" % p)
with open(p, "rb") as fh:
parts.append(fh.read())
pics, fonts = numbered("i"), numbered("zi")
parts += [packed(pics, 24, 8, 4), packed(fonts, 44, 0x18)]
directory, o = bytearray(0x90), 0x90
for i, p in enumerate(parts):
struct.pack_into("<III", directory, 12 * i, o, len(p), 0)
o += len(p)
area = bytes(directory) + b"".join(parts)
area += bytes(-len(area) % BLOCK)
sizes = [len(p) for p in parts]
info = {"cd0": (0x90 + sum(sizes[:2]), sizes[2]), "asp0": (0x90 + sizes[0], sizes[1]),
"pictures": 0x90 + sum(sizes[:7]), "fonts": 0x90 + sum(sizes[:8]), "npics": len(pics), "nfonts": len(fonts)}
return area, info
def compile_pages(pages: list[Page], program: str):
"""-> (code blob, 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))
n = len(pages)
blob = bytearray(struct.pack("<10I", 0x24 + 6 * n, 3, 0x1C, 4, 0x20, 4, 0x24, 6 * n, 0, 0))
for h, i in names:
blob += struct.pack("<IH", h, i)
program_off = len(blob)
ctx = tft_code.Context()
def section(lines, label=None):
if label:
blob.extend(_chunk(label))
for ln in lines:
blob.extend(_chunk(tft_code.compile_line(ln, ctx)))
blob.extend(_chunk(b""))
section(tft_code.statements(program.splitlines()) + ["page 0"])
records, objects, table, rec_base = bytearray(), bytearray(), [], 0
for pi, page in enumerate(pages):
ram = bytearray(b"\xff" * 8)
prec, first_obj, comp_names, init = bytearray(), len(objects) // tft.OBJ_SIZE, [], []
page_bco = 0
for ci, c in enumerate(page.components):
a = {x.name: x for x in c.attrs()}
tid = _u(a["type"])
if tid not in TYPES or (ci == 0) != (tid == 121):
raise Unsupported("component type %d (%s) on page %d" % (tid, c.get("objname"), pi))
t = TYPES[tid]
if tid == 121 and _u(a["sta"]) != 1:
raise Unsupported("page background other than a solid colour")
if tid == 52 and _u(a["sta"]) != 0:
raise Unsupported("string variables")
if _u(a["vscope"]) != 0:
raise Unsupported("global components")
cid = _u(a["id"])
owner = struct.pack("<BB", pi, cid) if t["owner"] else b"\xff\xff"
slot0 = len(prec) // tft.REC_SIZE
recs = [bytes(tft.REC_SIZE)] * t["slots"]
amap = [0xFFFF] * 88
for name, (slot, kind, size, hi, lo) in t["const"].items():
recs[slot] = struct.pack("<Iiii2sHBBH", t["group"], _s(a[name], lo < 0), hi, lo, owner, 0, kind, size, 0)
amap[MAP[name]] = slot0 + slot
for name, (slot, kind, size, hi, lo) in t["ram"].items():
ram += bytes(-len(ram) % min(size, 4))
recs[slot] = struct.pack("<Iiii2sHBBH", t["group"], len(ram) + 4, hi, lo, owner, 0, kind, size, 0)
amap[MAP[name]] = slot0 + slot
if name == "bco" and tid == 121:
page_bco = rec_base + slot0 + slot
ram += a[name].value[:size].ljust(size, b"\0")
ram += bytes(-len(ram) % 4)
prec += b"".join(recs)
# code block: draw section, erase section (visible types), event sections
start = len(blob)
ev = {g.name: tft_code.statements(tft_code.group_lines(g)) for g in c.groups if g.name != "att"}
rect = [_u(a[k]) if k in a else v for k, v in (("x", 0), ("y", 0), ("w", 1), ("h", 1), ("endx", 0), ("endy", 0))]
fill = b"\x09\x0d\x04" + ("%d,%d,%d,%d," % tuple(rect[:4])).encode() + b"\x01" + struct.pack("<I", page_bco)
draw = erase = 0xFFFFFFFF
if tid == 121:
draw = len(blob)
blob += _chunk(fill)
section(ev.get("codesload", []))
section([])
else:
section([])
if t["flag"] & 0x10:
erase = len(blob)
blob += _chunk(fill)
section([])
if t["flag"] & 0x10:
section(ev.get("codesdown", []), b"down")
section(ev.get("codesup", []), b"up")
if tid == 121:
section(ev.get("codesunload", []), b"unload")
init = ev.get("codesloadend", [])
obj = bytearray(b"\xff" * tft.OBJ_SIZE)
struct.pack_into("<BBBBII", obj, 0, tid, cid, 0, t["flag"], draw, erase)
struct.pack_into("<IHBBI6HI", obj, 0x1C, t["group"], 0, 0x7F, 0, 0, *rect, start)
struct.pack_into("<88H", obj, 0x38, *amap)
objects += obj
comp_names.append((tft.name_hash(c.get("objname")), cid))
names_off = len(blob)
blob += _chunk(b"".join(struct.pack("<IH", h, i) for h, i in sorted(comp_names)))
blob += _chunk(bytes(ram) + bytes(8))
blob += _chunk(b"\x09\x21\x08")
section(init)
table.append((first_obj, len(page.components), names_off, rec_base, len(ram)))
records += prec
rec_base += len(prec) // tft.REC_SIZE
code_size = len(blob)
ptable = b"".join(struct.pack("<HHIII", f, cnt, no, code_size + rb * tft.REC_SIZE, rs) for f, cnt, no, rb, rs in table)
return bytes(blob), bytes(records), ptable, bytes(objects), program_off
def build_tft(hmi: HMIFile, editor_dir: str = DEFAULT_EDITOR_DIR) -> bytes:
main = hmi.read("main.HMI")
model, = struct.unpack_from("<I", main, 16)
if model != SUPPORTED_MODEL:
raise Unsupported("model 0x%08X (only NX4832T035 has been measured)" % model)
from .project import parse_main, project_size
pm = parse_main(main)
if pm["direction"] != 90:
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, records, ptable, objects, program_off = compile_pages(pages, hmi.read("Program.s").decode("latin-1"))
area, info = resource_area(hmi, editor_dir)
base = tft.RES_START + len(area)
body = blob + records + ptable + objects
body += b"\xff" * (-len(body) % 4)
head = bytearray(b"\xff" * tft.RES_START)
head[:0x70] = bytes(0x70)
head[0:12] = bytes.fromhex("0001444e784501004cd30000")
struct.pack_into("<4H", head, 0x0C, w, h, h, w)
head[0x14:0x18] = bytes.fromhex("01000002")
cd0 = tft.RES_START + info["cd0"][0]
struct.pack_into("<IHIIIII", head, 0x18, cd0, 0, cd0, info["cd0"][1], tft.RES_START + info["asp0"][0],
info["asp0"][1], model)
head[0x32:0x3C] = bytes.fromhex("2100000001000c000000")
struct.pack_into("<II", head, 0x3C, base + len(body) + 4, len(area))
head[0x4C:0x54] = b"\xff" * 8
struct.pack_into("<I", head, 0x58, len(blob) + len(records))
pt = base + len(blob) + len(records)
layout = [len(blob), len(blob), 0, len(blob), tft.RES_START, base, pt, pt + len(ptable),
tft.RES_START + info["pictures"], 0, 0, 0, tft.RES_START + info["fonts"], program_off,
len(pages) | (len(objects) // tft.OBJ_SIZE) << 16, info["npics"], 0, info["nfonts"], 3]
for i, v in enumerate(layout):
struct.pack_into("<I", head, tft.LAYOUT_START + 4 * i, v ^ tft.LAYOUT_KEY)
return tft.seal(bytes(head) + area + body + bytes(4))