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>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-15 15:11:02 +01:00
commit 69e22cfb06
70 files changed
+25058

No files matched your search

+105
View File
@@ -0,0 +1,105 @@
# 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](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.
+251
View File
@@ -0,0 +1,251 @@
# The Nextion Editor `.HMI` project format
Reverse-engineered black-box: by editing projects in Nextion Editor (v1.68), saving, and comparing
files, and by asking the Editor whether hand-made files load ("oracle" tests). The Editor itself was
never decompiled or decrypted. Everything here was checked against real files; open points are
marked **OPEN**.
All integers are little-endian.
## 1. Container
An `.HMI` file is a tiny file system.
| Offset | Contents |
|---|---|
| `0x000000` | file table: `count` (u32), `count` × 28-byte entries, then the table checksum (u32) |
| `0x080000` | backup copy of the file table (byte-identical, incl. checksum) |
| `0x380000` | u32 `0xFFFFFFFF` |
| `0x6FFFF8` | ASCII `ver21234` |
| `0x700000` | entry data, packed back to back |
The space between these areas is normally zero (older files can contain stale data, e.g. at
`0x100000`, which is ignored).
### File table entry (28 bytes)
| Offset | Size | Field |
|---|---|---|
| 0 | 16 | name, NUL padded (`main.HMI`, `Program.s`, `0.pa`, `0.i`, `0.is`, `0.zi`, ...) |
| 16 | 4 | start offset in the file |
| 20 | 4 | size |
| 24 | 1 | deleted flag |
| 25 | 3 | unknown (looks like uninitialised memory; **is** covered by the table checksum) |
When the Editor replaces an entry it appends the new data to the end of the file, adds a new
entry, and marks the old entry deleted: deleted flag = 1 **and first byte of the name = 0**
(e.g. `\0ain.HMI`). The Editor finds entries by name, so setting only the flag is not enough.
Deleted entries stay in the table and their data stays in the file.
If the primary table's checksum fails the Editor silently uses the backup table. If both fail it
reports "Version mismatch". The Editor also rewrites a file when opening it (it repairs the
primary table from the backup, among other things) -- never reuse a test file after opening it.
### Entry names
| Name | Contents |
|---|---|
| `main.HMI` | project header (display model, resource list) -- 224 bytes |
| `Program.s` | start-up script, plain text (no checksum) |
| `N.pa` | page N |
| `N.i` | picture N as the display uses it (section 4) |
| `N.is` | picture N's original source file (section 4) |
| `N.zi` | font N (section 5) |
### `main.HMI` (project header)
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | checksum (section 2) |
| 4 | 4 | header size = 0x60 = start of the resource list |
| 8 | 1 | 1 (**OPEN**) |
| 9 | 1 | 0x41 in a 2019 file, 0x44 after saving with Editor 1.68 (Editor/format revision?) |
| 10 | 1 | 0x21 |
| 11 | 1 | display series: 0 = Basic (T), 3 = Intelligent (P); others **OPEN** |
| 12 | 1 | text encoding index (1 = iso-8859-1; an unknown value makes the Editor fail with "'null' is not a supported encoding name") |
| 13 | 1 | 3 (**OPEN**; not the model index) |
| 14 | 1 | 0x4F |
| 16 | 4 | model id (e.g. 0xB23BC018 NX4832T035_011, 0x181169DA NX4827P043_011); must match the series byte, otherwise the Editor falls back to its first model |
| 24 | 4 | 0x60 |
| 28 | 4 | resource count |
| 36 | 4 | 1 or 2 (**OPEN**) |
| 0x41 | 1 | 3 after switching to an Intelligent model (**OPEN**) |
| 0x60 | 16 × count | resource list: type[8] + name[8], e.g. `pa`/`3.pa`, `i`/`0.i`, `zi`/`0.zi` |
Adding a page = new `N.pa` entry + one resource-list entry + count + 1 + new checksum (verified:
the Editor shows pages added this way). `.is` entries are not listed.
## 2. Checksums
All three use CRC-32 with polynomial `0x04C11DB7`, MSB-first (not reflected), initial value
`0xFFFFFFFF`, no final XOR -- the algorithm of the STM32 hardware CRC unit. They differ in how
input is fed.
### Page checksum (first 4 bytes of every `N.pa`)
Every input **byte** is zero-extended to a 32-bit word and fed as one word. Input:
```
page[4:] # whole page after the checksum field
+ datasize (4 bytes, LE) # = page header offset 4
+ numberobj (4 bytes, LE) # = page header offset 12
+ page[20] + page[21] # header bytes 20 and 21
```
Evidence: two saves differing in one bit place that bit's influence at `x^(32·k)` -- adjacent file
bytes are exactly 32 bits apart in the CRC stream; a fixed 10-word tail appears after the page;
the tail contents were solved over pages of different lengths and component counts; then
verified on 276 Editor-written pages (including a 2019 file) and by the Editor accepting pages
built from scratch.
### `main.HMI` checksum (first 4 bytes)
Same word-per-byte scheme. Input: `main[4:] + main[16:20] + main[4:8] + main[10] + main[14]`.
**OPEN**: the last two tail bytes were 0x21, 0x4F in every sample; they may be constants (they equal
the page header's "version" bytes) rather than fields.
### File table checksum (u32 right after the last entry)
Input read as **little-endian 32-bit words**: the table from `count` through the last entry, then
the constant word `0x43454441` (ASCII "ADEC").
## 3. Pages (`N.pa`)
### Header (56 bytes)
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | checksum (above) |
| 4 | 4 | datasize = total page length |
| 8 | 4 | infoaddr = 56 (start of component table) |
| 12 | 4 | numberobj = component count |
| 16 | 4 | password |
| 20 | 1 | locked |
| 21 | 1 | 0x4F in every file seen (**OPEN**) |
| 22 | 1 | 0x21 (33) in every file seen -- format version? |
| 23 | 1 | 0 (**OPEN**) |
| 24 | 16 | page name |
| 40 | 16 | reserved (zero) |
### Component table
`numberobj` entries of `(u32 offset, u32 size, u32 unknown=0)`. Offset is relative to byte 56.
The page itself is component 0.
### Component data
A sequence of records `u32 length + bytes`, ending with an empty record. Records are grouped:
a header record `"<group>-<n>"` is followed by n records.
* `att-<n>`: attributes. Each record = 16-byte NUL-padded name + value. Integers are unsigned
LE of 1, 2 or 4 bytes (`val` has a different width per component type); `objname`, `txt`
(and other text attributes) are raw text in the project encoding (iso-8859-1 by default).
* `codes<event>-<n>`: event code, one record per line. Seen: `codesload` (preinitialize),
`codesloadend` (postinitialize), `codesdown` (touch press), `codesup` (touch release),
`codesunload` (page exit), `codestimer`, `codesslide` (slider move).
Attribute names seen so far: `aph bco bco1 bco2 borderc borderw ch dis disup down drag effect en
endx endy first font format groupid0 groupid1 h hig id isbr key left lenth lockobj maxval minval
mode movex movey objname pco pco2 pic pic1 pic2 picc picc1 picc2 psta pw right sendkey spax spay
sta style tim time txt txt_maxl type up val vscope w wid x xcen y ycen`.
Text attributes are `objname` and every attribute that has a length-limit companion in the same
component (`txt`/`txt_maxl`, `path`/`path_m`, `dir`/`dir_m`, `filter`/`filter_m`,
`format`/`format_m`, `vvs2`/`vvs2_m`). The same name can be a number elsewhere (`dir` is a u8 on
scrolling text, `format` a u8 on number).
Component `type` values (all placed in Editor 1.68; full default attribute lists in
`src/nxhmi/templates_*.json`):
| type | component | | type | component |
|---|---|---|---|---|
| 0 | waveform | | 59 | xfloat |
| 1 | slider | | 60 | ExPicture * |
| 2 | Gmov * | | 61 | ComboBox * |
| 3 | Video * | | 62 | SLText * |
| 4 | Audio * | | 63 | FileStream * |
| 5 | TouchCap | | 65 | FileBrowser * |
| 51 | timer | | 66 | DataRecord * |
| 52 | variable | | 67 | Switch * |
| 53 | dual-state button | | 68 | TextSelect * |
| 54 | number | | 98 | button |
| 55 | scrolling text | | 106 | progress bar |
| 56 | checkbox | | 109 | hotspot |
| 57 | radio | | 112 | picture |
| 58 | QRcode | | 113 | crop |
| 116 | text | | 121 | page |
| 122 | gauge | | | |
\* Intelligent series only. Attribute sets of shared types are identical on Basic and Intelligent
projects. `sta` on pages/texts: 1 = solid colour, 2 = picture.
## 4. Pictures
`N.is` = 27-byte header + the original image file, untouched (verified byte-identical with the
PNG that was imported):
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | `0A 64 01 01` |
| 8 | 4 | data offset = 27 |
| 12 | 2+2 | width, height |
| 16 | 4 | length of the embedded file |
| 24 | 3 | file type, e.g. `png` |
`N.i` = 24-byte header + pixels:
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | `0B 64 01 <format>` -- 0 = raw RGB565 (Basic series), 4 = compressed (Intelligent, **OPEN**) |
| 8 | 4 | data offset = 24 |
| 12 | 2+2 | width, height |
| 16 | 4 | data length (format 0: w × h × 2) |
Format 0: RGB565 little-endian, converted by plain truncation (`r>>3, g>>2, b>>3`), stored in the
panel's native scan order -- column by column, each column bottom-to-top:
`offset = 2 * (x * height + (height - 1 - y))`. Verified pixel-exact (480×320 and 64×64, Editor
output byte-identical to ours). **OPEN**: whether the order changes with the project's display
direction (all samples: main.HMI byte 13 = 3).
Format 4 (Intelligent series, **OPEN**): header field at 20 is non-zero for small pictures
(e.g. 2640 for a 3307-byte payload); payload starts with u32 1, u32 height, u32 width (note:
swapped vs. the header, i.e. panel orientation), ... then a block codec: runs of RGB565 colours
followed by small index bytes (e.g. `18c6 38c6 18c6 38c6 2131 1111`), with a variable number of
bytes per 4x4 block, and full 8-bit alpha (a PNG with 256 alpha levels was imported). A 480x320
photo compresses to 215,052 bytes at "Q:100".
Adding a picture = `N.is` + `N.i` + a `i`/`N.i` resource-list entry (kept grouped with the other
`i` entries) -- verified in the Editor.
## 5. Fonts (`N.zi`, format version 6)
Header 44 bytes: magic `04 FF 00 0B`, u16 encoding (3 = iso-8859-1), u8 width, u8 height,
multi-byte range (2 bytes), code range first/last, u32 character count, u8 version = 6,
u8 name length (twice) + 0, u32 length of name+map+glyphs, u32 name offset = 0x2C, 16 unknown
bytes. Then the name, the character map, the glyph data.
Character map: 10 bytes per character: u16 code, u8 glyph width, 2 unknown bytes,
u24 glyph offset (relative to the map start), u16 glyph length.
Glyph: mode byte (0x01 = black/white), then run-length codes over the pixels in the same
column-by-column, bottom-to-top order as pictures (runs continue across columns):
| Code | Meaning |
|---|---|
| `00 0xxxxx` | x transparent |
| `00 1xxxxx` | x ink |
| `01 0xxxxx` | x transparent, 1 ink |
| `01 1xxxxx` | x transparent, 2 ink |
| `10 0xxxxx` | x transparent, 3 ink |
| `10 1xxxxx` | x transparent, 4 ink |
| `11 tttiii` | ttt transparent, iii ink |
The Editor encodes greedily (transparent run + 1..4 ink if possible, else the 3+3-bit form, else a
plain run); our encoder reproduces a 224-glyph Editor font byte for byte. The v3/v5 write-ups in
github.com/hagronnestad/nextion-font-editor were a useful starting point; v6 differs (scan order,
B/W codes `10`/`11`). **OPEN**: anti-aliased glyphs (other mode bytes), multi-byte encodings,
the 16 unknown header bytes.
## 6. Not yet covered
See `docs/NOTES.md`.
+117
View File
@@ -0,0 +1,117 @@
# Status and open points
## Done (verified against the real Editor)
- Container read/write: file table + backup table, table checksum, Editor-style replace
(append + delete), building a fresh compact file from scratch.
- Page checksum, `main.HMI` checksum, table checksum.
- Pages: header, component table, attribute and event-code records -- byte-exact round trip on
every page tested (204 pages in 34 files).
- Decode to a JSON/text folder and encode back; edits made in JSON (text, position, new length)
load correctly in the Editor.
- Component factory (`nxhmi.components`) with the Editor's defaults for **all 31 component types**
(20 Basic + 11 Intelligent-only); `add(page, "button", x=.., txt=.., events=..)`. A page with 7
tool-added components renders correctly in the Editor.
- `main.HMI` resource list and model/series/encoding fields; adding pages (`project.add_page`,
CLI `new-page`) -- the Editor shows the new page with its components.
- Pictures (Basic series): `N.i` and `N.is` decode/encode, byte-identical to the Editor; adding
pictures (`project.add_picture`, CLI `add-picture`) verified in the Editor.
- Fonts (`.zi` v6, black/white): decode/encode byte-identical to the Editor.
- `decode` also writes the original picture files and a text dump of every font.
- Font generation from TrueType (`fonts.from_ttf`, CLI `add-font`): proportional fonts render
correctly in the Editor. Cosmetic OPEN: the Editor's Fonts panel derives the shown name/encoding
from the name string in a way not yet matched (shows "DejaVuSans-(h:24,encode:24asc...").
- CLI: `info verify decode encode set add add-picture add-font kinds new-page dump`.
Full overview of what is covered and missing: [COVERAGE.md](COVERAGE.md).
- Readable JSON values (enum names, `#rrggbb` colours); page renderer pixel-identical to the
Editor for most components ([RENDER.md](RENDER.md)).
## Next steps (in order)
1. Intelligent picture format 4 (block codec with alpha, see FORMAT.md 4 -- first look only); anti-aliased fonts.
3. `.tft` compilation research.
## Open
- `main.HMI`: bytes 8, 13, 36, 0x41; series codes other than Basic (0) and Intelligent (3);
whether the last two checksum tail bytes are fields or constants (only one value ever seen).
- Pictures, picture sources, fonts: carried as raw blobs for now.
- Unknown bytes: page header offsets 21/23, entry bytes 25..27, component-table third word.
- Templates come from Editor 1.68 on NX4832T035 (Basic) and NX4827P043 (Intelligent);
Discovery/Enhanced/Edge series not sampled yet.
## .tft compilation -- first look (2026-11-15), paused for a decision
How to get one: Compile, then File > "TFT file output" > Output (written to
`%AppData%\Nextion Editor\work\<id>\output\`). Compile also leaves `run.run` there (the simulator
build, much smaller -- pictures are stored differently).
Observed in a 740,544-byte TFT of a 6-page NX4832T035 project:
- 0x000-0x0C3: header -- model id (0xB23BC018 at 0x2C), screen size (480/320 at 0x0C), several
sizes/offsets; then FF padding.
- 0x0C4-0x117: a block of 32-bit words that all share the same high bytes (`.. .. AB EB`) --
i.e. XOR-obfuscated with a fixed key. A 4-byte value at 0x18C, then FF up to ~64 KB.
- The rest: project data, plus **Nextion's own binaries embedded verbatim** from the Editor's
install folder: `input.bin` (all of it), `qr0.bin`, `syscom.bin`. `ApplicationRUN.s0` (the
display runtime, 105 KB) was not found in plain form.
Consequences for an open-source compiler:
1. The repo must not ship Nextion's binaries. A compiler would have to read them from the user's
own Editor installation at build time.
2. The XOR-obfuscated parts are a deliberate protection, not just a format. Reproducing them
needs a decision on whether that is acceptable (interoperability research vs. circumvention).
3. Real work beyond that: Nextion script -> bytecode compiler, per-component runtime layout,
pictures/fonts in TFT layout, TFT checksums.
### Second look: minimal projects (one empty page, no pictures/fonts), NX4832T035
Method: build tiny projects with nxhmi that differ in one thing, compile + "TFT file output" via
the Editor, diff. **Compilation is deterministic** (same HMI -> byte-identical TFT).
Layout of a minimal TFT (328,920 bytes):
| Range | Contents |
|---|---|
| 0x00000-0x10090 | header (0x00-0xC3), XOR-obfuscated block (0xC4-0x117), value at 0x18C, FF padding, 144 bytes at 0x10000 |
| 0x10090-0x47F7B | Nextion files, verbatim, in this order: `input.bin`, `asp0.dll`, `cd0.dll`, `qr0.bin`, `syscom.bin`, `h0-0.dll`, `h1-0.dll` (the `.dll` files in the Editor folder are display firmware pieces, not Windows DLLs) |
| 0x47F7B-end-4 | project section: ~32 KB of zeros, then the compiled page(s) (~1 KB for an empty page) |
| last 4 bytes | file checksum |
Header fields (byte offsets, LE): 0x0C u16 480, u16 320, u16 320, u16 480; 0x18 and 0x1E u32
= offset of `cd0.dll`; 0x22 u32 = size of `cd0.dll`; 0x26 u32 = offset of `asp0.dll`; 0x2A u32
= size of `asp0.dll`; 0x2E u32 model id; 0x3C u32 file size; 0x40 u32 0x40000 (0x90000 for the
6-page project); 0x44 u32 hash-like value; 0x58 u32 grows with the project data.
Compiled page (plain, not obfuscated): contains `0,0,480,320,` (page area), event names
(`down`, `up`, `unload`), attribute values in place (page `bco` as u16 LE). Event code is
**tokenized, not compiled to bytecode**: `dim=50` becomes a 1-byte token for `dim` followed by the
literal text `=50`.
Obfuscated block 0xC4-0x117: word 0xC4 is a per-file checksum; words 0xC8..0x113 are a
**layout table XORed with the fixed key 0xEBAB2932** (offsets/sizes/counts -- e.g. the project
section start 0x47F7B twice, a size that grows with the code, page/picture counts). Decoder:
`nxhmi.tft.layout_table`.
Three more per-file values -- 0x44, 0xC4, 0x18C -- do **not** change when only content changes
(page colour, one code character); they depend on layout only (likely header checksums).
File checksum (last 4 bytes, LE): word-per-byte CRC (same family as the page checksum), stream
ending right before the trailer -- proved on two independent one-change pairs. Consequently
**same-length edits can be re-checksummed** (`nxhmi.tft.patch_trailer`, reproduces the Editor's
output byte for byte for a colour change and for `dim=50` -> `dim=51`).
**STUCK (2026-11-15):** start offset / seed of the trailer CRC across files of different lengths.
Tried, all without a fit (three minimal files of different lengths + the 6-page project):
every start offset 0..end with a constant seed (solved exactly by GF(2) linear algebra); seeds
taken from header fields 0x44/0xC4/0x18C (raw, inverted, LE/BE); the header checksum fields
zeroed or 0xFF in every combination; the layout table de-obfuscated before checksumming.
Ideas not yet tried: the stream skipping a region whose size varies (e.g. FF padding after the
page data); a seed derived from file size or layout words; the trailer covering only the
project section in a different order (e.g. pages then the zero area).
Not started: the 3 header checksums, the compiled page format (component records, the token
table for event code), pictures/fonts inside the TFT.
+55
View File
@@ -0,0 +1,55 @@
# Page rendering vs. Nextion Editor
`python -m nxhmi render project.HMI out/` draws every page the way Nextion Editor 1.68 shows it on
its canvas. Verified by capturing the Editor's canvas at 100 % zoom and comparing pixel by pixel
(ignoring the Editor's yellow name tags and its 2-px selection outline).
## Results
The demo project (`demo/demo.HMI`, built by `examples/make_demo.py`):
| Page | Differing pixels | Notes |
|---|---|---|
| home | 94 | all in the two radio buttons and at name-tag edges |
| controls | 5 | name-tag edges |
| gallery | 1 | name-tag edge |
A real 6-page user project (pictures, 32-px bitmap font, texts, 3D buttons, sliders): every page
pixel-identical apart from 0-5 px at name-tag edges.
Per component (dedicated test pages):
| Component | Match | Notes |
|---|---|---|
| text (all xcen/ycen, solid / crop / image background, border, 3D up/down) | 100 % | |
| text with word wrap | 100 % | the text block is aligned as a whole, lines left-aligned in it |
| number (plain, fixed length, hex, currency, negative), xfloat | 100 % | |
| button, dual-state button (colour and picture skins, on/off) | 100 % | "on" with 3D style is drawn pressed (3D down) |
| scrolling text (static) | 100 % | |
| progress bar (horizontal, vertical, picture mode) | 100 % | |
| slider (horizontal, vertical, auto cursor, picture background and cursor) | 100 % | auto cursor = square as thick as the slider; position truncates |
| checkbox (3D down, border, flat) | 100 % | |
| picture, crop (also smaller than the component) | 100 % | only the picture's real area is drawn |
| waveform (frame + grid) | 100 % | horizontal grid lines count from the bottom |
| gauge | 99.3 - 100 % | needle anti-aliasing differs by a few px |
| radio | ~93 - 97 % | circle outline/dot differ by +-1 px at some radii (work in progress) |
| QR code | placeholder only | |
| hotspot, touch cap, timer, variable | nothing drawn (same as the Editor) | |
## Rules learned from the Editor
- Text never starts above/left of its box: centring clamps at 0 (a 32-px font in a 30-px box
starts at the top).
- Text is laid out inside the border: 1 px for 3D styles, `borderw` for style "border".
- 3D colours are fixed: light (230,226,230), dark (65,68,65) -- top/left light for 3D up/auto,
dark for 3D down.
- Buttons with a picture background (`sta` crop or image) get no frame.
- Pictures are pasted at their real size; a smaller picture leaves the rest untouched.
- Checkbox: `bco` fill, `style` frame, checked = `pco` square from w/4 to 3w/4.
- Radio: circle sized by the component *width* (clipped to the height); ring radius
`(w-1)//2`, colour (65,68,65), filled with `bco`; checked = `pco` dot.
- Slider: auto cursor (255) is a square as thick as the slider; position = `int(frac * free)`.
- Waveform: vertical grid lines from the left edge, horizontal ones counted from the bottom.
Not covered yet: exact radio circles, QR codes, Intelligent-only components (need Intelligent
picture format 4), anti-aliased fonts, pressed/runtime states.