# 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](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](demo/render/home.png) ## 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.2 | | 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](docs/RENDER.md)) | | `.tft` compile | research: layout mapped, partial checksum support; not usable yet | Details and the full list of gaps: [docs/COVERAGE.md](docs/COVERAGE.md). ## 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` ``` ## Python ```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](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](https://github.com/MMMZZZZ/Nextion2Text) (MPL-2.0) first documented the page record layout (read-only); [nextion-font-editor](https://github.com/hagronnestad/nextion-font-editor) documented older font versions. This is an independent implementation. ## License MIT, see [LICENSE](LICENSE).