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>
497 lines
26 KiB
Markdown
497 lines
26 KiB
Markdown
# The Nextion Editor `.HMI` project format
|
||
|
||
Verified against **Nextion Editor 1.68.2 (build 1.68.2.3035)**. Reverse-engineered black-box: by editing projects in Nextion Editor, saving, and comparing
|
||
files, and by asking the Editor whether hand-made files load ("oracle" tests). The Editor itself was
|
||
never decompiled or decrypted. Everything here was checked against real files; open points are
|
||
marked **OPEN**.
|
||
|
||
All integers are little-endian.
|
||
|
||
## 1. Container
|
||
|
||
An `.HMI` file is a tiny file system.
|
||
|
||
| Offset | Contents |
|
||
|---|---|
|
||
| `0x000000` | file table: `count` (u32), `count` × 28-byte entries, then the table checksum (u32) |
|
||
| `0x080000` | backup copy of the file table (byte-identical, incl. checksum) |
|
||
| `0x380000` | u32 `0xFFFFFFFF` |
|
||
| `0x6FFFF8` | ASCII `ver21234` |
|
||
| `0x700000` | entry data, packed back to back |
|
||
|
||
The space between these areas is normally zero (older files can contain stale data, e.g. at
|
||
`0x100000`, which is ignored).
|
||
|
||
### File table entry (28 bytes)
|
||
|
||
| Offset | Size | Field |
|
||
|---|---|---|
|
||
| 0 | 16 | name, NUL padded (`main.HMI`, `Program.s`, `0.pa`, `0.i`, `0.is`, `0.zi`, ...) |
|
||
| 16 | 4 | start offset in the file |
|
||
| 20 | 4 | size |
|
||
| 24 | 1 | deleted flag |
|
||
| 25 | 3 | unknown (looks like uninitialised memory; **is** covered by the table checksum) |
|
||
|
||
When the Editor replaces an entry it appends the new data to the end of the file, adds a new
|
||
entry, and marks the old entry deleted: deleted flag = 1 **and first byte of the name = 0**
|
||
(e.g. `\0ain.HMI`). The Editor finds entries by name, so setting only the flag is not enough.
|
||
Deleted entries stay in the table and their data stays in the file.
|
||
|
||
If the primary table's checksum fails the Editor silently uses the backup table. If both fail it
|
||
reports "Version mismatch". The Editor also rewrites a file when opening it (it repairs the
|
||
primary table from the backup, among other things) -- never reuse a test file after opening it.
|
||
|
||
### Entry names
|
||
|
||
| Name | Contents |
|
||
|---|---|
|
||
| `main.HMI` | project header (display model, resource list) -- 224 bytes |
|
||
| `Program.s` | start-up script, plain text (no checksum) |
|
||
| `N.pa` | page N |
|
||
| `N.i` | picture N as the display uses it (section 4) |
|
||
| `N.is` | picture N's original source file (section 4) |
|
||
| `N.zi` | font N (section 5) |
|
||
|
||
### `main.HMI` (project header)
|
||
|
||
| Offset | Size | Field |
|
||
|---|---|---|
|
||
| 0 | 4 | checksum (section 2) |
|
||
| 4 | 4 | header size = 0x60 = start of the resource list |
|
||
| 8 | 1 | 1 (**OPEN**) |
|
||
| 9 | 1 | 0x41 in a 2019 file, 0x44 after saving with Editor 1.68 (Editor/format revision?) |
|
||
| 10 | 1 | 0x21 |
|
||
| 11 | 1 | display series: 0 = Basic (T), 1 = Enhanced (K), 3 = Intelligent (P), 6 = Edge (E), 100 = Discovery (F) |
|
||
| 12 | 1 | display direction in 90° steps (Setting > Display: 0 = 0°, 1 = 90°, 2 = 180°, 3 = 270°). Basic panels are portrait at 0°, so a 480×320 Basic project has 1; Intelligent panels are landscape at 0°. Page sizes follow (the Editor shows a 480×272 Intelligent project with 1 as 272×480). An unsupported value made the Editor fail to load ("'null' is not a supported encoding name") |
|
||
| 13 | 1 | character encoding (Setting > Display): 1 ascii, 2 gb2312, 3 iso-8859-1, 4-11 iso-8859-2..9, 12 iso-8859-13, 13 iso-8859-15, 14 iso-8859-11, 15 ks_c_5601-1987, 16 big5, 17-20 windows-1255..1258, 21 windows-874, 22 koi8-r, 23 shift-jis, 24 utf-8 (all measured; `models.ENCODINGS`) |
|
||
| 14 | 1 | 0x4F |
|
||
| 16 | 4 | model id (e.g. 0xB23BC018 NX4832T035_011, 0x181169DA NX4827P043_011); must match the series byte, otherwise the Editor falls back to its first model |
|
||
| 24 | 4 | 0x60 |
|
||
| 28 | 4 | resource count |
|
||
| 36 | 4 | 1 or 2 (**OPEN**) |
|
||
| 0x41 | 1 | 3 after switching to an Intelligent model (**OPEN**) |
|
||
| 0x60 | 16 × count | resource list: type[8] + name[8], e.g. `pa`/`3.pa`, `i`/`0.i`, `zi`/`0.zi` |
|
||
|
||
Adding a page = new `N.pa` entry + one resource-list entry + count + 1 + new checksum (verified:
|
||
the Editor shows pages added this way). `.is` entries are not listed.
|
||
|
||
## 2. Checksums
|
||
|
||
All three use CRC-32 with polynomial `0x04C11DB7`, MSB-first (not reflected), initial value
|
||
`0xFFFFFFFF`, no final XOR -- the algorithm of the STM32 hardware CRC unit. They differ in how
|
||
input is fed.
|
||
|
||
### Page checksum (first 4 bytes of every `N.pa`)
|
||
|
||
Every input **byte** is zero-extended to a 32-bit word and fed as one word. Input:
|
||
|
||
```
|
||
page[4:] # whole page after the checksum field
|
||
+ datasize (4 bytes, LE) # = page header offset 4
|
||
+ numberobj (4 bytes, LE) # = page header offset 12
|
||
+ page[20] + page[21] # header bytes 20 and 21
|
||
```
|
||
|
||
Evidence: two saves differing in one bit place that bit's influence at `x^(32·k)` -- adjacent file
|
||
bytes are exactly 32 bits apart in the CRC stream; a fixed 10-word tail appears after the page;
|
||
the tail contents were solved over pages of different lengths and component counts; then
|
||
verified on 276 Editor-written pages (including a 2019 file) and by the Editor accepting pages
|
||
built from scratch.
|
||
|
||
### `main.HMI` checksum (first 4 bytes)
|
||
|
||
Same word-per-byte scheme. Input: `main[4:] + main[16:20] + main[4:8] + main[10] + main[14]`.
|
||
**OPEN**: the last two tail bytes were 0x21, 0x4F in every sample; they may be constants (they equal
|
||
the page header's "version" bytes) rather than fields.
|
||
|
||
### File table checksum (u32 right after the last entry)
|
||
|
||
Input read as **little-endian 32-bit words**: the table from `count` through the last entry, then
|
||
the constant word `0x43454441` (ASCII "ADEC").
|
||
|
||
## 3. Pages (`N.pa`)
|
||
|
||
### Header (56 bytes)
|
||
|
||
| Offset | Size | Field |
|
||
|---|---|---|
|
||
| 0 | 4 | checksum (above) |
|
||
| 4 | 4 | datasize = total page length |
|
||
| 8 | 4 | infoaddr = 56 (start of component table) |
|
||
| 12 | 4 | numberobj = component count |
|
||
| 16 | 4 | password |
|
||
| 20 | 1 | locked |
|
||
| 21 | 1 | 0x4F in every file seen (**OPEN**) |
|
||
| 22 | 1 | 0x21 (33) in every file seen -- format version? |
|
||
| 23 | 1 | 0 (**OPEN**) |
|
||
| 24 | 16 | page name |
|
||
| 40 | 16 | reserved (zero) |
|
||
|
||
### Component table
|
||
|
||
`numberobj` entries of `(u32 offset, u32 size, u32 unknown=0)`. Offset is relative to byte 56.
|
||
The page itself is component 0.
|
||
|
||
### Component data
|
||
|
||
A sequence of records `u32 length + bytes`, ending with an empty record. Records are grouped:
|
||
a header record `"<group>-<n>"` is followed by n records.
|
||
|
||
* `att-<n>`: attributes. Each record = 16-byte NUL-padded name + value. Integers are unsigned
|
||
LE of 1, 2 or 4 bytes (`val` has a different width per component type); `objname`, `txt`
|
||
(and other text attributes) are raw text in the project encoding (iso-8859-1 by default).
|
||
* `codes<event>-<n>`: event code, one record per line. Seen: `codesload` (preinitialize),
|
||
`codesloadend` (postinitialize), `codesdown` (touch press), `codesup` (touch release),
|
||
`codesunload` (page exit), `codestimer`, `codesslide` (slider move).
|
||
|
||
Attribute names seen so far: `aph bco bco1 bco2 borderc borderw ch dis disup down drag effect en
|
||
endx endy first font format groupid0 groupid1 h hig id isbr key left lenth lockobj maxval minval
|
||
mode movex movey objname pco pco2 pic pic1 pic2 picc picc1 picc2 psta pw right sendkey spax spay
|
||
sta style tim time txt txt_maxl type up val vscope w wid x xcen y ycen`.
|
||
|
||
Text attributes are `objname` and every attribute that has a length-limit companion in the same
|
||
component (`txt`/`txt_maxl`, `path`/`path_m`, `dir`/`dir_m`, `filter`/`filter_m`,
|
||
`format`/`format_m`, `vvs2`/`vvs2_m`). The same name can be a number elsewhere (`dir` is a u8 on
|
||
scrolling text, `format` a u8 on number).
|
||
|
||
Component `type` values (all placed in Editor 1.68; full default attribute lists in
|
||
`src/nxhmi/templates_*.json`):
|
||
|
||
| type | component | | type | component |
|
||
|---|---|---|---|---|
|
||
| 0 | waveform | | 59 | xfloat |
|
||
| 1 | slider | | 60 | ExPicture * |
|
||
| 2 | Gmov * | | 61 | ComboBox * |
|
||
| 3 | Video * | | 62 | SLText * |
|
||
| 4 | Audio * | | 63 | FileStream * |
|
||
| 5 | TouchCap | | 65 | FileBrowser * |
|
||
| 51 | timer | | 66 | DataRecord * |
|
||
| 52 | variable | | 67 | Switch * |
|
||
| 53 | dual-state button | | 68 | TextSelect * |
|
||
| 54 | number | | 98 | button |
|
||
| 55 | scrolling text | | 106 | progress bar |
|
||
| 56 | checkbox | | 109 | hotspot |
|
||
| 57 | radio | | 112 | picture |
|
||
| 58 | QRcode | | 113 | crop |
|
||
| 116 | text | | 121 | page |
|
||
| 122 | gauge | | | |
|
||
|
||
\* Intelligent series only. Attribute sets of shared types are identical on Basic and Intelligent
|
||
projects. `sta` on pages/texts: 1 = solid colour, 2 = picture.
|
||
|
||
## 4. Pictures
|
||
|
||
`N.is` = 27-byte header + the original image file, untouched (verified byte-identical with the
|
||
PNG that was imported):
|
||
|
||
| Offset | Size | Field |
|
||
|---|---|---|
|
||
| 0 | 4 | `0A 64 01 01` |
|
||
| 8 | 4 | data offset = 27 |
|
||
| 12 | 2+2 | width, height |
|
||
| 16 | 4 | length of the embedded file |
|
||
| 24 | 3 | file type, e.g. `png` |
|
||
|
||
`N.i` = 24-byte header + pixels:
|
||
|
||
| Offset | Size | Field |
|
||
|---|---|---|
|
||
| 0 | 4 | `0A+direction, quality, 01, <format>` -- 0 = raw RGB565 (Basic, Enhanced), 3 = raw with a 20-byte zero header (Discovery), 4 = run-length or JPEG (Intelligent, Edge) |
|
||
| 8 | 4 | data offset = 24 |
|
||
| 12 | 2+2 | width, height |
|
||
| 16 | 4 | data length (format 0: w × h × 2) |
|
||
|
||
Format 0: RGB565 little-endian, converted by plain truncation (`r>>3, g>>2, b>>3`), stored in the
|
||
panel's native scan order -- column by column, each column bottom-to-top:
|
||
`offset = 2 * (x * height + (height - 1 - y))`. Verified pixel-exact (480×320 and 64×64, Editor
|
||
output byte-identical to ours). The order follows the display direction, see format 4.
|
||
|
||
Per series (measured by letting Editor 1.68 convert our pictures/fonts in each series):
|
||
|
||
| Series | Picture format | Stored direction (pictures and fonts) | Font glyph data |
|
||
|---|---|---|---|
|
||
| Basic, Enhanced | 0 | project direction | unpadded |
|
||
| Intelligent | 4 | project direction | 8-byte aligned |
|
||
| Edge | 4 (same encoder, same rules, also the JPEG variant for quality < 100) | project direction | unpadded (accepted as is) |
|
||
| Discovery | 3: 20 zero bytes, then raw RGB565 | always 0 (row by row), whatever the project direction | 8-byte aligned |
|
||
|
||
Discovery, Enhanced and Edge offer the 20 Basic component types (the Intelligent-only ones are
|
||
greyed out) with exactly the Basic default attributes; Enhanced and Edge draw like Basic on the
|
||
canvas (3D frame order, colours).
|
||
|
||
Format 4 (Intelligent series) -- decoded and re-encoded byte-identically (28 Editor samples, all
|
||
four directions, with and without alpha):
|
||
|
||
- Header as above; byte 0 = 0x0A + display direction (also for format 0: a landscape Basic
|
||
project, direction 1, writes 0x0B); +16 data length; +20 offset of the alpha section within the
|
||
data (0 = opaque picture).
|
||
- Pixel order: the picture rotated by the display direction (`pictures.stored_order`): 0 = row
|
||
by row, 1 = column by column bottom to top (same as format 0 on Basic), 2 = 180°, 3 = columns
|
||
from the right, top down.
|
||
- Data: u32 1, u32 stored width, u32 stored height (swapped for directions 1/3), u32 0, u32 0,
|
||
then blocks. A block is a u32 control word of eight 4-bit ops (low nibble first):
|
||
- `1`..`13`: run of that many pixels in the colour of the op's slot (slot = nibble index);
|
||
- `14`: run of N pixels, N in the next three nibbles (12 bits), colour of the op's slot;
|
||
- `15`: N literal pixels (N in the next three nibbles); their colours follow the control
|
||
word and end the block;
|
||
- `0`: nothing.
|
||
|
||
Run blocks carry 8 colour slots (RGB565 LE) after the control word; the last block is padded
|
||
with zero slots to 8.
|
||
- How the Editor encodes: split the pixels into runs of one colour of at most 13; pack 8 runs
|
||
per block; a block of eight 13-runs of one colour becomes op 14 (consecutive such blocks merge,
|
||
N = 104 × blocks, at most 39). Busy stretches become literal pixels: when the next block would
|
||
have at least 7 runs covering at most 10 pixels (and 8+ pixels are left), the next **8 pixels**
|
||
go into a literal block, and this repeats (merging) while the condition holds (12 designed run
|
||
patterns, plus the 28 samples).
|
||
- Alpha section: 7-bit alpha (`a * 127 // 255`) per pixel in storage order, run-length coded --
|
||
a byte with bit 7 set is one pixel of alpha `b & 0x7F`, otherwise `b` is the alpha and the next
|
||
byte the run length (≤ 255). Fully transparent pixels store colour 0.
|
||
- Pictures of 1-2 pixels stay format 0 (seen: 1x1, 2x1, 1x2; 8x1 is converted); nxhmi does the
|
||
same. The Editor shows a message box per picture while converting format-0 pictures it finds
|
||
in an Intelligent project.
|
||
- Compressed quality (picture list right-click > "Compressed quality setting", 1-99; shown as
|
||
"Q:nn"): header byte 1 = quality (100 = 0x64 for the run-length variant). Data: u32 **0**
|
||
(JPEG), u32 width and height padded up to multiples of 16, u32 0, u32 0, then a baseline JPEG
|
||
of the padded picture (black padding at the right/bottom, *then* rotated into stored order),
|
||
4:2:0, 96 dpi JFIF -- byte-identical to libjpeg (Pillow) at that quality for opaque pictures
|
||
(18/18 samples: qualities 1/30/50/99, landscape and portrait). Then, if the picture has alpha,
|
||
the same alpha run section, covering the *padded* picture (padding alpha 0), at the offset in
|
||
header +20. With alpha the Editor first passes the colours through premultiplied alpha; nxhmi
|
||
approximates that step (JPEG a few levels off in some pixels; alpha section identical). The
|
||
simulator decodes the JPEG like libjpeg (opaque pictures render pixel-exact); transparent ones
|
||
blend within 1 level.
|
||
|
||
Adding a picture = `N.is` + `N.i` + a `i`/`N.i` resource-list entry (kept grouped with the other
|
||
`i` entries) -- verified in the Editor.
|
||
|
||
## 5. Fonts (`N.zi`, format version 6)
|
||
|
||
Header 44 bytes: magic `04 FF 00` + `0x0A + display direction` (like pictures), u16 encoding (3 = iso-8859-1), u8 width, u8 height,
|
||
multi-byte range (2 bytes), code range first/last, u32 character count, u8 version = 6,
|
||
u8 name length (twice) + 0, u32 length of name+map+glyphs, u32 name offset = 0x2C, 16 unknown
|
||
bytes. Then the name, the character map, the glyph data.
|
||
|
||
Header byte 0x1E = 1 when the Font Creator's "Anti-aliasing of fonts" box was ticked. Such fonts
|
||
still hold 1-bit glyphs (Windows' thinner anti-aliased outline, thresholded); the Intelligent
|
||
simulator draws them with two colours only. Byte 18 (second name length) is 0 in fresh Font
|
||
Creator output and the name length after a re-save; both load.
|
||
|
||
Character map: 10 bytes per character: u16 code, u8 glyph advance width, u8 extra columns on the
|
||
left, u8 extra columns on the right (glyphs that overhang, e.g. `j`, `f`, `W`; the stored glyph is
|
||
advance + left + right wide and drawn starting `left` px before the pen position),
|
||
u24 glyph offset (relative to the map start), u16 glyph length. In Intelligent projects the glyph
|
||
data starts at a multiple of 8 from the map start (zero padding after the map); Basic fonts have no padding.
|
||
|
||
Glyph: mode byte (0x01 = black/white), then run-length codes over the pixels in the same order
|
||
as pictures for the project's display direction (runs continue across rows/columns): at 90° column
|
||
by column, bottom to top; at 0° row by row. When an Intelligent project is compiled, the Editor
|
||
converts a 90° font to the project direction; our encoder reproduces that conversion byte for byte.
|
||
|
||
| Code | Meaning |
|
||
|---|---|
|
||
| `00 0xxxxx` | x transparent |
|
||
| `00 1xxxxx` | x ink |
|
||
| `01 0xxxxx` | x transparent, 1 ink |
|
||
| `01 1xxxxx` | x transparent, 2 ink |
|
||
| `10 0xxxxx` | x transparent, 3 ink |
|
||
| `10 1xxxxx` | x transparent, 4 ink |
|
||
| `11 tttiii` | ttt transparent, iii ink |
|
||
|
||
The Editor encodes greedily (transparent run + 1..4 ink if possible, else the 3+3-bit form, else a
|
||
plain run); our encoder reproduces a 224-glyph Editor font byte for byte. The v3/v5 write-ups in
|
||
github.com/hagronnestad/nextion-font-editor were a useful starting point; v6 differs (scan order,
|
||
B/W codes `10`/`11`). **OPEN**: the remaining unknown header bytes (0x1F, 0x20).
|
||
|
||
Multi-byte fonts (Font Creator "Specified character" range; verified for GB2312, Big5, Shift-JIS,
|
||
KS C 5601 and UTF-8, round-trip byte-identical, rendered pixel-exact in the simulator):
|
||
|
||
| Header | Meaning | GB2312 | Big5 | Shift-JIS | KS C 5601 | UTF-8 |
|
||
|---|---|---|---|---|---|---|
|
||
| 1, 2 | end of the first trail-byte range, trail codes skipped after it | FF 00 | 7E 22 | 7E 01 | FF 00 | FF 00 |
|
||
| 4 | encoding (main.HMI numbering) | 2 | 16 | 23 | 15 | 24 |
|
||
| 5 | 2 = multi-byte (0 for single-byte fonts) | 2 | 2 | 2 | 2 | 2 |
|
||
| 6 | width (0 for multi-byte) | 0 | 0 | 0 | 0 | 0 |
|
||
| 8, 9 | lead-byte range | A1 F7 | A0 F9 | 81 EF | A1 C8 | FF FF |
|
||
| 10, 11 | trail-byte range | A1 FE | 40 FE | 40 FC | A1 FE | 00 FF |
|
||
| 0x1C, 0x1D | end of the first lead range, lead codes skipped | FF 00 | FF 00 | 9F 40 | FF 00 | FF 00 |
|
||
| 0x20 | ? | 4 | 5 | 5 | 4 | 5 |
|
||
|
||
Map codes: double-byte encodings store the character's two bytes as a little-endian u16 (GB2312
|
||
中 = bytes D6 D0 -> 0xD0D6); UTF-8 fonts store the Unicode code point. The map is sorted by
|
||
code. The display splits text into characters by taking every byte >= 0x81 together with the
|
||
next byte (not limited to header 8-9: KS C hanja leads above C8 still pair; Shift-JIS half-width
|
||
katakana pair up as well, so they cannot be shown); a character without a glyph advances by the
|
||
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 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.
|
||
|
||
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).
|
||
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: 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).
|
||
|
||
### 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 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 | 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 |
|
||
|
||
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 | 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>`.
|