Files
openhmi-nx/docs/NOTES.md
T
mangavalkandClaude Fable 5.2 99a5240af0 tft: script tokens, global variables, timers, control flow
build-tft now reproduces 35 Editor-made samples byte for byte: assignments,
arithmetic, 27 commands, system variables and colours, attribute references,
Program.s globals, all page/hotspot/timer events, if/else/while/for.

Co-Authored-By: Claude Fable 5.2 <noreply@anthropic.com>
2026-11-16 18:23:14 +01:00

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

  • Readable JSON values (enum names, #rrggbb colours); page renderer pixel-identical to the Editor for most components (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.
  2. .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).

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 and val. 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.

Script (same day): tokens, global variables, timers and control flow are in (FORMAT.md 7.6, nxhmi.tft_code); 35 Editor-made samples are reproduced byte for byte. Things to know:

  • A token table entry exists only for names that were compiled once. To add names: put them in a project, compile, read the token from the chunk (the analysis was a 30-line script printing source line next to chunk).
  • >= was never the plain operator in a sample (only as the inverse of < in an ||); its code 5 is the gap in 1..6. Verify before relying on it.
  • Unverified and therefore refused: negative global initial values, x-1000 (binary minus before a long number), mixed &&/||, parentheses in conditions, braces-less if.
  • The Editor appends one page 0 chunk to the program even when Program.s already ends with it.

Not done: sliders, touch cap and every drawing component (text, number, button, progress bar, gauge, waveform, picture, crop, checkbox, radio, QR code ...); string variables and string functions; page backgrounds other than a solid colour; global (vscope) components; other models, portrait, other series; and nothing has been loaded onto a display.