0x44 = CRC of the resource area, 0xC4 = CRC of header [0,0xC4), 0x18C = CRC of [0xC8,0x18C); trailer = CRC of the whole file ^ (len & 0xFF) ^ 0x56. tft.seal() recomputes all of them. Verified against 24 Editor-made files of 8 lengths. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
7.3 KiB
7.3 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; run-length or JPEG for quality < 100), all display directions |
| Fonts | complete: single- and multi-byte encodings (GB2312, Big5, Shift-JIS, KS C 5601, UTF-8), black/white and the anti-aliasing flag, overhanging glyphs, all display directions; generation from TrueType for all of them |
| 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 all 27 models of the 5 series; 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.iformat 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.
.tftmilestones (8): layout map; layout table; trailer checksum; 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, loadeffect(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.iformat 0 (Basic, raw RGB565) and format 4 (Intelligent, run-length + 7-bit alpha), stored rotated for the display direction, andN.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
.ziversion 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.pybuilds 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 includingmain.HMI.
Missing
.HMI side
| Item | Notes |
|---|---|
| Display direction | byte 12 decoded and written (new_project(portrait=...)); picture order verified for all four (format 4); font glyph order verified for 0° and 90° |
| 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 | solved for any length (tft.trailer); one model measured |
| 3 header checksums (0x44, 0xC4, 0x18C) | solved (tft.header_checksums, tft.seal) |
| 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
.tft: the compiled page/component format and the event-code token table (see NOTES.md).- The anti-aliasing routine of Intelligent rounded shapes (switch knob/track, ComboBox).
- The premultiplied-alpha colour step for transparent JPEG pictures (a few levels off).