Files
openhmi-nx/src/nxhmi/project.py
T

306 lines
13 KiB
Python
Raw Normal View History

"""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/<N>_<name>.json one file per page: header fields + components
resources/<entry> 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("<I", blob, 0)[0],
"model_id": "0x%08X" % struct.unpack_from("<I", blob, 16)[0]}
mid = struct.unpack_from("<I", blob, 16)[0]
if mid in MODELS:
d["model"], d["model_desc"] = MODELS[mid]
# 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)
res = []
for i in range(count):
o = start + 16 * i
res.append([blob[o:o + 8].rstrip(b"\0").decode("latin-1"), blob[o + 8:o + 16].rstrip(b"\0").decode("latin-1")])
d["resources"] = res
d["raw_hex"] = blob.hex()
return d
def component_to_json(c: Component, encoding: str, readable: bool = True) -> 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("<I", blob, 0, checksum.main_crc(bytes(blob)))
items.append((it["name"], bytes(blob)))
else:
with open(os.path.join(folder, it["file"]), "rb") as f:
items.append((it["name"], f.read()))
build(items).save(hmi_path)
def main_add_resource(main: bytes, rtype: str, name: str) -> bytes:
"""Return main.HMI with one more resource-list entry (e.g. "pa", "6.pa") and a new checksum."""
start, = struct.unpack_from("<I", main, 4)
count, = struct.unpack_from("<I", main, 28)
b = bytearray(main[:start + 16 * count])
b += rtype.encode("latin-1")[:8].ljust(8, b"\0") + name.encode("latin-1")[:8].ljust(8, b"\0")
struct.pack_into("<I", b, 28, count + 1)
struct.pack_into("<I", b, 0, checksum.main_crc(bytes(b)))
return bytes(b)
def add_page(h: HMIFile, name: str, **attrs) -> 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("<I", main, 4)
count, = struct.unpack_from("<I", main, 28)
ents = [main[start + 16 * i:start + 16 * i + 16] for i in range(count)]
new = rtype.encode("latin-1")[:8].ljust(8, bytes(1)) + name.encode("latin-1")[:8].ljust(8, bytes(1))
pos = count
for i in range(count - 1, -1, -1):
if ents[i][:8] == new[:8]:
pos = i + 1
break
else:
order = ["i", "zi", "pa"]
if rtype in order:
later = order[order.index(rtype) + 1:]
for i, e in enumerate(ents):
if e[:8].rstrip(bytes(1)).decode("latin-1") in later:
pos = i
break
ents.insert(pos, new)
b = bytearray(main[:start]) + b"".join(ents)
struct.pack_into("<I", b, 28, count + 1)
struct.pack_into("<I", b, 0, checksum.main_crc(bytes(b)))
return bytes(b)
def add_picture(h: HMIFile, image_file: bytes) -> 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("<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])
struct.pack_into("<I", b, 16, mid)
struct.pack_into("<I", b, 24, 0x60)
struct.pack_into("<I", b, 28, len(resources))
struct.pack_into("<I", b, 36, 2)
b[0x41] = 3 # Editor 1.68 writes 3 here (0 in 2019 files)
for rtype, name in resources:
b += rtype.encode("latin-1")[:8].ljust(8, bytes(1)) + name.encode("latin-1")[:8].ljust(8, bytes(1))
struct.pack_into("<I", b, 0, checksum.main_crc(bytes(b)))
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."""
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("<I", h.read("main.HMI"), 16)[0]
name = models.BY_ID.get(mid)
return models.MODELS[name][2:4] if name else (480, 320)