# 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.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; 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](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 | |---|---| | 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`) | | Pictures and fonts inside the TFT | solved (FORMAT.md 7.2) | | Compiled page format | structure solved (code blob, name hashes, RAM image, attribute records, page table, object records -- FORMAT.md 7.3-7.5); 13 of 20 Basic types in `nxhmi.tft_types` (page, hotspot, text, number, button, picture, crop, progress bar, checkbox, radio, int variable, timer, touch cap; variants and limits in the README table); missing: slider, dual-state button, float, scrolling text, gauge, waveform, QR code | | Event-code tokens | solved for what was sampled (FORMAT.md 7.6): 27 commands, 33 system variables/colours, numbers, global variables, attribute references, if/else/while/for. Not sampled: string functions and attributes, the remaining commands and system variables, `>=` op code | | Builder (`nxhmi build-tft`) | byte-identical to the Editor for the supported subset (one model: NX4832T035); refuses anything else. **Never tested on a real display** | | 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. `.tft`: script token table, then component types one at a time (see NOTES.md); a second display model. 2. The anti-aliasing routine of Intelligent rounded shapes (switch knob/track, ComboBox). 3. The premultiplied-alpha colour step for transparent JPEG pictures (a few levels off).