Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
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 |
81 % (6.5/8 milestones) | nxhmi build-tft: byte-identical to the Editor for NX4832T035 projects with pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts and script (assignments, arithmetic, 27 commands, if/else/while/for, global variables); the other component types not yet; never tried on a display |
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.
