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>
67 lines
3.7 KiB
Markdown
67 lines
3.7 KiB
Markdown
# 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).
|