Files
openhmi-nx/docs/COVERAGE.md
T
mangavalkandClaude Opus 5.5 55c2f9d6b6 Fonts: anti-aliasing flag, overhanging glyphs, Font Creator byte 18
The Font Creator's anti-aliased fonts are 1-bit glyphs with header flag 0x1E (the simulator draws
them with two colours). Map bytes 3/4 are extra columns left/right of the advance width; glyphs
are drawn starting 'left' px early. Editor-generated fonts now round-trip byte for byte.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 00:42:03 +01:00

7.4 KiB

Coverage report (updated 2026-11-15)

What openhmi-nx covers today compared with Nextion Editor 1.68.2 (build 1.68.2.3035), 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 complete: format 0 (Basic) and format 4 (Intelligent, with alpha), all display directions
Fonts complete for single-byte encodings: black/white and the anti-aliasing flag, overhanging glyphs, all display directions
Rendering pages like the Editor pixel-identical for every Basic component and 9 of 11 Intelligent-only ones; ComboBox and Switch approximate at anti-aliased edges
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

How the percentages in the README are counted

  • Display series: 5 series in the Editor's model dialog (Basic, Discovery, Enhanced, Intelligent, Edge); a series counts once its series byte and model ids are confirmed.
  • Picture formats: N.i format byte 0 (raw) and 4 (compressed).
  • Font modes: glyph mode black/white and anti-aliased.
  • Readable names: component types whose attribute notes (value lists) were read from the Editor.
  • Rendering: a component type counts as covered when every test case of it is pixel-identical to the Editor canvas (name tags and selection outline excluded). Invisible types (timer, variable, hotspot, touch cap) count when they draw nothing, like the Editor.
  • .tft milestones (8): layout map; layout table; trailer checksum (half: same-length only); the three header checksums; compiled page/component format; event-code tokens; pictures and fonts in the TFT; a builder that produces a file the display accepts.

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.
  • Intelligent: drag, load effect (pages have two more), transparency background, and the value lists of all 11 Intelligent-only types (switch direction, ComboBox arrow / expansion, TextSelect lines, SLText / DataRecord / FileBrowser scroll bar, DataRecord options, media source / state / looping). Note: the Editor lists 3D_Down for TextSelect but refuses to compile it (only 0-1 compile).

Pictures

  • N.i format 0 (Basic, raw RGB565) and format 4 (Intelligent, run-length + 7-bit alpha), stored rotated for the display direction, and N.is (original file) -- encoder output is byte-identical to the Editor's (format 4: 28 samples, all four directions); the Editor keeps our format-4 pictures unchanged; 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
Picture quality below 100 (Editor picture list "Q:") not studied
Multi-byte encodings (GB2312, Big5, ...) only single-byte fonts studied
Other display series Discovery / Enhanced / Edge not sampled; only Basic + Intelligent templates
Display direction byte 12 decoded and written (new_project(portrait=...)); picture order verified for all four (format 4); font glyph order for 90° 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
Pressed / runtime states not drawn
Anti-aliased edges (Switch, ComboBox) approximate: the simulator's coverage routine is unknown (the knob looks like a scaled pre-drawn image)

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