Files
openhmi-nx/README.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

133 lines
6.8 KiB
Markdown

# openhmi-nx
Open-source tools for **Nextion HMI projects**: decode, edit, encode and render `.HMI` files
without Nextion Editor -- and, as research in progress, compile `.tft` firmware.
- decode a project into readable JSON + text (diff it, review it, keep it in git) and encode it back
- create projects, pages, components, pictures and fonts (rasterized from any TrueType font) from code
- render pages to PNG, matching the Editor's canvas pixel for pixel for nearly every component
- verify every checksum in a project
The file format, including its checksums, is documented in [docs/FORMAT.md](docs/FORMAT.md). It
was worked out black-box -- by editing projects in Nextion Editor and comparing the files it
writes; no Nextion software was decompiled.
> Not affiliated with or endorsed by Nextion / ITEAD. "Nextion" is their trademark.
![demo home page rendered by nxhmi](demo/render/home.png)
## Status
Every percentage is a count with a stated basis, so it can be checked (details in
[docs/COVERAGE.md](docs/COVERAGE.md)).
| Area | Coverage | Basis |
|---|---|---|
| `.HMI` read / write / build from scratch | **100 %** of everything seen | every entry type in Editor-written files round-trips byte-identical; new projects open in the Editor |
| Checksums (`.HMI`) | **100 %** (3/3) | page, project header, file table |
| Component types (read, write, create) | **100 %** (31/31) | all types in the Editor's toolbox, incl. 11 Intelligent-only |
| Display series | **100 %** (5/5) | Basic, Enhanced, Intelligent, Edge, Discovery: all 27 models, series bytes, picture format and storage direction per series |
| Picture formats | **100 %** (2/2) | raw RGB565 (Basic) and run-length + alpha or JPEG for quality < 100 (Intelligent), byte-identical to the Editor (transparent JPEG pictures: near-identical), every display direction |
| Font modes | **100 %** (2/2) | black/white and "anti-aliased" (a header flag; glyphs stay 1-bit, verified in the simulator); single- and multi-byte encodings (GB2312, Big5, Shift-JIS, KS C 5601, UTF-8), Editor fonts round-trip byte-identical |
| Readable attribute names in JSON | **100 %** (31/31 types) | every value list the Editor documents, incl. the Intelligent-only types and load effects |
| Rendering, Basic components | **100 %** (20/20 pixel-exact) | incl. gauges and QR codes (own encoder, no dependencies) |
| Rendering, all components | **94 %** (29/31 pixel-exact) | Intelligent ComboBox and Switch are drawn, but their anti-aliased edges are approximate (~99 % / ~92 % of pixels exact) |
| `.tft` compilation | **69 %** (5.5/8 milestones) | `nxhmi build-tft`: byte-identical to the Editor for NX4832T035 projects with pages, hotspots, int variables, pictures and fonts; other component types and most script not yet |
## Compatibility
Everything here was reverse-engineered and verified against **Nextion Editor 1.68.2 (build
1.68.2.3035)** on Windows; `nxhmi.TESTED_EDITOR_VERSION` holds that version. Files written by nxhmi
open in that Editor, and the test fixture is a project re-saved by it.
- Older projects (tested with one saved by an older Editor in 2019) read and round-trip fine; when
1.68.2 re-saves them it upgrades a few header bytes (see docs/FORMAT.md).
- **After a Nextion Editor update**: open `demo/demo.HMI` in the new Editor, File > Save As, and
compare it with `tests/fixtures/demo_editor_saved.HMI` (e.g. `python -m nxhmi info` on both, or
replace the fixture and run the tests). If anything differs, the format changed -- please open
an issue with the Editor version.
## Install
Python 3.9+. Pillow is only needed for pictures, font generation and rendering.
```
pip install -e . # or run with PYTHONPATH=src
pip install pillow # optional
```
## Command line
```
python -m nxhmi info project.HMI # entries, pages, checksum status
python -m nxhmi verify project.HMI # check every checksum
python -m nxhmi decode project.HMI folder/ # -> manifest.json, Program.s, pages/*.json, resources/
python -m nxhmi encode folder/ new.HMI # folder -> fresh .HMI
python -m nxhmi dump project.HMI --page home # one page as JSON
python -m nxhmi set project.HMI home title txt "Hello"
python -m nxhmi add project.HMI home button x=10 y=60 w=120 h=40 txt=Hi --name bHi
python -m nxhmi new-page project.HMI settings
python -m nxhmi add-picture project.HMI logo.png
python -m nxhmi add-font project.HMI DejaVuSans.ttf 24
python -m nxhmi render project.HMI pngs/ # one PNG per page
python -m nxhmi kinds # component kinds for `add`
```
## Use with Claude
The repo is set up for Claude (Claude Code, Claude Desktop or any MCP client):
- **MCP server** -- `python -m nxhmi.mcp_server` (stdio, no dependencies). Tools: `info`,
`get_page`, `set_attributes`, `set_event`, `add_component`, `remove_component`, `add_page`,
`new_project`, `add_picture`, `add_font`, `verify`, `list_kinds`, `schema`, and
**`render_page`, which returns the page as an image** so the model can see what it built.
Attribute values can be readable names (`"xcen": "center"`, `"bco": "#ff0000"`).
`.mcp.json` registers it automatically when Claude Code runs in this repo; elsewhere add:
```json
{"mcpServers": {"nxhmi": {"command": "python", "args": ["-m", "nxhmi.mcp_server"],
"env": {"PYTHONPATH": "/path/to/openhmi-nx/src"}}}}
```
- **Skill** -- [.claude/skills/nextion-hmi/SKILL.md](.claude/skills/nextion-hmi/SKILL.md): the
edit -> verify -> render loop, value names, fonts/pictures, event code, limits.
- **Machine-readable CLI** -- `info --json`, `schema <kind>`, `dump --page`.
## Python
```python
from nxhmi import project, fonts, components as C
from nxhmi.render import Renderer
h = project.new_project("NX4832T035_011", "home") # no Nextion files needed
font = project.add_font(h, fonts.from_ttf(None, 24)) # None = Pillow's bundled CC0 font
page = project.add_page(h, "settings")
C.add(page, "button", x=10, y=10, w=140, h=40, txt="back", font=font,
events={"codesup": ["page home"]})
h.write("1.pa", page.pack())
h.save("my.HMI") # opens in Nextion Editor
Renderer(h).render("settings").save("settings.png")
```
## Demo
`demo/` is generated by [examples/make_demo.py](examples/make_demo.py): a 3-page project
(`demo.HMI`), its decoded form (`decoded/`) and renders (`render/`). Nextion Editor re-saves it
byte for byte unchanged -- that re-save is the test fixture in `tests/fixtures/`.
## Tests
```
python -m unittest discover -s tests
```
## Credits
[Nextion2Text](https://github.com/MMMZZZZ/Nextion2Text) (MPL-2.0) first documented the page record
layout (read-only); [nextion-font-editor](https://github.com/hagronnestad/nextion-font-editor)
documented older font versions. This is an independent implementation.
## License
MIT, see [LICENSE](LICENSE).