All five display series; exact component colours; Editor's literal rule for format 4

- 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>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-16 14:35:50 +01:00
1 parent 922ca21f0f
commit ec35ceb615
9 files changed
+140 -57

No files matched your search

+1 -1
View File
@@ -26,7 +26,7 @@ Every percentage is a count with a stated basis, so it can be checked (details i
| `.HMI` read / write / build from scratch | **100 %** of everything seen | every entry type in Editor-written files round-trips byte-identical; new projects open in the Editor |
| Checksums (`.HMI`) | **100 %** (3/3) | page, project header, file table |
| Component types (read, write, create) | **100 %** (31/31) | all types in the Editor's toolbox, incl. 11 Intelligent-only |
| Display series | **40 %** (2/5) | Basic (T) and Intelligent (P) confirmed; Discovery, Enhanced, Edge not sampled |
| Display series | **100 %** (5/5) | Basic, Enhanced, Intelligent, Edge, Discovery: all 27 models, series bytes, picture format and storage direction per series |
| Picture formats | **100 %** (2/2) | raw RGB565 (Basic) and run-length + alpha or JPEG for quality < 100 (Intelligent), byte-identical to the Editor (transparent JPEG pictures: near-identical), every display direction |
| Font modes | **100 %** (2/2) | black/white and "anti-aliased" (a header flag; glyphs stay 1-bit, verified in the simulator); single- and multi-byte encodings (GB2312, Big5, Shift-JIS, KS C 5601, UTF-8), Editor fonts round-trip byte-identical |
| Readable attribute names in JSON | **100 %** (31/31 types) | every value list the Editor documents, incl. the Intelligent-only types and load effects |
+4 -5
View File
@@ -16,7 +16,7 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th
| Pictures | **complete**: format 0 (Basic) and format 4 (Intelligent, with alpha; run-length or JPEG for quality < 100), all display directions |
| Fonts | **complete**: single- and multi-byte encodings (GB2312, Big5, Shift-JIS, KS C 5601, UTF-8), black/white and the anti-aliasing flag, overhanging glyphs, all display directions; generation from TrueType for all of them |
| Rendering pages like the Editor | **pixel-identical** for every Basic component and 9 of 11 Intelligent-only ones; ComboBox and Switch approximate at anti-aliased edges |
| New projects from scratch | `project.new_project(model)` for 12 Basic/Intelligent models; the generated demo is byte-identical to the Editor's re-save |
| New projects from scratch | `project.new_project(model)` for all 27 models of the 5 series; the generated demo is byte-identical to the Editor's re-save |
| Compiling `.tft` firmware | **research only** -- not possible yet |
## How the percentages in the README are counted
@@ -93,7 +93,6 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th
### `.HMI` side
| Item | Notes |
|---|---|
| Other display series | Discovery / Enhanced / Edge not sampled; only Basic + Intelligent templates |
| Display direction | byte 12 decoded and written (`new_project(portrait=...)`); picture order verified for all four (format 4); font glyph order verified for 0° and 90° |
| Some header fields | main.HMI bytes 8, 13, 36, 0x41; page header 21/23; entry bytes 25-27 |
| Font name shown in the Editor's Fonts panel | cosmetic, generated fonts show an odd label |
@@ -118,6 +117,6 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th
| Licensing | every `.tft` embeds Nextion's firmware files; the repo must never ship them -- a builder would read them from the user's own Editor installation |
## Suggested next steps
1. Intelligent picture format 4 (needed for Intelligent displays).
2. `.tft`: try the remaining trailer-checksum ideas listed in NOTES.md; then the compiled page format.
3. Sample the other display series to confirm templates and picture order.
1. `.tft`: try the remaining trailer-checksum ideas listed in NOTES.md; then the compiled page format.
2. The anti-aliasing routine of Intelligent rounded shapes (switch knob/track, ComboBox).
3. Picture quality < 100 on Edge (JPEG variant) -- not tried.
+19 -4
View File
@@ -61,7 +61,7 @@ primary table from the backup, among other things) -- never reuse a test file af
| 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** |
| 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 |
@@ -196,7 +196,7 @@ PNG that was imported):
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | `0B 64 01 <format>` -- 0 = raw RGB565 (Basic series), 4 = compressed (Intelligent, **OPEN**) |
| 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) |
@@ -206,6 +206,19 @@ 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):
@@ -227,8 +240,10 @@ four directions, with and without alpha):
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).
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.
+5 -3
View File
@@ -51,9 +51,11 @@ TextSelects, several of each other type):
## Rules learned from the Editor
- Colours: RGB565 is expanded differently per series. Basic replicates the top bits
(`r<<3 | r>>2`); Intelligent scales (`r*255//31`, `g*255//63`), so `0xC618` shows as
(198,195,198) on Basic and (197,194,197) on Intelligent.
- Colours: component colours (bco, pco, ...) are scaled on every series (`r*255//31`,
`g*255//63`), so `0xC618` shows as (197,194,197); format-0 picture pixels are bit-replicated
(`r<<3 | r>>2`); format-3/4 pictures as decoded. (Until 2026-11 nxhmi replicated component
colours on Basic -- off by one level in some channels; earlier comparisons used a tolerance
that hid it. Now checked with zero tolerance on Basic, Enhanced, Discovery and Edge.)
- Intelligent 3D frames draw the left edge after the bottom one (dark bottom-left corner on
3D down); Basic draws it the other way round.
- TextSelect: items (`path`, CR LF separated) in cells of `hig` rows inside the frame; the
+35 -4
View File
@@ -1,7 +1,8 @@
"""Display models: id stored in main.HMI (offset 16), series byte (offset 11), native resolution.
Only series whose series byte was confirmed in the Editor are listed (Basic = 0, Intelligent = 3).
Model ids are the 32-bit values the Editor writes for each model.
Every model in Nextion Editor 1.68's model dialog, with the series byte and model id the Editor
writes (Basic = 0, Enhanced = 1, Intelligent = 3, Edge = 6, Discovery = 100).
Sizes are listed landscape (width >= height).
"""
from __future__ import annotations
@@ -19,14 +20,32 @@ MODELS = {
"NX8048P070_011": (0xDA27BAA7, 3, 800, 480),
"NX1060P070_011": (0xC43473C2, 3, 1024, 600),
"NX1060P101_011": (0x4FC44FA0, 3, 1024, 600),
"NX8048P043_011": (0xA859A323, 3, 800, 480),
# Discovery (F)
"NX3224F024_011": (0x5B49C1BC, 100, 320, 240),
"NX3224F028_011": (0xBA9C8E20, 100, 320, 240),
"NX4832F035_011": (0x1CE47603, 100, 480, 320),
# Enhanced (K)
"NX3224K024_011": (0x5C7E9301, 1, 320, 240),
"NX3224K028_011": (0xBDABDC9D, 1, 320, 240),
"NX4024K032_011": (0xC4A1A90F, 1, 400, 240),
"NX4832K035_011": (0x1BD324BE, 1, 480, 320),
"NX4827K043_011": (0x63C18A17, 1, 480, 272),
"NX8048K050_011": (0x2E45DE45, 1, 800, 480),
"NX8048K070_011": (0xA1F7596A, 1, 800, 480),
# Edge (E)
"NX4848E021_011": (0xA2770AFE, 6, 480, 480),
"NX4848E028_011": (0x0B3DB14B, 6, 480, 480),
"NX4848E040_011": (0x21B2AF65, 6, 480, 480),
"NX4880E043_011": (0xB7A00D7C, 6, 800, 480),
}
BY_ID = {v[0]: k for k, v in MODELS.items()}
SERIES = {0: "Basic", 3: "Intelligent"}
SERIES = {0: "Basic", 1: "Enhanced", 3: "Intelligent", 6: "Edge", 100: "Discovery"}
# main.HMI offset 12: display direction, in 90-degree steps as chosen in the Editor
# (Setting > Display: 0 / 90 / 180 / 270). Basic panels are portrait at 0 degrees, so the
# landscape sizes listed above need 90 or 270; Intelligent panels are landscape at 0 and 180.
NATIVE_PORTRAIT = {0: True, 3: False}
NATIVE_PORTRAIT = {0: True, 1: True, 3: False, 6: True, 100: True} # as listed in the model dialog
def direction_byte(model: str, landscape: bool = True, flipped: bool = False) -> int:
@@ -35,6 +54,18 @@ def direction_byte(model: str, landscape: bool = True, flipped: bool = False) ->
return (1 if landscape == portrait_native else 0) + (2 if flipped else 0)
def storage_direction(series: int, direction: int) -> int:
"""Direction pictures and fonts are stored in (their byte 0 / 3 = 0x0A + this): the project
direction, except Discovery, which always stores row by row (0) -- measured in Editor 1.68."""
return 0 if series == 100 else direction % 4
def picture_format(series: int) -> int:
"""N.i format the Editor writes: 0 raw (Basic, Enhanced), 4 run-length/JPEG (Intelligent, Edge),
3 raw with a 20-byte zero header (Discovery)."""
return {3: 4, 6: 4, 100: 3}.get(series, 0)
def page_size(model: str, direction: int):
"""(width, height) of the pages for main.HMI byte 12 = direction."""
_, series, w, h = lookup(model)
+46 -33
View File
@@ -158,51 +158,56 @@ def encode_format4(pixels_rgba, width: int, height: int, direction: int = 0) ->
"""Format-4 ``N.i`` (Intelligent series), byte-identical to Nextion Editor 1.68's output.
pixels_rgba: callable (x, y) -> (r, g, b[, a]). Colours run in groups of up to 13 pixels;
eight ops make a block; blocks of eight 13-runs of one colour merge into a long run (op 14),
blocks of eight single pixels into a literal block (op 15)."""
a stretch where the next 8 runs cover at most 10 pixels (7+ runs, 8+ pixels left) becomes
literal pixels, 8 at a time (op 15) -- measured on designed run patterns."""
order = stored_order(width, height, direction)
rgba = [tuple(pixels_rgba(x, y)) + (255,) for x, y in order]
px = [_565(c) if c[3] else 0 for c in rgba]
alpha = [c[3] * 127 // 255 for c in rgba]
has_alpha = any(a != 127 for a in alpha)
n = len(px)
ops, i = [], 0
while i < n:
pw, ph = (height, width) if direction % 2 else (width, height)
out = bytearray(struct.pack("<IIIII", 1, pw, ph, 0, 0))
def next_ops(i):
ops = []
while i < n and len(ops) < 8:
j = i
while j < n and px[j] == px[i] and j - i < 13:
j += 1
ops.append((px[i], j - i))
i = j
blocks = [ops[k:k + 8] for k in range(0, len(ops), 8)]
pw, ph = (height, width) if direction % 2 else (width, height)
out = bytearray(struct.pack("<IIIII", 1, pw, ph, 0, 0))
def long_run(b, colour):
return len(b) == 8 and all(c == colour and length == 13 for c, length in b)
def literal(b):
return len(b) == 8 and all(length == 1 for _, length in b)
k = 0
while k < len(blocks):
b = blocks[k]
if long_run(b, b[0][0]):
m = k
while m < len(blocks) and long_run(blocks[m], b[0][0]) and (m - k + 1) * 104 <= 0xFFF:
m += 1
out += struct.pack("<I8H", 14 | (m - k) * 104 << 4, *[b[0][0]] * 8)
k = m
elif literal(b):
m = k
while m < len(blocks) and literal(blocks[m]) and (m - k + 1) * 8 <= 0xFFF:
m += 1
cols = [c for bb in blocks[k:m] for c, _ in bb]
out += struct.pack("<I%dH" % len(cols), 15 | len(cols) << 4, *cols)
k = m
else:
return ops
i = 0
while i < n:
ops = next_ops(i)
if len(ops) >= 7 and sum(l for _, l in ops) <= 10 and n - i >= 8:
# busy stretch: literal pixels, 8 at a time, merged while the rule keeps holding
k = i
while k < n and n - k >= 8 and k - i + 8 <= 0xFFF:
o = next_ops(k)
if not (len(o) >= 7 and sum(l for _, l in o) <= 10):
break
k += 8
out += struct.pack("<I%dH" % (k - i), 15 | (k - i) << 4, *px[i:k])
i = k
continue
if len(ops) == 8 and all(l == 13 and c == ops[0][0] for c, l in ops):
# eight 13-runs of one colour: long run (op 14), consecutive blocks merge
k, total = i, 0
while total + 104 <= 0xFFF:
o = next_ops(k)
if not (len(o) == 8 and all(l == 13 and c == ops[0][0] for c, l in o)):
break
k += 104; total += 104
out += struct.pack("<I8H", 14 | total << 4, *[ops[0][0]] * 8)
i = k
continue
ctrl = 0
for slot, (_, length) in enumerate(b):
for slot, (_, length) in enumerate(ops):
ctrl |= length << (4 * slot)
out += struct.pack("<I8H", ctrl, *([c for c, _ in b] + [0] * (8 - len(b))))
k += 1
out += struct.pack("<I8H", ctrl, *([c for c, _ in ops] + [0] * (8 - len(ops))))
i += sum(l for _, l in ops)
aoff = 0
if has_alpha:
aoff = len(out)
@@ -218,7 +223,11 @@ def from_image_file(data: bytes, direction: int = 1, series: int = 0, quality: i
img = Image.open(io.BytesIO(data))
ftype = (img.format or "png").lower()[:3]
w, h = img.size
if series == 3 and w * h > 2: # the Editor keeps 1-2 pixel pictures in format 0
if series == 100: # Discovery: format 3 = 20 zero bytes + raw RGB565
rgb = img.convert("RGB").load()
pic = make_picture(bytes(20) + to_rgb565(lambda x, y: rgb[x, y], w, h, direction), w, h, direction)
pic = pic[:3] + bytes([3]) + pic[4:]
elif series in (3, 6) and w * h > 2: # the Editor keeps 1-2 pixel pictures in format 0
rgba = img.convert("RGBA").load()
if quality < 100:
pic = encode_jpeg(lambda x, y: rgba[x, y], w, h, direction, quality)
@@ -314,6 +323,8 @@ def decode_format4(blob: bytes):
def _rgb(v: int):
"""Format-0 picture pixel RGB565 -> RGB as the Editor canvas shows it: bit replication
(component colours and format-4 pictures are scaled instead, v * 255 // max)."""
r, g, b = v >> 11, (v >> 5) & 63, v & 31
return (r << 3 | r >> 2, g << 2 | g >> 4, b << 3 | b >> 2)
@@ -331,6 +342,8 @@ def to_image(blob: bytes):
_, _, px, alpha = decode_format4(blob)
elif d["format"] == 0:
px, alpha = struct.unpack_from("<%dH" % (w * h), blob, 24), None
elif d["format"] == 3: # Discovery: 20-byte zero header, then raw RGB565
px, alpha = struct.unpack_from("<%dH" % (w * h), blob, 44), None
else:
raise NotImplementedError("picture format %d not supported" % d["format"])
img = Image.new("RGBA" if alpha else "RGB", (w, h))
+6 -3
View File
@@ -223,8 +223,10 @@ def add_picture(h: HMIFile, image_file: bytes, quality: int = 100) -> int:
n = 0
while h.find("%d.i" % n):
n += 1
from . import models
main = h.read("main.HMI")
pic, src = pictures.from_image_file(image_file, direction=main[12] % 4, series=main[11], quality=quality)
pic, src = pictures.from_image_file(image_file, direction=models.storage_direction(main[11], main[12]),
series=main[11], quality=quality)
h.write("%d.is" % n, src)
h.write("%d.i" % n, pic)
h.write("main.HMI", main_insert_resource(h.read("main.HMI"), "i", "%d.i" % n))
@@ -258,9 +260,10 @@ def add_font(h: HMIFile, font) -> int:
n = 0
while h.find("%d.zi" % n):
n += 1
from . import models
main = h.read("main.HMI")
font.direction = main[12] % 4 # glyphs are stored rotated like pictures
font.align = main[11] == 3 # Intelligent: glyph data 8-byte aligned
font.direction = models.storage_direction(main[11], main[12]) # stored rotated like pictures
font.align = main[11] in (3, 100) # Intelligent/Discovery: glyph data 8-byte aligned
h.write("%d.zi" % n, font.pack())
h.write("main.HMI", main_insert_resource(h.read("main.HMI"), "zi", "%d.zi" % n))
return n
+6 -4
View File
@@ -118,12 +118,14 @@ def qr_rects(txt, w: int, dis: int):
return rects
def rgb(v: int, series: int = 0):
"""RGB565 -> 8-bit RGB the way the Editor shows it: Basic replicates the top bits,
Intelligent scales (``v * 255 // 31``), e.g. 0xC618 is (198,195,198) vs (197,194,197)."""
"""Component colour RGB565 -> 8-bit RGB the way the Editor shows it, on every series (canvas and
simulator, measured exactly): scaled, ``v * 255 // 31``, e.g. 0xC618 -> (197,194,197).
(Format-0 picture pixels are bit-replicated instead, see pictures._rgb.) ``series=None``
gives bit replication."""
r, g, b = v >> 11, (v >> 5) & 63, v & 31
if series == 3:
return (r * 255 // 31, g * 255 // 63, b * 255 // 31)
if series is None: # bit replication (old behaviour, for reference)
return (r << 3 | r >> 2, g << 2 | g >> 4, b << 3 | b >> 2)
return (r * 255 // 31, g * 255 // 63, b * 255 // 31)
class Renderer:
+18
View File
@@ -46,6 +46,24 @@ class NewProject(unittest.TestCase):
self.assertEqual(main[11], series)
self.assertEqual(Page.parse(h.read("0.pa")).components[0].get("w"), w)
def test_series_storage(self):
# measured in Editor 1.68: picture format and storage direction per series
import io
from PIL import Image
from nxhmi import fonts
im = Image.new("RGB", (5, 3), (10, 200, 30)); b = io.BytesIO(); im.save(b, "PNG")
cases = {"NX4832T035_011": (0x0B, 0), "NX4832K035_011": (0x0B, 0), "NX4832F035_011": (0x0A, 3),
"NX4848E040_011": (0x0B, 4), "NX4827P043_011": (0x0A, 4)}
for name, (b0, fmt) in cases.items():
h = project.new_project(name)
project.add_picture(h, b.getvalue())
project.add_font(h, fonts.from_ttf(None, 8))
pic, zi = h.read("0.i"), h.read("0.zi")
self.assertEqual((pic[0], pic[3]), (b0, fmt), name)
self.assertEqual(zi[3], b0, name) # fonts are stored like pictures
self.assertEqual(models.SERIES[100], "Discovery")
self.assertEqual(models.page_size("NX4880E043_011", 0), (480, 800)) # Edge 4.3": portrait native
def test_unknown_model(self):
with self.assertRaises(KeyError):
project.new_project("NX0000X000_000")