2026-11-15 15:11:02 +01:00
# 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
2026-11-15 15:20:59 +01:00
Every percentage is a count with a stated basis, so it can be checked (details in
[docs/COVERAGE.md ](docs/COVERAGE.md )).
2026-11-15 15:11:02 +01:00
2026-11-15 15:20:59 +01:00
| 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 |
2026-11-16 14:35:50 +01:00
| Display series | **100 %** (5/5) | Basic, Enhanced, Intelligent, Edge, Discovery: all 27 models, series bytes, picture format and storage direction per series |
2026-11-16 13:22:25 +01:00
| 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 |
2026-11-16 13:42:50 +01:00
| 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 |
2026-11-16 00:34:11 +01:00
| Readable attribute names in JSON | **100 %** (31/31 types) | every value list the Editor documents, incl. the Intelligent-only types and load effects |
2026-11-15 16:17:23 +01:00
| Rendering, Basic components | **100 %** (20/20 pixel-exact) | incl. gauges and QR codes (own encoder, no dependencies) |
2026-11-16 00:26:27 +01:00
| 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) |
2026-11-16 23:31:12 +01:00
### `.tft` compilation (`nxhmi build-tft`)
Research stage. The goal is output byte-identical to Nextion Editor's; anything not measured is
refused with the reason instead of guessed. Checked against 84 Editor-compiled sample projects.
2026-11-16 23:47:16 +01:00
**Firmware files (needed once, not in this repo).** Every `.tft` embeds seven of Nextion's own
firmware files (`input.bin` , `asp0.dll` , `cd0.dll` , `qr0.bin` , `syscom.bin` , `h0-0.dll` ,
`h1-0.dll` ). They are Nextion's property, so this repo cannot include them. Copy them from your
own Nextion Editor installation into the repo's [`firmware/` ](firmware/README.md ) folder, which git
ignores:
```
python -m nxhmi firmware --from "C:\Program Files (x86)\Nextion Editor"
```
Because the files cannot be shipped, the repo ships their SHA-256 hashes instead
([`src/nxhmi/firmware.sha256` ](src/nxhmi/firmware.sha256 ), from Nextion Editor 1.68.2.3035). Every
build checks the files against these hashes first, and refuses missing files or files from another
Editor version. `python -m nxhmi firmware` shows the state per file. Use `--firmware-dir` or
`NXHMI_FIRMWARE_DIR` to keep them elsewhere.
2026-11-16 23:31:12 +01:00
| Sub-goal | Status | Basis |
|---|---|---|
| File container | **done** (4/4) | header, layout table, the four checksums, resource area |
| Pictures and fonts in the `.tft` | **done** (2/2) | any number of each (Basic picture format) |
| Page section structure | **done** | code blob, name hashes, RAM image, attribute records, page table, object records |
| Script: statements | **mostly** | assignments, arithmetic, numbers, global `int` variables, attribute references, `if` / `else if` / `else` / `while` / `for` . Not yet: `>=` (inferred only), mixed `&&` /`||` , string attributes and string functions, negative global initial values |
| Script: commands | **39 %** (25/64) | commands whose token was read from a compiled sample |
| Script: system variables and colours | **40 %** (29/72) | same basis |
| Component types (Basic) | **65 %** (13/20) | page, hotspot, text, number, button, picture, crop, progress bar, checkbox, radio, int variable, timer, touch cap. Missing: slider, dual-state button, float, scrolling text, gauge, waveform, QR code |
| Component variants | **partly** | number: all backgrounds and border styles. Button: all 5 styles, solid background only. Text: flat on solid colour only. Progress bar: horizontal, solid colours only. Checkbox: default style only. Page: solid colour only. No global (`vscope` ) components, no drag / effects |
| Display directions | **25 %** (1/4) | 90 degrees (landscape) only |
| Display models | **4 %** (1/27) | NX4832T035 only |
| Tested on a real display | **no** | byte-identity with the Editor is the only evidence so far |
2026-11-15 15:11:02 +01:00
2026-11-15 15:20:27 +01:00
## 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.
2026-11-15 15:11:02 +01:00
## 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`
```
2026-11-15 15:27:01 +01:00
## 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`.
2026-11-15 15:11:02 +01:00
## 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 ).