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

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