mangavalkandClaude Fable 5.2 f66c902443 tft: page section format, pictures/fonts, first builder (nxhmi build-tft)
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>
2026-11-16 18:13:11 +01:00
2026-11-15 16:05:41 +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

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.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:

    {"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.

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