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

+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)