Files
openhmi-nx/docs/COVERAGE.md
T
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

5.7 KiB

Coverage report (updated 2026-11-15)

What nextion-hmi-tools covers today compared with Nextion Editor 1.68, and what is missing. "Verified" means checked against the real Editor: either the Editor's own output is reproduced byte for byte, or a file written by nxhmi was opened in the Editor and showed the expected result.

Summary

Area Status
Reading .HMI files complete for everything seen so far
Writing .HMI files (edit, add, build from scratch) complete for Basic-series projects
Checksums (page, project header, file table) complete, verified
Components 31 / 31 types (20 Basic + 11 Intelligent-only) read/write/create
Readable JSON (enum names, colours) done for every value list the Editor documents
Pictures Basic series complete; Intelligent compressed format missing
Fonts black/white complete incl. generation from TrueType; anti-aliased missing
Rendering pages like the Editor pixel-identical for most components incl. picture skins; radio ~93-97 %, QR placeholder
New projects from scratch project.new_project(model) for 12 Basic/Intelligent models; the generated demo is byte-identical to the Editor's re-save
Compiling .tft firmware research only -- not possible yet

Covered in detail

File container and integrity

  • File table + backup table at 0x80000, Editor-style replace (append + delete), fresh compact files. Verified: 34 sample files re-written byte-identical; from-scratch files open in the Editor.
  • All three checksums (CRC-32/0x04C11DB7, STM32-style feeding) -- 276 Editor-written pages verify.

Project header (main.HMI)

  • Model id + series byte, text-encoding index, resource list (pages, pictures, fonts).
  • Adding pages, pictures and fonts updates it correctly (verified in the Editor).

Pages and components

  • Byte-exact round trip of every page tested (204 pages).
  • All 31 component types with the Editor's own default attributes (templates_*.json): page, text, scrolling text, number, xfloat, button, dual-state button, progress bar, picture, crop, hotspot, touch cap, gauge, waveform, slider, timer, variable, checkbox, radio, QR code, and Intelligent-only video, audio, Gmov, ExPicture, ComboBox, SLText, FileStream, FileBrowser, DataRecord, Switch, TextSelect.
  • Event code (all event groups) as plain text lines.
  • Text vs. number attributes detected reliably (length-limit companion rule).
  • Signed values (e.g. number val) supported.

Readable values

  • Value names for vscope, sta (per component type), style, xcen, ycen, isbr, pw, format, dir, en, mode, psta, dez, variable type, QR logo -- taken from the Editor's own attribute notes. Colours as #rrggbb. Still round-trips byte for byte.

Pictures (Basic series)

  • N.i (RGB565, panel-native rotated order) and N.is (original file) -- encoder output is byte-identical to the Editor's; adding pictures verified in the Editor.

Fonts

  • .zi version 6, black/white: decode/encode byte-identical to the Editor (224-glyph font).
  • New fonts from any TrueType/OpenType file (proportional or fixed width, ascii / iso-8859-1); verified rendering in the Editor.

Rendering

  • See RENDER.md: a real 6-page project renders pixel-identical; per-component tests 100 % for text, number, xfloat, buttons, progress bar, slider, checkbox, picture, crop, waveform.

Tooling

  • CLI: info verify decode encode set add add-picture add-font new-page kinds render dump.
  • 66 unit tests; the only binary fixture is our own demo re-saved by Nextion Editor (no Nextion files).

Demo project

  • examples/make_demo.py builds a 3-page project from code (fonts from Pillow's CC0 font, generated pictures). Nextion Editor re-saves it byte for byte unchanged, every entry including main.HMI.

Missing

.HMI side

Item Notes
Intelligent picture format 4 block codec with 8-bit alpha; first findings in FORMAT.md
Anti-aliased fonts, multi-byte encodings (GB2312, Big5, ...) only B/W single-byte fonts seen
Other display series Discovery / Enhanced / Edge not sampled; only Basic + Intelligent templates
Display direction picture/glyph order verified for one direction (main.HMI byte 13 = 3) only
Some header fields main.HMI bytes 8, 13, 36, 0x41; page header 21/23; entry bytes 25-27
Font name shown in the Editor's Fonts panel cosmetic, generated fonts show an odd label
Media resources video / audio / Gmov files themselves (not just the components)
Editor features beyond the file simulator/debugger, upload over serial (Nexus covers upload)

Rendering

Item Notes
Radio circle ~93-97 %: outline/dot differ by +-1 px at some radii (in progress)
QR code placeholder; needs the Editor's QR settings
Pressed / runtime states, Intelligent-only components not drawn

.tft compilation (firmware for the display)

Item Status
File layout mapped (header, embedded Nextion files, project section, trailer)
Layout table decoded (fixed XOR key)
Trailer checksum works for same-length edits; unknown for different lengths (stuck)
3 header checksums (0x44, 0xC4, 0x18C) not analysed
Compiled page format, event-code tokens first look only
Pictures and fonts inside the TFT not analysed
Licensing every .tft embeds Nextion's firmware files; the repo must never ship them -- a builder would read them from the user's own Editor installation

Suggested next steps

  1. Intelligent picture format 4 (needed for Intelligent displays).
  2. .tft: try the remaining trailer-checksum ideas listed in NOTES.md; then the compiled page format.
  3. Sample the other display series to confirm templates and picture order.