Byte-identical to Nextion Editor 1.68.2 for NX4832T035 projects made of pages, hotspots and int variables with any pictures and fonts. Firmware files are read from the user's Editor folder at build time. FORMAT.md section 7 documents the header, resource area, code blob, attribute records, page table and objects. Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
125 lines
7.8 KiB
Markdown
125 lines
7.8 KiB
Markdown
# 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); per-type tables done for page, hotspot, int variable; the other types need their slot tables and generated draw scripts |
|
|
| Event-code tokens | encoding understood (command / system-variable / attribute-reference / number tokens); table being filled |
|
|
| 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).
|