Files
openhmi-nx/docs/NOTES.md
T

269 lines
17 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.
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).
## Idea: custom firmware on the display, and the risk of bricking it (2026-11-17)
Only an idea, not planned. Nothing here was tested; the chips on the board have not been
identified (a photo of the back of the board would tell us the MCU, display controller, flash
and whether there are SWD/JTAG pads).
Three ways to get our own code onto the screen, from safest to riskiest:
1. **A `.tft` from our builder, uploaded the normal way (serial or microSD): low risk.** The
builder copies Nextion's firmware pieces unchanged (the SHA-256 check guarantees that). Only
the project data is ours. A mistake there should give a blank or garbled screen, a crash loop or
a refused upload, not a dead update path. The usual recovery is a microSD card with a
known-good Editor-made `.tft` (insert, power on). Caveat: which flash areas the firmware pieces
overwrite is unknown, but since they are the Editor's own bytes the risk equals any Editor
upload. Before the first test on a real display: prepare that recovery card, and start with a
builder output that is byte-identical to the Editor's.
2. **Our own firmware flashed over SWD (like the nRF dongle): the Nextion firmware is lost for
good, the hardware survives.** The chip is almost certainly read-protected, so the original
cannot be backed up. The chip itself is hard to brick through SWD: it can almost always be
reflashed. Exceptions: firmware that disables the debug pins (usually recoverable by connecting
under reset) and setting the permanent read-protection level (irreversible). Small hardware
risk: driving a pin against something on the board, or misconfiguring the backlight / LCD
supply. Read the board layout before writing to pins. Then own drivers are needed for the LCD
controller, the touch input, the flash and the UART, after which LVGL could run on it. Feasible
on a common STM32/GD32-class MCU with enough RAM; much harder with a proprietary or FPGA
display controller. Only on a spare display.
3. **Our own code in the firmware slots of a `.tft`: highest risk, far away.** Broken code there
could stop the display from ever accepting a new upload; whether microSD recovery still works
depends on where the bootloader lives (unknown). It would also need Nextion's runtime and
bootloader to be understood, which goes beyond the black-box rule.
Cheaper alternative if the goal is just "our own code on the remote's screen": an ESP32 board with
a 3.5" 480x320 touchscreen costs about the same, is fully open, runs LVGL and has Wi-Fi/Bluetooth.