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>
133 lines
6.8 KiB
Markdown
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.
|
|
|
|

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