mangavalkandClaude Opus 5.5 69e22cfb06 openhmi-nx: decode, encode, render Nextion HMI projects; .tft research
Black-box reverse-engineered .HMI format (container, three checksums,
pages, all 31 component types, pictures, fonts), readable JSON, page
renderer matching Nextion Editor, demo project built from code and a
test suite (66 tests). See docs/COVERAGE.md for status.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
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. 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.

demo home page rendered by nxhmi

Status

Area Coverage
.HMI read / write / build from scratch complete for Basic (T) and Intelligent (P) series projects; output byte-identical to Nextion Editor 1.68
Checksums all three (page, project header, file table)
Components all 31 types, with the Editor's own defaults
Readable JSON enum names and #rrggbb colours, still byte-exact on the way back
Pictures Basic series format complete; Intelligent compressed format not yet
Fonts black/white .zi v6 complete, incl. generation from TrueType; anti-aliased not yet
Rendering pixel-identical for text, numbers, buttons, sliders, bars, checkboxes, pictures, waveform...; radio ~95 %, QR placeholder (docs/RENDER.md)
.tft compile research: layout mapped, partial checksum support; not usable yet

Details and the full list of gaps: docs/COVERAGE.md.

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`

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.

S
Description
No description provided
Readme MIT
1 MiB
0 Stars 1 Watchers 0 Forks
Languages
Python 100%