Files
openhmi-nx/CLAUDE.md
T
mangavalkandClaude Fable 5.2 f66c902443 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>
2026-11-16 18:13:11 +01:00

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 .tft output (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.md needs evidence (byte-identical Editor output, or the Editor accepting a file we wrote). Mark guesses as OPEN.
  • Keep docs/COVERAGE.md and 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.py for the style: one rule, one measured expectation).