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>
This commit is contained in:
mangavalkandClaude Fable 5.2 committed 2026-11-16 18:23:14 +01:00
1 parent f66c902443
commit 99a5240af0
7 files changed
+511 -50

No files matched your search

+2 -2
View File
@@ -113,8 +113,8 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th
| Trailer checksum | solved for any length (`tft.trailer`); one model measured |
| 3 header checksums (0x44, 0xC4, 0x18C) | solved (`tft.header_checksums`, `tft.seal`) |
| Pictures and fonts inside the TFT | solved (FORMAT.md 7.2) |
| Compiled page format | structure solved (code blob, name hashes, RAM image, attribute records, page table, object records -- FORMAT.md 7.3-7.5); per-type tables done for page, hotspot, int variable; the other types need their slot tables and generated draw scripts |
| Event-code tokens | encoding understood (command / system-variable / attribute-reference / number tokens); table being filled |
| Compiled page format | structure solved (code blob, name hashes, RAM image, attribute records, page table, object records -- FORMAT.md 7.3-7.5); per-type tables done for page, hotspot, int variable, timer; the other types need their slot tables and generated draw scripts |
| Event-code tokens | solved for what was sampled (FORMAT.md 7.6): 27 commands, 33 system variables/colours, numbers, global variables, attribute references, if/else/while/for. Not sampled: string functions and attributes, the remaining commands and system variables, `>=` op code |
| Builder (`nxhmi build-tft`) | byte-identical to the Editor for the supported subset (one model: NX4832T035); refuses anything else. **Never tested on a real display** |
| Licensing | every `.tft` embeds Nextion's firmware files; the repo must never ship them -- a builder would read them from the user's own Editor installation |
+45 -10
View File
@@ -394,8 +394,8 @@ 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).
The first eight words describe three tables at 4 + offset: table 0 (4 zero bytes, **OPEN**),
table 1 (global variables, see 7.6; 4 zero bytes without globals) and the page names.
**Name hash** = CRC of the name NUL-padded to 14 bytes. Names are not stored anywhere else.
@@ -406,7 +406,7 @@ tokenised script line; an empty chunk ends a section.
`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.
as a reference to the page's `bco` record).
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>`,
@@ -415,8 +415,8 @@ tokenised script line; an empty chunk ends a section.
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.
(timer: 7.6; slider, touch cap -- **OPEN**); the page's Preinitialize lines; 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).
@@ -430,11 +430,11 @@ 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 |
| 0 | u32 RAM address of the component's data (page: of its second word) |
| 4 | i32 value (constant attributes) or RAM address of the value |
| 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`) |
| 18 | u8 0, u8 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 |
@@ -453,9 +453,44 @@ Object:
| 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 |
| 0x0C | u32 x 4: offset of the first line of the down, up, timer, unload event; FFFFFFFF when the event is empty |
| 0x1C | u32 RAM address 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) |
### 7.6 Script tokens
A script line is stored as text with some parts replaced by binary tokens
(`nxhmi.tft_code`; tables there):
| Token | Meaning |
|---|---|
| `09 ii tt` | a command at the start of a line; `tt` = 04 for names of up to 4 letters, 08 for longer ones, `ii` = index in that table (`page` 0B/04, `print` 04/08 ...). The arguments follow, tokenised like an expression (`printh`: plain text) |
| `04 tt iiii 00` | system variable or colour constant, same two tables (`dim` 0003/04, `WHITE` 0000/08 ...) |
| `05` + u32 | global variable declared in Program.s: its offset in the global RAM (4 bytes each, in declaration order) |
| `01` + u32 | component attribute (`va0.val`, `page0.va0.val`): global attribute record number |
| `03` + i32 | number: hex literals and decimal literals of four or more digits (a leading minus is folded in); shorter decimals stay text |
Operators, commas, quotes, component and page names used as command arguments (`ref m0`,
`page page0`) and the array forms `b[1].x`, `p[0].b[2].val` stay text.
`int a=0,b=5` lines in Program.s produce no chunk: the values go into header table 1 of the code
blob (u32 each, then 4 zero bytes), and one 12-byte descriptor per variable `(CRC of the bare
name, offset, 9)`, sorted by hash, sits between the code blob and the attribute records (layout
word 2 = count, word 3 = offset of the attribute records). All RAM addresses in attribute
records start after this global RAM: address = 4 + 4*globals + offset in the page RAM image.
Control flow becomes jumps; `skip` counts bytes (chunks including their length words) from the
end of the jumping chunk and may be negative:
- `09 00 04 <lhs>,<rhs>,<op>,<03 skip>` -- continue when `lhs op rhs` holds, otherwise jump.
`op`: 1 `==`, 2 `<`, 3 `>`, 4 `<=`, 6 `!=`; 5 `>=` is inferred (**OPEN**).
- `T ` + `03 skip` -- jump always (end of an `if` body that has an `else`; end of a loop body).
- `a&&b`: one test per term, each skipping to the else part. `a||b`: every term but the last is
inverted and skips to the body.
- `for(init;cond;step)` = init line, tests, body, step line, jump back.
Timers: the event section is the label `timer`, a chunk `S ` + `03 1`, the event lines; the
page's init code gets `09 22 08 <en>,<id>,<tim>,0` and `L ` + `03 <offset of the first event line>`.
+16 -3
View File
@@ -152,6 +152,19 @@ Useful facts not obvious from the format description:
- 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.
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.