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

+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()