tft: page section format, pictures/fonts, first builder (nxhmi build-tft)

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>
This commit is contained in:
mangavalkandClaude Fable 5.2 committed 2026-11-16 18:13:11 +01:00
1 parent 7337e693a5
commit f66c902443
10 files changed
+589 -5

No files matched your search

+132
View File
@@ -327,3 +327,135 @@ width of the space glyph.
## 6. Not yet covered
See `docs/NOTES.md`.
## 7. Compiled firmware (`.tft`)
Measured on Editor 1.68.2.3035, model NX4832T035 (Basic series), landscape. Everything below is
reproduced byte for byte by `nxhmi.tft_build` for the supported subset unless marked **OPEN**.
All integers little-endian. "CRC" = the word-per-byte CRC of section 2 with seed 0xFFFFFFFF.
### 7.1 File map
| Range | Contents |
|---|---|
| 0x00000-0x0FFFF | header; unused bytes are FF |
| 0x10000-`base` | resource area, size = u32@0x40, a multiple of 0x10000, zero-padded |
| `base`-end | page section: code blob, attribute records, page table, object records, FF padding to a multiple of 4, trailer |
Header:
| Offset | Field |
|---|---|
| 0x00 | 12 constant bytes `00 01 44 4E 78 45 01 00 4C D3 00 00` (**OPEN**: meaning; probably format/Editor version) |
| 0x0C | u16 width, height, height, width |
| 0x14 | `01 00 00 02` (**OPEN**) |
| 0x18, 0x1E | u32 file offset of `cd0.dll` (twice; u16 0 between) |
| 0x22 | u32 size of `cd0.dll` |
| 0x26, 0x2A | u32 file offset, size of `asp0.dll` |
| 0x2E | u32 model id (as in main.HMI) |
| 0x32 | `21 00 00 00 01 00 0C 00 00 00` (**OPEN**) |
| 0x3C | u32 file size |
| 0x40 | u32 resource area size |
| 0x44 | CRC of the resource area |
| 0x48 | u32 0, 8 x FF, u32 0 |
| 0x58 | u32 size of code blob + attribute records |
| 0xC4 | CRC of `[0x00, 0xC4)` |
| 0xC8 | layout table: 19 u32, each XOR 0xEBAB2932 |
| 0x18C | CRC of `[0xC8, 0x18C)` as stored |
Layout table words: 0, 1, 3 = code blob size; 4 = 0x10000; 5 = `base`; 6 = page table offset;
7 = object records offset; 8 = pictures offset; 12 = fonts offset; 13 = offset of the program
inside the blob; 14 = page count | component count << 16; 15 = picture count; 17 = font count;
18 = 3; the rest 0 (**OPEN**: probably audio/video/gmov resources).
Trailer (last 4 bytes): CRC of everything before it, XOR `(file length & 0xFF) ^ 0x56`.
### 7.2 Resource area
A 0x90-byte directory of 12 entries `(u32 offset from 0x10000, u32 size, u32 0)`, then the data
in the same order: seven files copied verbatim from the Editor's install folder (`input.bin`,
`asp0.dll`, `cd0.dll`, `qr0.bin`, `syscom.bin`, `h0-0.dll`, `h1-0.dll`), all pictures, all fonts;
entries 9-11 are empty.
- Pictures: the 24-byte headers of all `N.i` entries first, then their pixel data. In each
header, u32@4 = picture number and u32@8 = offset of its data from the start of the picture
block. (One picture: identical to the `.i` entry.)
- Fonts: the 44-byte headers of all `N.zi` entries first, then the rest of each font; u32@0x18
of a header = offset of that font's data from the start of the font block.
### 7.3 Code blob
Offsets in this section are relative to `base`.
```
u32 0x24 + 6*pages, u32 3, u32 0x1C, u32 4, u32 0x20, u32 4, u32 0x24, u32 6*pages, u32 0, u32 0
page names: (u32 name hash, u16 page number), sorted by hash
program
per page: code blocks of its components, name list, RAM image, init code
```
The first ten words describe three tables at 4 + (0x1C, 0x20, 0x24) with sizes 4, 4, 6*pages;
the first two are empty when the program declares no global variables (**OPEN**: their format).
**Name hash** = CRC of the name NUL-padded to 14 bytes. Names are not stored anywhere else.
Everything after the page names is a sequence of **chunks**: `u32 length` + bytes. A chunk is one
tokenised script line; an empty chunk ends a section.
- Program: one chunk per `Program.s` statement (comments and blank lines dropped), then a chunk
`page 0` added by the Editor, then the empty chunk.
- Component block (the page itself is component 0):
- draw section -- lines, empty chunk. Page: `fill x,y,w,h,<bco>` (command `09 0D 04`, colour
as a reference to the page's `bco` record), then the Preinitialize event lines.
Types that draw themselves (progress bar, gauge, QR code, text ...) have their own script
here, generated from the attributes (**OPEN** per type).
- erase section (types with a rectangle only; empty for the page) -- `fill x,y,w,h,<page bco>`,
empty chunk.
- events: a label chunk (`down`, `up`, `unload`, `timer`, `slide` -- plain text), the event's
lines, empty chunk. Page: down, up, unload. Hotspot: down, up. Variable: none.
- After the last component of a page: one chunk with the name list `(u32 hash, u16 id)` sorted
by hash; one chunk with the RAM image followed by 8 zero bytes; type-specific init lines
(timer, slider, touch cap -- **OPEN**); the chunk `09 21 08`; the page's Postinitialize lines;
empty chunk.
RAM image: 8 x FF, then every RAM-stored attribute of every component in component order,
each aligned to its size, each component padded to 4. For a page: `sta` (u8), pad, `bco` (u16).
### 7.4 Attribute records (24 bytes)
Every component owns a fixed number of record slots (page 33, hotspot 27, variable 11,
timer 11, touch cap 10, progress bar 33, slider 40, gauge 41, QR code 33 ...); unused slots are
all zero. Record numbers are global (pages concatenated) in script references and page-relative
in the object records.
| Offset | Field |
|---|---|
| 0 | u32 8 for a page, 16 for other components |
| 4 | i32 value (constant attributes) or 4 + offset into the RAM image |
| 8, 12 | i32 maximum, minimum |
| 16 | u8 page number, u8 component id of the component to redraw on change; FF FF = none |
| 18 | u16 change action (0 = none; timers use 1 for `tim`, 2 for `en`) |
| 20 | u8 kind: 0x01 constant; 0x0B/0x0C/0x0D/0x0E x/y/w/h; 0x08 endx/endy; 0x21, 0x22, 0x31, 0x32, 0x39, 0x3F RAM-stored |
| 21 | u8 size in bytes |
| 22 | u16 0 |
Slots seen in all types: 0 `type`, 1 `id`, 3 `vscope`, 9-14 `x y w h endx endy`.
### 7.5 Page table (16 bytes per page) and object records (232 bytes per component)
Page: u16 first object number, u16 component count, u32 offset of the name-list chunk, u32
offset of the page's first attribute record (from `base`), u32 RAM image size.
Object:
| Offset | Field |
|---|---|
| 0 | u8 type, u8 id, u8 0, u8 flags (0x37 visible types, 0x27 timer/touch cap, 0x07 variable) |
| 4 | u32 offset of the draw section, FFFFFFFF if empty |
| 8 | u32 offset of the erase section, FFFFFFFF if none/empty |
| 0x0C-0x1B | more code offsets (0x14: timer event), FF when unused |
| 0x1C | u32 8 / 16 as in the records |
| 0x20 | `00 00 7F 00`, u32 0 |
| 0x28 | u16 x, y, w, h, endx, endy (0,0,1,1,0,0 for invisible types) |
| 0x34 | u32 offset of the component's code block |
| 0x38 | 88 x u16: record number (page-relative) of well-known attributes, FFFF = absent. Positions: 1 vscope, 2 sta, 4 bco, 16 pco, 20 val, 42 x, 43 y, 44 endx, 45 endy, 46 w, 47 h, 49 id, 62 type (**OPEN**: the others) |