Files
openhmi-nx/src/nxhmi/tft_build.py
T
mangavalkandClaude Fable 5.2 99a5240af0 tft: script tokens, global variables, timers, control flow
build-tft now reproduces 35 Editor-made samples byte for byte: assignments,
arithmetic, 27 commands, system variables and colours, attribute references,
Program.s globals, all page/hotspot/timer events, if/else/while/for.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-16 18:23:14 +01:00

284 lines
14 KiB
Python

"""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 .checksum import word_per_byte_crc
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, "tim": 33, "en": 34, "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),
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}),
}
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, 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))
n = len(pages)
decl, program_lines = tft_code.declarations(tft_code.statements(program.splitlines()))
if any(v < 0 for v in decl.values()):
raise Unsupported("global variables with a negative initial value")
g = 4 * len(decl)
blob = bytearray(struct.pack("<8I", 0x24 + g + 6 * n, 3, 0x1C, 4, 0x20, 4 + g, 0x24 + g, 6 * n))
blob += bytes(4) + b"".join(struct.pack("<I", v) for v in decl.values()) + bytes(4)
for h, i in names:
blob += struct.pack("<IH", h, i)
program_off = len(blob)
offsets = {name: 4 * i for i, name in enumerate(decl)}
descriptors = b"".join(struct.pack("<III", h, o, 9) for h, o in
sorted((word_per_byte_crc(name.encode("latin-1")), o) for name, o in offsets.items()))
# record numbers are needed before any script is compiled: number them first
where, base_rec = {}, 0 # (page name, component name) -> (first record, type)
for page in pages:
pname = page.components[0].get("objname")
for c in page.components:
tid = _u(c.attr("type"))
if tid not in TYPES:
raise Unsupported("component type %d (%s)" % (tid, c.get("objname")))
where[(pname, c.get("objname"))] = (base_rec, TYPES[tid])
base_rec += TYPES[tid]["slots"]
current = [None]
def attr(path):
if len(path) == 3:
key, name = (path[0], path[1]), path[2]
elif len(path) == 2:
key, name = (current[0], path[0]), path[1]
else:
return None
if key not in where:
return None
first, t = where[key]
slot = {**t["const"], **t["ram"]}.get(name)
return None if slot is None else first + slot[0]
ctx = tft_code.Context(offsets, {k[1] for k in where}, attr)
def section(lines, label=None):
if label:
blob.extend(_chunk(label))
for c in tft_code.compile_lines(lines, ctx):
blob.extend(_chunk(c))
blob.extend(_chunk(b""))
section(program_lines + ["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
pre, post = [], []
current[0] = page.components[0].get("objname")
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
group = g + 4 + (4 if tid == 121 else len(ram)) # RAM address of the component's data
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("<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():
ram += bytes(-len(ram) % min(size, 4))
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
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([])
section([])
else:
section([])
if t["flag"] & 0x10:
erase = len(blob)
blob += _chunk(fill)
section([])
code_at = [0xFFFFFFFF] * 4 # down, up, timer, unload (object +0x0C..)
for i, (label, group_name, wanted) in enumerate((
(b"down", "codesdown", t["flag"] & 0x10), (b"up", "codesup", t["flag"] & 0x10),
(None, None, False), (b"unload", "codesunload", tid == 121))):
if wanted:
if ev.get(group_name):
code_at[i] = len(blob) + 4 + len(label)
section(ev.get(group_name, []), label)
if tid == 121:
pre, post = ev.get("codesload", []), ev.get("codesloadend", [])
if tid == 51:
# event: label, "S <1>", the event lines; registered by two init lines
blob += _chunk(b"timer")
code_at[2] = len(blob)
blob += _chunk(b"S \x03" + struct.pack("<I", 1))
first = rec_base + slot0
init.append(b"\x09\x22\x08\x01" + struct.pack("<I", first + 8) + (",%d," % cid).encode()
+ b"\x01" + struct.pack("<I", first + 7) + b",0")
init.append(b"L \x03" + struct.pack("<I", len(blob)))
section(ev.get("codestimer", []))
obj = bytearray(b"\xff" * tft.OBJ_SIZE)
struct.pack_into("<BBBBII", obj, 0, tid, cid, 0, t["flag"], draw, erase)
struct.pack_into("<4I", obj, 0x0C, *code_at)
struct.pack_into("<IHBBI6HI", obj, 0x1C, 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))
for raw in init:
blob += _chunk(raw)
for c in tft_code.compile_lines(pre, ctx):
blob += _chunk(c)
blob += _chunk(b"\x09\x21\x08")
section(post)
table.append((first_obj, len(page.components), names_off, rec_base, len(ram)))
records += prec
rec_base += len(prec) // tft.REC_SIZE
rec_off = len(blob) + len(descriptors)
ptable = b"".join(struct.pack("<HHIII", f, cnt, no, rec_off + rb * tft.REC_SIZE, rs) for f, cnt, no, rb, rs in table)
return bytes(blob), descriptors, 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, descriptors, 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 + descriptors + 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(descriptors) + len(records))
pt = base + len(blob) + len(descriptors) + len(records)
layout = [len(blob), len(blob), len(descriptors) // 12, len(blob) + len(descriptors), 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))