# 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), 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 `"-"` is followed by n records. * `att-`: 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 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 ` -- 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`.