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

+32
View File
@@ -169,6 +169,32 @@ def cmd_dump(a):
print(json.dumps(project.page_to_json(e.name, p, a.encoding, not a.raw), indent=1, ensure_ascii=False))
def cmd_build_tft(a):
from . import tft_build
try:
out = tft_build.build_tft(HMIFile.load(a.hmi), a.editor_dir)
except tft_build.Unsupported as e:
print("error: cannot compile yet:", e, file=sys.stderr)
return 3
except FileNotFoundError as e:
print("error:", e, file=sys.stderr)
return 2
with open(a.tft, "wb") as fh:
fh.write(out)
print("wrote %s (%d bytes)" % (a.tft, len(out)))
def cmd_tft_info(a):
from . import tft
with open(a.tft, "rb") as fh:
data = fh.read()
info = tft.header_info(data)
info["header_checksums_ok"] = tft.verify_header(data)
info["trailer_ok"] = tft.verify_trailer(data)
print(json.dumps(info, indent=1))
return 0 if info["header_checksums_ok"] and info["trailer_ok"] else 1
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)
@@ -210,6 +236,12 @@ def main(argv=None):
s.add_argument("-o", "--out"); s.set_defaults(f=cmd_new_page)
s = sub.add_parser("dump", help="print pages as JSON"); s.add_argument("hmi"); s.add_argument("--page")
s.add_argument("--encoding", default="latin-1"); s.add_argument("--raw", action="store_true"); s.set_defaults(f=cmd_dump)
s = sub.add_parser("build-tft", help="compile to .tft (research stage: NX4832T035, few component types; "
"needs a Nextion Editor installation for the firmware files)")
s.add_argument("hmi"); s.add_argument("tft")
s.add_argument("--editor-dir", default=r"C:\Program Files (x86)\Nextion Editor"); s.set_defaults(f=cmd_build_tft)
s = sub.add_parser("tft-info", help="header fields, layout table and checksum status of a .tft")
s.add_argument("tft"); s.set_defaults(f=cmd_tft_info)
a = ap.parse_args(argv)
try:
return a.f(a) or 0
+8
View File
@@ -34,6 +34,14 @@ def header_info(tft: bytes) -> dict:
}
OBJ_SIZE, REC_SIZE = 232, 24 # object record / attribute record in the page section
def name_hash(name: str) -> int:
"""Hash under which page and component names are stored: CRC of the name NUL-padded to 14."""
return word_per_byte_crc(name.encode("latin-1")[:14].ljust(14, b"\0"))
RES_START = 0x10000 # resource area: firmware files, pictures, fonts
OFF_RES_SIZE, OFF_RES_CRC, OFF_HEAD1_CRC, OFF_HEAD2_CRC = 0x40, 0x44, 0xC4, 0x18C
+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))
+35
View File
@@ -0,0 +1,35 @@
"""Nextion script -> the tokenised form stored in a .tft (research stage; see docs/FORMAT.md)."""
from __future__ import annotations
import re
import struct
class Unsupported(Exception):
"""The project uses something whose compiled form has not been worked out yet."""
class Context:
pass
def group_lines(group) -> list[str]:
return [(r if isinstance(r, bytes) else r.value).decode("latin-1") for r in group.records]
def statements(lines) -> list[str]:
out = []
for ln in lines:
ln = ln.split("//")[0].strip()
if ln:
out.append(ln)
return out
def compile_line(line: str, ctx: Context) -> bytes:
if line == "baud=115200":
return b"\x04\x04\x0e\x00\x00=\x03" + struct.pack("<I", 115200)
m = re.fullmatch(r"page (\S+)", line)
if m:
return b"\x09\x0b\x04" + m.group(1).encode()
raise Unsupported("script line %r" % line)