Files
openhmi-nx/docs/NOTES.md
T
mangavalkandClaude Opus 5.5 69e22cfb06 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>
2026-11-15 15:11:02 +01:00

118 lines
7.0 KiB
Markdown

# 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.