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

+3 -1
View File
@@ -18,7 +18,9 @@ src/nxhmi/
pictures.py N.i / N.is
fonts.py .zi v6 fonts, generation from TrueType
render.py page renderer matching the Editor canvas
tft.py .tft research helpers (layout table, header checksums, trailer, seal)
tft.py .tft helpers (layout table, header checksums, trailer, seal, name hash)
tft_build.py .HMI -> .tft builder (subset; firmware files come from the user's Editor folder)
tft_code.py Nextion script -> tokenised chunks
cli.py python -m nxhmi ...
mcp_server.py MCP server (stdio JSON-RPC, no deps) -- tools for Claude incl. render_page images
examples/make_demo.py builds demo/ (demo.HMI, decoded/, render/)
+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 | **50 %** (4/8 milestones) | layout mapped, layout table decoded, all four checksums solved (any length); page format not yet, so not usable |
| `.tft` compilation | **69 %** (5.5/8 milestones) | `nxhmi build-tft`: byte-identical to the Editor for NX4832T035 projects with pages, hotspots, int variables, pictures and fonts; other component types and most script not yet |
## Compatibility
+5 -3
View File
@@ -112,11 +112,13 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th
| Layout table | decoded (fixed XOR key) |
| Trailer checksum | solved for any length (`tft.trailer`); one model measured |
| 3 header checksums (0x44, 0xC4, 0x18C) | solved (`tft.header_checksums`, `tft.seal`) |
| Compiled page format, event-code tokens | first look only |
| Pictures and fonts inside the TFT | not analysed |
| 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; the other types need their slot tables and generated draw scripts |
| Event-code tokens | encoding understood (command / system-variable / attribute-reference / number tokens); table being filled |
| 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 |
## Suggested next steps
1. `.tft`: the compiled page/component format and the event-code token table (see NOTES.md).
1. `.tft`: script token table, then component types one at a time (see NOTES.md); a second display model.
2. The anti-aliasing routine of Intelligent rounded shapes (switch knob/track, ComboBox).
3. The premultiplied-alpha colour step for transparent JPEG pictures (a few levels off).
+132
View File
@@ -327,3 +327,135 @@ width of the space glyph.
## 6. Not yet covered
See `docs/NOTES.md`.
## 7. Compiled firmware (`.tft`)
Measured on Editor 1.68.2.3035, model NX4832T035 (Basic series), landscape. Everything below is
reproduced byte for byte by `nxhmi.tft_build` for the supported subset unless marked **OPEN**.
All integers little-endian. "CRC" = the word-per-byte CRC of section 2 with seed 0xFFFFFFFF.
### 7.1 File map
| Range | Contents |
|---|---|
| 0x00000-0x0FFFF | header; unused bytes are FF |
| 0x10000-`base` | resource area, size = u32@0x40, a multiple of 0x10000, zero-padded |
| `base`-end | page section: code blob, attribute records, page table, object records, FF padding to a multiple of 4, trailer |
Header:
| Offset | Field |
|---|---|
| 0x00 | 12 constant bytes `00 01 44 4E 78 45 01 00 4C D3 00 00` (**OPEN**: meaning; probably format/Editor version) |
| 0x0C | u16 width, height, height, width |
| 0x14 | `01 00 00 02` (**OPEN**) |
| 0x18, 0x1E | u32 file offset of `cd0.dll` (twice; u16 0 between) |
| 0x22 | u32 size of `cd0.dll` |
| 0x26, 0x2A | u32 file offset, size of `asp0.dll` |
| 0x2E | u32 model id (as in main.HMI) |
| 0x32 | `21 00 00 00 01 00 0C 00 00 00` (**OPEN**) |
| 0x3C | u32 file size |
| 0x40 | u32 resource area size |
| 0x44 | CRC of the resource area |
| 0x48 | u32 0, 8 x FF, u32 0 |
| 0x58 | u32 size of code blob + attribute records |
| 0xC4 | CRC of `[0x00, 0xC4)` |
| 0xC8 | layout table: 19 u32, each XOR 0xEBAB2932 |
| 0x18C | CRC of `[0xC8, 0x18C)` as stored |
Layout table words: 0, 1, 3 = code blob size; 4 = 0x10000; 5 = `base`; 6 = page table offset;
7 = object records offset; 8 = pictures offset; 12 = fonts offset; 13 = offset of the program
inside the blob; 14 = page count | component count << 16; 15 = picture count; 17 = font count;
18 = 3; the rest 0 (**OPEN**: probably audio/video/gmov resources).
Trailer (last 4 bytes): CRC of everything before it, XOR `(file length & 0xFF) ^ 0x56`.
### 7.2 Resource area
A 0x90-byte directory of 12 entries `(u32 offset from 0x10000, u32 size, u32 0)`, then the data
in the same order: seven files copied verbatim from the Editor's install folder (`input.bin`,
`asp0.dll`, `cd0.dll`, `qr0.bin`, `syscom.bin`, `h0-0.dll`, `h1-0.dll`), all pictures, all fonts;
entries 9-11 are empty.
- Pictures: the 24-byte headers of all `N.i` entries first, then their pixel data. In each
header, u32@4 = picture number and u32@8 = offset of its data from the start of the picture
block. (One picture: identical to the `.i` entry.)
- Fonts: the 44-byte headers of all `N.zi` entries first, then the rest of each font; u32@0x18
of a header = offset of that font's data from the start of the font block.
### 7.3 Code blob
Offsets in this section are relative to `base`.
```
u32 0x24 + 6*pages, u32 3, u32 0x1C, u32 4, u32 0x20, u32 4, u32 0x24, u32 6*pages, u32 0, u32 0
page names: (u32 name hash, u16 page number), sorted by hash
program
per page: code blocks of its components, name list, RAM image, init code
```
The first ten words describe three tables at 4 + (0x1C, 0x20, 0x24) with sizes 4, 4, 6*pages;
the first two are empty when the program declares no global variables (**OPEN**: their format).
**Name hash** = CRC of the name NUL-padded to 14 bytes. Names are not stored anywhere else.
Everything after the page names is a sequence of **chunks**: `u32 length` + bytes. A chunk is one
tokenised script line; an empty chunk ends a section.
- Program: one chunk per `Program.s` statement (comments and blank lines dropped), then a chunk
`page 0` added by the Editor, then the empty chunk.
- Component block (the page itself is component 0):
- draw section -- lines, empty chunk. Page: `fill x,y,w,h,<bco>` (command `09 0D 04`, colour
as a reference to the page's `bco` record), then the Preinitialize event lines.
Types that draw themselves (progress bar, gauge, QR code, text ...) have their own script
here, generated from the attributes (**OPEN** per type).
- erase section (types with a rectangle only; empty for the page) -- `fill x,y,w,h,<page bco>`,
empty chunk.
- events: a label chunk (`down`, `up`, `unload`, `timer`, `slide` -- plain text), the event's
lines, empty chunk. Page: down, up, unload. Hotspot: down, up. Variable: none.
- After the last component of a page: one chunk with the name list `(u32 hash, u16 id)` sorted
by hash; one chunk with the RAM image followed by 8 zero bytes; type-specific init lines
(timer, slider, touch cap -- **OPEN**); the chunk `09 21 08`; the page's Postinitialize lines;
empty chunk.
RAM image: 8 x FF, then every RAM-stored attribute of every component in component order,
each aligned to its size, each component padded to 4. For a page: `sta` (u8), pad, `bco` (u16).
### 7.4 Attribute records (24 bytes)
Every component owns a fixed number of record slots (page 33, hotspot 27, variable 11,
timer 11, touch cap 10, progress bar 33, slider 40, gauge 41, QR code 33 ...); unused slots are
all zero. Record numbers are global (pages concatenated) in script references and page-relative
in the object records.
| Offset | Field |
|---|---|
| 0 | u32 8 for a page, 16 for other components |
| 4 | i32 value (constant attributes) or 4 + offset into the RAM image |
| 8, 12 | i32 maximum, minimum |
| 16 | u8 page number, u8 component id of the component to redraw on change; FF FF = none |
| 18 | u16 change action (0 = none; timers use 1 for `tim`, 2 for `en`) |
| 20 | u8 kind: 0x01 constant; 0x0B/0x0C/0x0D/0x0E x/y/w/h; 0x08 endx/endy; 0x21, 0x22, 0x31, 0x32, 0x39, 0x3F RAM-stored |
| 21 | u8 size in bytes |
| 22 | u16 0 |
Slots seen in all types: 0 `type`, 1 `id`, 3 `vscope`, 9-14 `x y w h endx endy`.
### 7.5 Page table (16 bytes per page) and object records (232 bytes per component)
Page: u16 first object number, u16 component count, u32 offset of the name-list chunk, u32
offset of the page's first attribute record (from `base`), u32 RAM image size.
Object:
| Offset | Field |
|---|---|
| 0 | u8 type, u8 id, u8 0, u8 flags (0x37 visible types, 0x27 timer/touch cap, 0x07 variable) |
| 4 | u32 offset of the draw section, FFFFFFFF if empty |
| 8 | u32 offset of the erase section, FFFFFFFF if none/empty |
| 0x0C-0x1B | more code offsets (0x14: timer event), FF when unused |
| 0x1C | u32 8 / 16 as in the records |
| 0x20 | `00 00 7F 00`, u32 0 |
| 0x28 | u16 x, y, w, h, endx, endy (0,0,1,1,0,0 for invisible types) |
| 0x34 | u32 offset of the component's code block |
| 0x38 | 88 x u16: record number (page-relative) of well-known attributes, FFFF = absent. Positions: 1 vscope, 2 sta, 4 bco, 16 pco, 20 val, 42 x, 43 y, 44 endx, 45 endy, 46 w, 47 h, 49 id, 62 type (**OPEN**: the others) |
+25
View File
@@ -130,3 +130,28 @@ The file length is always a multiple of 4 (the page section is padded with zeros
Other dead ends, for the record: seeds from header fields; header checksum fields zeroed/0xFF in
every combination; the layout table de-obfuscated before checksumming; prefixes built from
length/layout words; runs of 00/FF bytes before the file.
### Page section solved, first builder (2026-11-16)
Format: FORMAT.md section 7. `nxhmi build-tft` reproduces the Editor byte for byte for projects
made of pages (solid colour), hotspots and int variables, with any pictures and fonts, on
NX4832T035. Check with `NXHMI_TFT_SAMPLES=<folder of name.HMI + name.tft> python -m unittest
discover -s tests -p test_tft_build.py` (samples stay outside the repo).
How the samples are made: one tiny project per question (nxhmi builds them), compiled in the
Editor by a click script (open file, Compile, File > TFT file output > Output), ~45 s each.
A project whose script does not compile yields no TFT -- e.g. `sys0` is only known when
`Program.s` declares it (`int sys0=0,sys1=0,sys2=0`, as in the Editor's default program).
Useful facts not obvious from the format description:
- Text-like components need a font in the project or the compile fails.
- Every component type brings its own generated script (draw section, init lines); e.g. a
progress bar's draw section is three `fill`-like lines computed from x/y/w/h and `val`.
These must be collected per type -- the bulk of the remaining work.
- Record references in scripts (`01` + u32) are global record numbers, so adding a component
renumbers every reference after it.
Not done: script tokens beyond `baud=115200` / `page N`; timers, sliders and every drawing
component; global variables declared in Program.s (blob header tables 0 and 1); other models,
portrait, other series; and nothing has been loaded onto a display.
+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)
+125
View File
@@ -0,0 +1,125 @@
"""The .tft builder. Real Editor output cannot be in the repo (it embeds Nextion firmware), so
these tests use a fake "Editor folder" with generated stand-in files and check the structure.
Byte-identity with the Editor is checked by test_against_editor_samples when NXHMI_TFT_SAMPLES
points to a folder of <name>.HMI + <name>.tft pairs made with Nextion Editor 1.68.2."""
import glob
import os
import shutil
import struct
import tempfile
import unittest
from helpers import HAVE_PIL
from nxhmi import cli, components as C, project, tft, tft_build
from nxhmi.page import Page
SAMPLES = os.environ.get("NXHMI_TFT_SAMPLES")
class Build(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.mkdtemp()
for i, n in enumerate(tft_build.FIRMWARE_FILES):
with open(os.path.join(self.tmp, n), "wb") as fh:
fh.write(bytes([i + 1]) * (100 + 7 * i))
def tearDown(self):
shutil.rmtree(self.tmp)
def project(self):
h = project.new_project("NX4832T035_011")
p = Page.parse(h.read("0.pa"))
C.add(p, "hotspot", x=10, y=20, w=30, h=40)
C.add(p, "variable")
h.write("0.pa", p.pack())
project.add_page(h, "second")
return h
def test_structure(self):
out = tft_build.build_tft(self.project(), self.tmp)
self.assertEqual(len(out) % 4, 0)
self.assertTrue(tft.verify_header(out))
self.assertTrue(tft.verify_trailer(out))
self.assertEqual(struct.unpack_from("<I", out, 0x3C)[0], len(out))
lay = tft.layout_table(out)
base = lay[5]
self.assertEqual(base, 0x20000) # resources fit in one 64 KB block
self.assertEqual(lay[14], 2 | 4 << 16) # 2 pages, 4 components
# resource directory: first firmware file right after the 0x90-byte directory
self.assertEqual(struct.unpack_from("<II", out, 0x10000), (0x90, 100))
self.assertEqual(out[0x10090:0x10090 + 100], b"\x01" * 100)
# page table: page 0 has 3 components, 33 + 27 + 11 record slots, then page 1
first, count, names, recs, ram = struct.unpack_from("<HHIII", out, lay[6])
self.assertEqual((first, count, recs, ram), (0, 3, lay[0], 16))
self.assertEqual(struct.unpack_from("<HHIII", out, lay[6] + 16)[3], lay[0] + 71 * 24)
# name list of page 0: sorted hashes
n, = struct.unpack_from("<I", out, base + names)
hashes = [struct.unpack_from("<I", out, base + names + 4 + 6 * i)[0] for i in range(n // 6)]
self.assertEqual(hashes, sorted(tft.name_hash(x) for x in ("page0", "m0", "va0")))
# hotspot object record: type 109, id 1, rectangle
obj = out[lay[7] + 232:lay[7] + 464]
self.assertEqual(obj[:2], bytes([109, 1]))
self.assertEqual(struct.unpack_from("<6H", obj, 0x28), (10, 20, 30, 40, 39, 59))
def test_name_hash(self):
self.assertEqual(tft.name_hash("page0"), 0xAC967926) # measured in Editor output
def test_unsupported_is_reported(self):
h = self.project()
p = Page.parse(h.read("0.pa"))
C.add(p, "slider", 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")
self.project().save(hmi)
import contextlib
import io
with contextlib.redirect_stdout(io.StringIO()) as text:
self.assertEqual(cli.main(["build-tft", hmi, out, "--editor-dir", self.tmp]), 0)
self.assertEqual(cli.main(["tft-info", out]), 0)
self.assertIn('"trailer_ok": true', text.getvalue())
@unittest.skipUnless(HAVE_PIL, "needs Pillow")
def test_pictures_and_fonts_blocks(self):
import io
from PIL import Image
from nxhmi import fonts
h = self.project()
for size in ((8, 8), (20, 10)):
b = io.BytesIO()
Image.new("RGB", size, (9, 9, 9)).save(b, "PNG")
project.add_picture(h, b.getvalue())
project.add_font(h, fonts.from_ttf(None, 16))
out = tft_build.build_tft(h, self.tmp)
lay = tft.layout_table(out)
self.assertEqual((lay[15], lay[17]), (2, 1))
pics = lay[8]
# two 24-byte headers first; u32@4 = picture number, u32@8 = data offset in the block
self.assertEqual(struct.unpack_from("<II", out, pics + 4), (0, 48))
self.assertEqual(struct.unpack_from("<II", out, pics + 28), (1, 48 + len(h.read("0.i")) - 24))
self.assertEqual(out[lay[12]:lay[12] + 44][:8], h.read("0.zi")[:8])
@unittest.skipUnless(SAMPLES and os.path.isdir(tft_build.DEFAULT_EDITOR_DIR), "needs Editor-made samples")
def test_against_editor_samples(self):
from nxhmi.container import HMIFile
done = 0
for ref in sorted(glob.glob(os.path.join(SAMPLES, "*.tft"))):
hmi = ref[:-4] + ".HMI"
if not os.path.exists(hmi):
continue
try:
out = tft_build.build_tft(HMIFile.load(hmi))
except (tft_build.Unsupported, KeyError):
continue
with open(ref, "rb") as fh:
self.assertEqual(out, fh.read(), os.path.basename(ref))
done += 1
self.assertGreater(done, 0)
if __name__ == "__main__":
unittest.main()