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>
158 lines
9.4 KiB
Markdown
158 lines
9.4 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`).
|
|
|
|
### 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.
|
|
|
|
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.
|