2026-11-15 15:11:02 +01:00
|
|
|
# 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, same-length trailer patch)
|
|
|
|
|
cli.py python -m nxhmi ...
|
2026-11-15 15:27:01 +01:00
|
|
|
mcp_server.py MCP server (stdio JSON-RPC, no deps) -- tools for Claude incl. render_page images
|
2026-11-15 15:11:02 +01:00
|
|
|
examples/make_demo.py builds demo/ (demo.HMI, decoded/, render/)
|
2026-11-15 15:27:01 +01:00
|
|
|
.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)
|
2026-11-15 15:11:02 +01:00
|
|
|
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.
|
|
|
|
|
|
2026-11-15 15:20:27 +01:00
|
|
|
## 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.
|
|
|
|
|
|
2026-11-15 15:11:02 +01:00
|
|
|
## 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.
|
2026-11-15 15:27:01 +01:00
|
|
|
- New user-facing features get an MCP tool (with a test in `tests/test_mcp.py`) and a line in the skill.
|
2026-11-15 15:11:02 +01:00
|
|
|
- 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).
|