"""Decode a .HMI into a readable, diffable folder -- and encode such a folder back. Folder layout:: manifest.json entry order, model info, which file holds what Program.s the project's start-up script (plain text) main.HMI.json the project header, parsed where understood (+ raw hex) pages/_.json one file per page: header fields + components resources/ every other entry (pictures, fonts, ...) as raw bytes Page JSON:: {"file": "1.pa", "name": "main", "password": 0, "locked": 0, ..., "components": [ {"att": [["type", "u8", 121], ["objname", "str", "main"], ...], "events": {"codesdown": ["page 2"], ...}, "order": ["att", "codesload", ...]} # group order, for exact round trips ]} """ from __future__ import annotations import json import os import struct from . import checksum, enums from .container import HMIFile, build from .page import Attr, Component, Group, Page MODELS = { # model id (main.HMI offset 16) -> (part number, description). Values observed or taken # from public lists of Nextion models; extend as needed. 0xB23BC018: ("NX4832T035_011", 'Nextion 3.5" Basic 480x320'), } def _safe(name: str) -> str: return "".join(ch if ch.isalnum() or ch in "-_." else "_" for ch in name) def parse_main(blob: bytes) -> dict: d = {"crc_ok": checksum.main_crc(blob) == struct.unpack_from(" dict: out = {"order": [g.name for g in c.groups]} events = {} ctype = c.get("type") for g in c.groups: if g.name == "att": out["att"] = [] for a in g.records: kind, value = a.decoded(encoding) if readable: value = enums.to_label(ctype, a.name, kind, value) out["att"].append([a.name, kind, value]) else: events[g.name] = [r.decode(encoding) for r in g.records] out["events"] = events if c.table_extra: out["table_extra"] = c.table_extra if c.trailing: out["trailing_hex"] = c.trailing.hex() return out def component_from_json(d: dict, encoding: str) -> Component: groups = [] ctype = next((v for n, k, v in d.get("att", []) if n == "type"), None) for gname in d.get("order", ["att"] + list(d.get("events", {}))): if gname == "att": groups.append(Group("att", [Attr.encode(n, k, enums.from_label(ctype, n, k, v), encoding) for n, k, v in d["att"]])) else: groups.append(Group(gname, [ln.encode(encoding) for ln in d["events"][gname]])) return Component(groups, d.get("table_extra", 0), bytes.fromhex(d.get("trailing_hex", ""))) def page_to_json(entry_name: str, p: Page, encoding: str, readable: bool = True) -> dict: return {"file": entry_name, "name": p.name, "password": p.password, "locked": p.locked, "b21": p.b21, "version": p.version, "b23": p.b23, "reserved_hex": p.reserved.hex(), "components": [component_to_json(c, encoding, readable) for c in p.components]} def page_from_json(d: dict, encoding: str) -> Page: return Page(d["name"], [component_from_json(c, encoding) for c in d["components"]], d.get("password", 0), d.get("locked", 0), d.get("b21", 0x4F), d.get("version", 0x21), d.get("b23", 0), bytes.fromhex(d.get("reserved_hex", "00" * 16))) def decode(hmi_path: str, out_dir: str, encoding: str = "latin-1", readable: bool = True) -> dict: h = HMIFile.load(hmi_path) os.makedirs(os.path.join(out_dir, "pages"), exist_ok=True) os.makedirs(os.path.join(out_dir, "resources"), exist_ok=True) manifest = {"format": "nxhmi-folder-1", "encoding": encoding, "entries": []} for e in h.live(): blob = h.read(e.name) item = {"name": e.name} if e.name.endswith(".pa"): p = Page.parse(blob) fn = "pages/%s_%s.json" % (_safe(e.name[:-3]), _safe(p.name)) with open(os.path.join(out_dir, fn), "w", encoding="utf-8") as f: json.dump(page_to_json(e.name, p, encoding, readable), f, indent=1, ensure_ascii=False) item["page"] = fn elif e.name == "Program.s": with open(os.path.join(out_dir, "Program.s"), "wb") as f: f.write(blob) item["file"] = "Program.s" elif e.name == "main.HMI": info = parse_main(blob) with open(os.path.join(out_dir, "main.HMI.json"), "w", encoding="utf-8") as f: json.dump(info, f, indent=1) item["main"] = "main.HMI.json" manifest["model"] = info.get("model", info["model_id"]) else: fn = "resources/" + _safe(e.name) with open(os.path.join(out_dir, fn), "wb") as f: f.write(blob) item["file"] = fn _write_preview(out_dir, e.name, blob) manifest["entries"].append(item) with open(os.path.join(out_dir, "manifest.json"), "w", encoding="utf-8") as f: json.dump(manifest, f, indent=1) return manifest def encode(folder: str, hmi_path: str) -> None: with open(os.path.join(folder, "manifest.json"), encoding="utf-8") as f: manifest = json.load(f) enc = manifest.get("encoding", "latin-1") items = [] for it in manifest["entries"]: if "page" in it: with open(os.path.join(folder, it["page"]), encoding="utf-8") as f: items.append((it["name"], page_from_json(json.load(f), enc).pack())) elif "main" in it: with open(os.path.join(folder, it["main"]), encoding="utf-8") as f: blob = bytearray(bytes.fromhex(json.load(f)["raw_hex"])) struct.pack_into(" bytes: """Return main.HMI with one more resource-list entry (e.g. "pa", "6.pa") and a new checksum.""" start, = struct.unpack_from(" Page: """Add a new empty page to an opened project (next free N.pa) and register it in main.HMI.""" from .components import new_page used = {Page.parse(h.read(e.name)).name for e in h.live() if e.name.endswith(".pa")} if name in used: raise ValueError("page %r exists" % name) n = 0 while h.find("%d.pa" % n): n += 1 p = new_page(name, **attrs) h.write("%d.pa" % n, p.pack()) h.write("main.HMI", main_add_resource(h.read("main.HMI"), "pa", "%d.pa" % n)) return p def main_insert_resource(main: bytes, rtype: str, name: str) -> bytes: """Like main_add_resource, but keeps entries grouped by type (the Editor lists i, zi, pa).""" start, = struct.unpack_from(" int: """Add a picture (png/jpg/bmp bytes) to the project; returns its picture id. Basic series only.""" from . import pictures n = 0 while h.find("%d.i" % n): n += 1 pic, src = pictures.from_image_file(image_file) 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)) return n def _write_preview(out_dir: str, name: str, blob: bytes) -> None: """Human-readable companions of binary resources (never read back by encode).""" from . import fonts, pictures try: if name.endswith(".is"): info = pictures.source_info(blob) with open(os.path.join(out_dir, "resources", _safe(name) + "." + (info["type"] or "bin")), "wb") as f: f.write(pictures.source_file(blob)) elif name.endswith(".zi"): font = fonts.Font.parse(blob) lines = ["font %r %dx%d encoding %d chars 0x%02X-0x%02X" % (font.name, font.width, font.height, font.encoding, font.first, font.last)] for g in font.glyphs: lines.append("") lines.append("char 0x%02X %r width %d" % (g.code, chr(g.code), g.width)) lines += ["".join("#" if v else "." for v in row) for row in g.pixels] with open(os.path.join(out_dir, "resources", _safe(name) + ".txt"), "w", encoding="utf-8") as f: f.write("\n".join(lines) + "\n") except (ValueError, NotImplementedError, struct.error): pass def add_font(h: HMIFile, font) -> int: """Add a fonts.Font to the project; returns its font id.""" n = 0 while h.find("%d.zi" % n): n += 1 h.write("%d.zi" % n, font.pack()) h.write("main.HMI", main_insert_resource(h.read("main.HMI"), "zi", "%d.zi" % n)) return n DEFAULT_PROGRAM = ( "//Program.s runs once at power-on, before the first page is shown.\r\n" "//Global variables can be declared here: int sys0=0\r\n" "baud=115200\r\n" "page 0\r\n" ) def make_main(model: str, resources: list, encoding: str = "iso-8859-1") -> 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"). """ from . import models mid, series, _, _ = models.lookup(model) b = bytearray(0x60) struct.pack_into(" HMIFile: """A new, empty project with one page -- no Nextion files needed.""" from . import models from .components import new_page _, _, w, h = models.lookup(model) page = new_page(first_page, w=w, h=h) items = [("main.HMI", make_main(model, [("pa", "0.pa")])), ("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.""" from . import models mid = struct.unpack_from("