Font Creator output decoded (lead/trail ranges and gaps in the header, map codes = bytes as little-endian u16 or Unicode code points) and round-tripped byte for byte; from_ttf(chars=) builds them; the renderer splits text like the simulator (any byte >= 0x81 starts a pair, missing characters advance one space) -- pixel-exact for all five encodings. Intelligent glyph data is 8-byte aligned (was 4). CLI add-font --chars/--chars-file, MCP chars. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
133 lines
6.7 KiB
Markdown
133 lines
6.7 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 | **40 %** (2/5) | Basic (T) and Intelligent (P) confirmed; Discovery, Enhanced, Edge not sampled |
|
|
| 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 | **31 %** (2.5/8 milestones) | layout mapped, layout table decoded, trailer checksum (same-length edits only); not usable 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).
|