Files
openhmi-nx/docs/NOTES.md
T

234 lines
15 KiB
Markdown
Raw Normal View History

# 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.
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.
Added later the same day: touch cap and plain text (55 samples reproduced).
Not done: sliders and the other drawing components (number, button, progress bar, gauge,
waveform, picture, crop, checkbox, radio, QR code ...); text with a border, picture or crop
background; string attributes in script (`t0.txt="x"`), 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.
Samples: `tools/make_tft_samples.py` writes the 63 study projects (`tools/tft_samples.json`);
45 are reproduced, the other 18 are one-component projects of the types still to do (their
Editor output is needed again if the scratch copies are gone: ~45 s of Editor time each).
Starting points for the next component types (from those samples, not yet in the builder):
- Record slots after 14 follow the type's own attribute list; the RAM order is not the slot
order (text: font, isbr, pco, bco, xcen, ycen, pw, then txt with `txt_maxl + 1` bytes).
Kinds seen: 0x21/0x31 u8, 0x22/0x32 u16, 0x39 i32, 0x3F string (size = bytes reserved),
0x02 `txt_maxl`.
- Text draw section (implemented): `09 1C 08 x,y,w,h,<font>,<pco>,<bco>,<xcen>,<ycen>,1,<isbr>,0,0,<pw>,0`
then `09 13 04` with four `03 7FFF` numbers and `<txt>`; every `<..>` is a record reference,
so changing an attribute at run time needs no recompilation. The literal 1 and 0s are
probably sta, spax, spay and the border -- untested, so other values are refused. The `font`
record's maximum is the number of fonts - 1.
- Number looks like text but keeps `sta` and `style` in RAM (plus three unexplained bytes) and
draws with `09 1C 08` + `09 11 04 <val>,<lenth>,<format>`. Button (default 3D style) has a
long generated script with conditional jumps on `val`.
- Progress bar draw section: `<sys 0005/04>=<val>*w/100`, then two fills (`09 0D 04`) for the
filled and the empty part. Gauge: one `09 0A 08` line. QR code: one `09 08 08` line.
- Slider and touch cap add the init line `09 16 04 1`; slider has a `slide` event label.
- Object flag byte: 0x37 types with a rectangle, 0x27 timer and touch cap, 0x07 variable.
### Look inside the Editor (2026-11-17, allowed by the owner, read-only)
Result: almost nothing, and nothing from it is in the repo.
- `Nextion Editor.exe` is a small .NET loader; the real program (and with it the compiler and
the per-component script templates) is `ACTR.dll`, which is encrypted and was left alone.
- `en0_com.bin` / `en0_va.bin` are the Editor's help texts for commands and system variables
(plain text behind a one-byte XOR). They give the complete list of names (64 commands, 75
variables and constants) but not the token numbers: the order in the file is not the token
order. **Fact from the inspection:** only this list of names, used to decide what to put in
sample projects. Every token number in `tft_code.py` was read from compiled samples.
### Slot rule and the generic builder (2026-11-17)
Found by comparing samples, not from the Editor: a component's record slots follow the
attributes the Editor *shows* for it, in order. Components with a rectangle: 19 common slots
(type, id, objname, vscope, drag, sendkey, aph, movex, movey, x, y, w, h, endx, endy, effect,
first, time, lockobj), then one slot per visible attribute, then 8 empty ones. Components
without (variable, timer, touch cap): 7, the visible attributes, 2 empty. Hidden attributes
get no slot -- e.g. `style` disappears when `sta` is not "solid color", `borderc`/`borderw`
exist only for style "border" -- so every later slot moves.
The generated scripts are ordinary Nextion script compiled by the same compiler as event code
(`if(val==1) {...} else {...}` in a button becomes the usual test/jump chunks), with constant
attributes written as literals and RAM attributes as record references. `nxhmi.tft_types`
therefore describes a type as: visible attributes, record kinds, RAM order, script templates.
The RAM order and the unnamed drawing commands still have to be read from samples per type.
State on 2026-11-17 (paused by the owner mid-way): 13 Basic types compile, 84 samples reproduced.
Page RAM image starts with 4 x FF plus one FF per component padded to 4 (found when a page
with five components failed). Read from samples but not yet in the builder: vertical progress
bar (`sys05_4=val*h/100`, fill from `endy+1-sys05_4`), text with border / crop / picture
background (same `_back` / `_border` rules as number, but `sta`, `style`, `borderc`, `borderw`,
`spax`, `spay` are constants there and are written into the script as literals).
Samples waiting to be compiled: `g3.json` in the session scratchpad (directions 0/180/270,
`>=`, mixed `&&`/`||`, string attributes, negative globals, more variants) -- regenerate with
`tools/make_tft_samples.py` (`direction` and `gradient` keys) if the scratchpad is gone.
New sample pairs live in `D:\Claude\nextion-tft-samples\2026-11-17` (outside the repo).