Files
openhmi-nx/docs/FORMAT.md
T
mangavalkandClaude Opus 5.5 0138a0ba56 Multi-byte fonts: GB2312, Big5, Shift-JIS, KS C 5601, UTF-8
Font Creator output decoded (lead/trail ranges and gaps in the header, map codes = bytes as
little-endian u16 or Unicode code points) and round-tripped byte for byte; from_ttf(chars=)
builds them; the renderer splits text like the simulator (any byte >= 0x81 starts a pair,
missing characters advance one space) -- pixel-exact for all five encodings.
Intelligent glyph data is 8-byte aligned (was 4). CLI add-font --chars/--chars-file, MCP chars.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 13:42:50 +01:00

16 KiB
Raw Blame History

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 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 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). The order follows the display direction, see format 4.

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); a block of eight single pixels becomes a literal block (consecutive ones merge, N = 8 × blocks).

  • 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.