Display direction and character encoding in main.HMI

Byte 12 is the display direction (90-degree steps) and byte 13 the
character encoding -- the docs had them swapped. Basic panels are
portrait at 0 degrees, Intelligent ones landscape, so new Intelligent
projects used to open in portrait. new_project takes portrait= and
encoding=; all 24 Editor encodings are mapped; parse_main reports both.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-15 16:36:10 +01:00
1 parent 842591a14c
commit a93cb58b96
7 files changed
+77 -21

No files matched your search

+2
View File
@@ -29,6 +29,8 @@ Back up the user's file first (copy it) unless they said not to; edits write in
- `schema <kind>` lists every attribute of a component kind with defaults and allowed values;
`list_kinds` lists the kinds (`button`, `text`, `number`, `slider`, `progress_bar`, ...).
- Coordinates: `x`, `y`, `w`, `h` in pixels; `endx`/`endy` are updated automatically.
- `new_project` is landscape by default (`portrait: true` for a tall screen); `info` shows
`direction` and `encoding`.
- Text needs a font: `font` is a font id. A new project has **no fonts** -- call `add_font`
first (height in px; no TrueType path = bundled CC0 font). `txt_maxl` must be >= the text length.
- Pictures: `add_picture` returns an id for `pic` / `picc` (crop) / `pic2` etc. Basic-series
+1 -1
View File
@@ -89,7 +89,7 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th
| Intelligent picture format 4 | block codec with 8-bit alpha; first findings in FORMAT.md |
| Anti-aliased fonts, multi-byte encodings (GB2312, Big5, ...) | only B/W single-byte fonts seen |
| Other display series | Discovery / Enhanced / Edge not sampled; only Basic + Intelligent templates |
| Display direction | picture/glyph order verified for one direction (main.HMI byte 13 = 3) only |
| Display direction | byte 12 decoded and written (`new_project(portrait=...)`); picture/glyph order verified for one direction (90° Basic) only |
| 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 |
| Media resources | video / audio / Gmov files themselves (not just the components) |
+3 -3
View File
@@ -62,8 +62,8 @@ primary table from the backup, among other things) -- never reuse a test file af
| 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) |
| 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 |
@@ -205,7 +205,7 @@ Format 0: RGB565 little-endian, converted by plain truncation (`r>>3, g>>2, b>>3
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).
direction (all samples: main.HMI byte 12 = 1, i.e. 90° on a Basic panel).
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:
+5 -4
View File
@@ -143,10 +143,10 @@ def t_add_page(path, name, attributes=None):
return {"page": name, "entry": entry}
def t_new_project(path, model="NX4832T035_011", first_page="page0"):
def t_new_project(path, model="NX4832T035_011", first_page="page0", portrait=False, encoding="iso-8859-1"):
if os.path.exists(path):
raise ValueError("%s exists; refusing to overwrite" % path)
project.new_project(model, first_page).save(path)
project.new_project(model, first_page, portrait=portrait, encoding=encoding).save(path)
return t_info(path)
@@ -237,8 +237,9 @@ TOOLS = {
{"path": S, "page": S, "component": S}, ["path", "page", "component"]),
"add_page": (t_add_page, "Add an empty page (display size of the project).",
{"path": S, "name": S, "attributes": OBJ}, ["path", "name"]),
"new_project": (t_new_project, "Create a new project file (refuses to overwrite). Models: see nxhmi.models.",
{"path": S, "model": S, "first_page": S}, ["path"]),
"new_project": (t_new_project, "Create a new project file (refuses to overwrite). Models: see nxhmi.models. "
"Landscape unless portrait is true; encoding as in the Editor (iso-8859-1, utf-8, gb2312, ...).",
{"path": S, "model": S, "first_page": S, "portrait": {"type": "boolean"}, "encoding": S}, ["path"]),
"add_picture": (t_add_picture, "Add a picture from an image file (png/jpg/bmp); returns its picture id.",
{"path": S, "image_path": S}, ["path", "image_path"]),
"add_font": (t_add_font, "Add a font rasterized from a TrueType file (omit ttf_path for the bundled CC0 font).",
+28 -2
View File
@@ -23,8 +23,34 @@ MODELS = {
BY_ID = {v[0]: k for k, v in MODELS.items()}
SERIES = {0: "Basic", 3: "Intelligent"}
# main.HMI text-encoding index (offset 12). Only the value seen in real projects is listed.
ENCODINGS = {"iso-8859-1": 1}
# 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}
def direction_byte(model: str, landscape: bool = True, flipped: bool = False) -> int:
"""main.HMI byte 12 for a landscape/portrait project on this model (flipped = +180 degrees)."""
portrait_native = NATIVE_PORTRAIT[lookup(model)[1]]
return (1 if landscape == portrait_native else 0) + (2 if flipped else 0)
def page_size(model: str, direction: int):
"""(width, height) of the pages for main.HMI byte 12 = direction."""
_, series, w, h = lookup(model)
landscape = (direction % 2 == 1) == NATIVE_PORTRAIT[series]
return (w, h) if landscape else (h, w)
# main.HMI offset 13: character encoding, value -> name as in the Editor's Setting > Display list.
# Measured by choosing each entry in Nextion Editor 1.68 and saving.
ENCODINGS = {
"ascii": 1, "gb2312": 2, "iso-8859-1": 3, "iso-8859-2": 4, "iso-8859-3": 5, "iso-8859-4": 6,
"iso-8859-5": 7, "iso-8859-6": 8, "iso-8859-7": 9, "iso-8859-8": 10, "iso-8859-9": 11,
"iso-8859-13": 12, "iso-8859-15": 13, "iso-8859-11": 14, "ks_c_5601-1987": 15, "big5": 16,
"windows-1255": 17, "windows-1256": 18, "windows-1257": 19, "windows-1258": 20,
"windows-874": 21, "koi8-r": 22, "shift-jis": 23, "utf-8": 24,
}
def lookup(model: str):
+22 -11
View File
@@ -44,6 +44,10 @@ def parse_main(blob: bytes) -> dict:
mid = struct.unpack_from("<I", blob, 16)[0]
if mid in MODELS:
d["model"], d["model_desc"] = MODELS[mid]
from . import models
d["direction"] = blob[12] * 90 # degrees, as in the Editor's Setting > Display
names = {v: k for k, v in models.ENCODINGS.items()}
d["encoding"] = names.get(blob[13], blob[13])
# resource list: header size at +4 (= list start), count at +28, entries of type[8] + name[8]
start, = struct.unpack_from("<I", blob, 4)
count, = struct.unpack_from("<I", blob, 28)
@@ -263,18 +267,23 @@ DEFAULT_PROGRAM = (
)
def make_main(model: str, resources: list, encoding: str = "iso-8859-1") -> bytes:
def make_main(model: str, resources: list, encoding: str = "iso-8859-1", direction: int = None) -> bytes:
"""Build a main.HMI project header from scratch.
Field values follow Nextion Editor 1.68 output (see docs/FORMAT.md); ``resources`` is a list of
(type, name) such as ("pa", "0.pa").
(type, name) such as ("pa", "0.pa"). ``direction`` is the Editor's display direction in
90-degree steps (byte 12); the default is landscape for the model.
"""
from . import models
mid, series, _, _ = models.lookup(model)
if direction is None:
direction = models.direction_byte(model)
if encoding not in models.ENCODINGS:
raise ValueError("unknown encoding %r; known: %s" % (encoding, ", ".join(models.ENCODINGS)))
b = bytearray(0x60)
struct.pack_into("<I", b, 4, 0x60) # header size / resource list start
b[8:12] = bytes([0x01, 0x44, 0x21, series])
b[12:16] = bytes([models.ENCODINGS[encoding], 0x03, 0x4F, 0x00])
b[12:16] = bytes([direction % 4, models.ENCODINGS[encoding], 0x4F, 0x00])
struct.pack_into("<I", b, 16, mid)
struct.pack_into("<I", b, 24, 0x60)
struct.pack_into("<I", b, 28, len(resources))
@@ -286,21 +295,23 @@ def make_main(model: str, resources: list, encoding: str = "iso-8859-1") -> byte
return bytes(b)
def new_project(model: str = "NX4832T035_011", first_page: str = "page0", program: str = DEFAULT_PROGRAM) -> HMIFile:
"""A new, empty project with one page -- no Nextion files needed."""
def new_project(model: str = "NX4832T035_011", first_page: str = "page0", program: str = DEFAULT_PROGRAM,
portrait: bool = False, encoding: str = "iso-8859-1") -> HMIFile:
"""A new, empty project with one page -- no Nextion files needed. Landscape unless ``portrait``."""
from . import models
from .components import new_page
_, _, w, h = models.lookup(model)
direction = models.direction_byte(model, landscape=not portrait)
w, h = models.page_size(model, direction)
page = new_page(first_page, w=w, h=h)
items = [("main.HMI", make_main(model, [("pa", "0.pa")])),
items = [("main.HMI", make_main(model, [("pa", "0.pa")], encoding, direction)),
("Program.s", program.encode("latin-1")),
("0.pa", page.pack())]
return build(items)
def project_size(h: HMIFile):
"""(width, height) of the project's display, from main.HMI."""
"""(width, height) of the project's pages, from main.HMI (model and display direction)."""
from . import models
mid = struct.unpack_from("<I", h.read("main.HMI"), 16)[0]
name = models.BY_ID.get(mid)
return models.MODELS[name][2:4] if name else (480, 320)
main = h.read("main.HMI")
name = models.BY_ID.get(struct.unpack_from("<I", main, 16)[0])
return models.page_size(name, main[12]) if name else (480, 320)
+16
View File
@@ -22,6 +22,22 @@ class NewProject(unittest.TestCase):
self.assertEqual(Page.parse(h.read("0.pa")).name, "start")
self.assertEqual(project.project_size(h), (480, 320))
def test_direction_and_encoding(self):
# measured in the Editor: Basic panels are portrait at 0 degrees, Intelligent landscape
basic = project.new_project("NX4832T035_011")
self.assertEqual(basic.read("main.HMI")[12:14], bytes([1, 3])) # 90 degrees, iso-8859-1
tall = project.new_project("NX4832T035_011", portrait=True)
self.assertEqual(tall.read("main.HMI")[12], 0)
self.assertEqual(project.project_size(tall), (320, 480))
intel = project.new_project("NX4827P043_011")
self.assertEqual(intel.read("main.HMI")[12], 0)
self.assertEqual(project.project_size(intel), (480, 272))
info = project.parse_main(project.new_project(encoding="utf-8").read("main.HMI"))
self.assertEqual((info["direction"], info["encoding"]), (90, "utf-8"))
self.assertEqual(models.ENCODINGS["gb2312"], 2)
with self.assertRaises(ValueError):
project.new_project(encoding="latin-9")
def test_every_model(self):
for name, (mid, series, w, hgt) in models.MODELS.items():
h = project.new_project(name)