mangavalkandClaude Opus 5.5 c102157ac2 Pictures with compressed quality < 100 (JPEG variant of format 4)
Header byte 1 = quality; data type 0 = baseline JPEG of the picture padded with black to
multiples of 16 and then rotated for the display direction (libjpeg/Pillow, 4:2:0, 96 dpi),
byte-identical to the Editor for opaque pictures (18/18); alpha runs cover the padded picture.
add_picture(quality=), CLI add-picture -q, MCP add_picture quality; decoder in to_image.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 13:22:25 +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 40 % (2/5) Basic (T) and Intelligent (P) confirmed; Discovery, Enhanced, Edge not sampled
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); Editor fonts with overhanging glyphs 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 31 % (2.5/8 milestones) layout mapped, layout table decoded, trailer checksum (same-length edits only); not usable 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%