- 15 more models (Discovery, Enhanced, Edge, NX8048P043): ids and series bytes 1/6/100 from the Editor; native orientation per series; Discovery/Enhanced/Edge use the Basic templates - per series picture format and storage direction: Enhanced like Basic, Edge format 4, Discovery format 3 (20 zero bytes + raw RGB565) always stored row by row; fonts likewise - component colours are scaled (v*255//31) on every series -- exact against the canvas with zero tolerance; format-0 pictures stay bit-replicated - format-4 encoder: literal pixels when the next 8 runs cover <= 10 pixels (7+ runs), 8 pixels at a time -- reproduces the Editor on 12 designed patterns plus the 28 earlier samples Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
330 lines
17 KiB
Markdown
330 lines
17 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) | 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`.
|