251 lines
11 KiB
Markdown
251 lines
11 KiB
Markdown
# The Nextion Editor `.HMI` project format
|
||||
|
|
|
|||
|
|
Reverse-engineered black-box: by editing projects in Nextion Editor (v1.68), 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), 3 = Intelligent (P); others **OPEN** |
|
|||
|
|
| 12 | 1 | text encoding index (1 = iso-8859-1; an unknown value makes the Editor fail with "'null' is not a supported encoding name") |
|
|||
|
|
| 13 | 1 | 3 (**OPEN**; not the model index) |
|
|||
|
|
| 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 | `0B 64 01 <format>` -- 0 = raw RGB565 (Basic series), 4 = compressed (Intelligent, **OPEN**) |
|
|||
|
|
| 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). **OPEN**: whether the order changes with the project's display
|
|||
|
|
direction (all samples: main.HMI byte 13 = 3).
|
|||
|
|
|
|||
|
|
Format 4 (Intelligent series, **OPEN**): header field at 20 is non-zero for small pictures
|
|||
|
|
(e.g. 2640 for a 3307-byte payload); payload starts with u32 1, u32 height, u32 width (note:
|
|||
|
|
swapped vs. the header, i.e. panel orientation), ... then a block codec: runs of RGB565 colours
|
|||
|
|
followed by small index bytes (e.g. `18c6 38c6 18c6 38c6 2131 1111`), with a variable number of
|
|||
|
|
bytes per 4x4 block, and full 8-bit alpha (a PNG with 256 alpha levels was imported). A 480x320
|
|||
|
|
photo compresses to 215,052 bytes at "Q:100".
|
|||
|
|
|
|||
|
|
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 0B`, 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.
|
|||
|
|
|
|||
|
|
Character map: 10 bytes per character: u16 code, u8 glyph width, 2 unknown bytes,
|
|||
|
|
u24 glyph offset (relative to the map start), u16 glyph length.
|
|||
|
|
|
|||
|
|
Glyph: mode byte (0x01 = black/white), then run-length codes over the pixels in the same
|
|||
|
|
column-by-column, bottom-to-top order as pictures (runs continue across columns):
|
|||
|
|
|
|||
|
|
| 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**: anti-aliased glyphs (other mode bytes), multi-byte encodings,
|
|||
|
|
the 16 unknown header bytes.
|
|||
|
|
|
|||
|
|
## 6. Not yet covered
|
|||
|
|
|
|||
|
|
See `docs/NOTES.md`.
|