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>
9.4 KiB
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.HMIchecksum, 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.HMIresource list and model/series/encoding fields; adding pages (project.add_page, CLInew-page) -- the Editor shows the new page with its components.- Pictures (Basic series):
N.iandN.isdecode/encode, byte-identical to the Editor; adding pictures (project.add_picture, CLIadd-picture) verified in the Editor. - Fonts (
.ziv6, black/white): decode/encode byte-identical to the Editor. decodealso writes the original picture files and a text dump of every font.- Font generation from TrueType (
fonts.from_ttf, CLIadd-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.
- Readable JSON values (enum names,
#rrggbbcolours); page renderer pixel-identical to the Editor for most components (RENDER.md).
Next steps (in order)
- Intelligent picture format 4 (block codec with alpha, see FORMAT.md 4 -- first look only); anti-aliased fonts.
.tftcompilation 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:
- 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.
- 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).
- 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).
All four checksums solved (2026-11-16)
All are the word-per-byte CRC with seed 0xFFFFFFFF (nxhmi.tft.header_checksums, trailer,
seal); verified on every sample (two layouts, 0x40000 and 0x90000 resource areas):
| Where | Covers |
|---|---|
| 0x44 | the resource area [0x10000, 0x10000 + u32@0x40) -- firmware files, pictures, fonts. Constant for all picture-less projects of one model, which is why it looked "layout only" |
| 0xC4 | header [0x00, 0xC4) (includes 0x44) |
| 0x18C | [0xC8, 0x18C): the layout table as stored (XORed) and the FF padding after it |
| last 4 bytes | the whole file before the trailer, then XOR (file length & 0xFF) ^ 0x56 |
Why the trailer resisted: the stream and seed were the obvious ones all along, but the result
is XORed with a byte that depends on the file length, so every "constant seed" search failed.
What cracked it: compute, per file, the seed that a from-offset-0 CRC would need (run the CRC
backwards from the trailer). Files of equal length needed the same seed even with different
headers -> the header is in the stream as-is and only the length matters; then
trailer ^ CRC(file) turned out to be a single byte, len & 0xFF ^ 0x56, on all eight lengths
seen (low bytes D8 E0 E4 E8 EC F0 00 C0). OPEN: whether 0x56 is model-specific (only
NX4832T035 measured), and whether more than the low length byte takes part.
The file length is always a multiple of 4 (the page section is padded with zeros).
Other dead ends, for the record: seeds from header fields; header checksum fields zeroed/0xFF in every combination; the layout table de-obfuscated before checksumming; prefixes built from length/layout words; runs of 00/FF bytes before the file.
Page section solved, first builder (2026-11-16)
Format: FORMAT.md section 7. nxhmi build-tft reproduces the Editor byte for byte for projects
made of pages (solid colour), hotspots and int variables, with any pictures and fonts, on
NX4832T035. Check with NXHMI_TFT_SAMPLES=<folder of name.HMI + name.tft> python -m unittest discover -s tests -p test_tft_build.py (samples stay outside the repo).
How the samples are made: one tiny project per question (nxhmi builds them), compiled in the
Editor by a click script (open file, Compile, File > TFT file output > Output), ~45 s each.
A project whose script does not compile yields no TFT -- e.g. sys0 is only known when
Program.s declares it (int sys0=0,sys1=0,sys2=0, as in the Editor's default program).
Useful facts not obvious from the format description:
- Text-like components need a font in the project or the compile fails.
- Every component type brings its own generated script (draw section, init lines); e.g. a
progress bar's draw section is three
fill-like lines computed from x/y/w/h andval. These must be collected per type -- the bulk of the remaining work. - Record references in scripts (
01+ u32) are global record numbers, so adding a component renumbers every reference after it.
Not done: script tokens beyond baud=115200 / page N; timers, sliders and every drawing
component; global variables declared in Program.s (blob header tables 0 and 1); other models,
portrait, other series; and nothing has been loaded onto a display.