0x44 = CRC of the resource area, 0xC4 = CRC of header [0,0xC4), 0x18C = CRC of [0xC8,0x18C); trailer = CRC of the whole file ^ (len & 0xFF) ^ 0x56. tft.seal() recomputes all of them. Verified against 24 Editor-made files of 8 lengths. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
3.5 KiB
Working on this repo
Python package nxhmi (in src/): read, verify, edit, write and render Nextion Editor .HMI
projects, plus research on .tft firmware. No runtime dependencies; Pillow for pictures, fonts
and rendering.
Layout
src/nxhmi/
checksum.py the three CRCs (page, main.HMI, file table)
container.py .HMI file system: tables, entries, Editor-style replace, fresh files
page.py pages, components, attributes, event code
components.py create components from templates_basic/intelligent.json (Editor defaults)
enums.py readable attribute values (names, #rrggbb)
models.py display models (id, series, resolution)
project.py new projects, add page/picture/font, decode to folder / encode back
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)
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/)
.mcp.json registers the MCP server for Claude Code in this repo
.claude/skills/nextion-hmi/SKILL.md how to use the tools on a user's project (keep in sync with mcp_server.py)
tests/ unittest suite; fixtures/demo_editor_saved.HMI = the demo re-saved by the Editor
tools/ template generator
docs/ FORMAT.md (spec), RENDER.md, COVERAGE.md, NOTES.md (open points, what was tried)
Commands
python -m unittest discover -s tests # all tests (run from the repo root)
python examples/make_demo.py # rebuild demo/ after changing writers or the renderer
PYTHONPATH=src python -m nxhmi verify demo/demo.HMI
After rebuilding the demo, tests/test_project.py::Demo must still pass: the generated demo has to
stay byte-identical to the Editor's re-save in tests/fixtures/. If a deliberate change breaks
that, re-save the demo with Nextion Editor (open, File > Save As) and replace the fixture.
Editor version
All findings and the fixture come from Nextion Editor 1.68.2.3035 (nxhmi.TESTED_EDITOR_VERSION).
When verifying against a different Editor build, say so in the commit and in docs/NOTES.md; if a
new build writes different bytes, document the difference in docs/FORMAT.md per version and bump
TESTED_EDITOR_VERSION only after the fixture is re-saved and all tests pass.
Rules
- Black-box only. Formats are worked out by changing projects in Nextion Editor and comparing files, or by asking the Editor whether a hand-made file loads. Never decompile, decrypt or patch Nextion software.
- Never commit Nextion's files: no
.tftoutput (it embeds Nextion firmware), nothing from the Editor's install folder, no third-party projects. Test data is generated (examples/) or is our own demo re-saved by the Editor. - Every format claim in
docs/FORMAT.mdneeds evidence (byte-identical Editor output, or the Editor accepting a file we wrote). Mark guesses as OPEN. - Keep
docs/COVERAGE.mdand the README coverage table current when something is added. - New user-facing features get an MCP tool (with a test in
tests/test_mcp.py) and a line in the skill. - Writers must stay byte-identical to the Editor where we have samples; add a test when a new
rule is learned (see
tests/test_render.pyfor the style: one rule, one measured expectation).