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>
6.8 KiB
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. 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).
| 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.HMIin the new Editor, File > Save As, and compare it withtests/fixtures/demo_editor_saved.HMI(e.g.python -m nxhmi infoon 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, andrender_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.jsonregisters it automatically when Claude Code runs in this repo; elsewhere add:{"mcpServers": {"nxhmi": {"command": "python", "args": ["-m", "nxhmi.mcp_server"], "env": {"PYTHONPATH": "/path/to/openhmi-nx/src"}}}} -
Skill -- .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
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: 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 (MPL-2.0) first documented the page record layout (read-only); nextion-font-editor documented older font versions. This is an independent implementation.
License
MIT, see LICENSE.
