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>
3.7 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 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/)
.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).