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:
commit
69e22cfb06
70 files changed
+25058
No files matched your search
@@ -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
@@ -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
@@ -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.
|
||||
@@ -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.
|
||||
Reference in new issue
Block a user