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>
This commit is contained in:
commit
69e22cfb06
70 files changed
+25058
No files matched your search
@@ -0,0 +1,96 @@
|
||||
# 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.
|
||||
|
||||

|
||||
|
||||
## 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](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).
|
||||
|
||||
## 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).
|
||||
Reference in new issue
Block a user