Files
openhmi-nx/CLAUDE.md
T
mangavalkandClaude Opus 5.5 6f8341c66c Claude integration: MCP server with render_page images, skill, JSON CLI
- nxhmi.mcp_server: dependency-free stdio MCP server, 14 tools; readable
  values in and out; render_page returns a PNG image
- .mcp.json for Claude Code, .claude/skills/nextion-hmi/SKILL.md
- CLI: info --json, schema <kind>
- fix: project.add_page(h=...) clashed with the page height keyword
- 75 tests

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-15 15:27:01 +01:00

3.5 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 research helpers (layout table, same-length trailer patch)
  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).