openhmi-nx: decode, encode, render Nextion HMI projects; .tft research
Black-box reverse-engineered .HMI format (container, three checksums, pages, all 31 component types, pictures, fonts), readable JSON, page renderer matching Nextion Editor, demo project built from code and a test suite (66 tests). See docs/COVERAGE.md for status. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
commit
69e22cfb06
70 files changed
+25058
No files matched your search
@@ -0,0 +1,172 @@
|
||||
"""The .HMI container: a small file system with a checksummed, duplicated file table.
|
||||
|
||||
Layout (all offsets absolute, little-endian):
|
||||
|
||||
0x000000 file table: count(u32), count * 28-byte entries, then table checksum (u32)
|
||||
0x080000 exact backup copy of the file table (+ checksum)
|
||||
0x380000 u32 0xFFFFFFFF marker
|
||||
0x6FFFF8 b"ver21234"
|
||||
0x700000 entry data, packed back to back
|
||||
|
||||
Entry (28 bytes): name[16] (NUL padded), start(u32), size(u32), deleted(u8), 3 more bytes
|
||||
(not interpreted by us; kept as-is, written as 0 for new entries). A deleted entry also has
|
||||
the first byte of its name set to 0 -- the Editor matches entries by name, so the flag alone
|
||||
is not enough.
|
||||
"""
|
||||
from __future__ import annotations
|
||||
|
||||
import struct
|
||||
from dataclasses import dataclass, field
|
||||
|
||||
from . import checksum
|
||||
|
||||
TABLE_OFFSET = 0x000000
|
||||
BACKUP_TABLE_OFFSET = 0x080000
|
||||
MARKER_OFFSET = 0x380000
|
||||
VERSION_OFFSET = 0x6FFFF8
|
||||
VERSION_MAGIC = b"ver21234"
|
||||
DATA_OFFSET = 0x700000
|
||||
ENTRY_SIZE = 28
|
||||
MAX_TABLE_BYTES = BACKUP_TABLE_OFFSET - TABLE_OFFSET - 4
|
||||
|
||||
|
||||
class HMIError(Exception):
|
||||
pass
|
||||
|
||||
|
||||
@dataclass
|
||||
class Entry:
|
||||
name: str
|
||||
start: int
|
||||
size: int
|
||||
deleted: bool = False
|
||||
extra: bytes = b"\0\0\0" # the 3 trailing entry bytes
|
||||
raw_name: bytes = b"" # name exactly as stored (deleted entries are mangled)
|
||||
|
||||
def pack(self) -> bytes:
|
||||
nm = self.raw_name if self.raw_name else self.name.encode("latin-1")
|
||||
nm = nm[:16].ljust(16, b"\0")
|
||||
if self.deleted:
|
||||
nm = b"\0" + nm[1:]
|
||||
return nm + struct.pack("<IIB", self.start, self.size, 1 if self.deleted else 0) + self.extra[:3].ljust(3, b"\0")
|
||||
|
||||
|
||||
@dataclass
|
||||
class HMIFile:
|
||||
raw: bytearray
|
||||
entries: list[Entry] = field(default_factory=list)
|
||||
|
||||
# ------------------------------------------------------------------ reading
|
||||
@classmethod
|
||||
def load(cls, path) -> "HMIFile":
|
||||
with open(path, "rb") as f:
|
||||
return cls.from_bytes(f.read())
|
||||
|
||||
@classmethod
|
||||
def from_bytes(cls, data: bytes) -> "HMIFile":
|
||||
raw = bytearray(data)
|
||||
entries = cls._read_table(raw, TABLE_OFFSET)
|
||||
if entries is None:
|
||||
entries = cls._read_table(raw, BACKUP_TABLE_OFFSET)
|
||||
if entries is None:
|
||||
raise HMIError("both file tables are corrupt (checksum mismatch)")
|
||||
return cls(raw, entries)
|
||||
|
||||
@staticmethod
|
||||
def _read_table(raw: bytes, base: int):
|
||||
if len(raw) < base + 4:
|
||||
return None
|
||||
count, = struct.unpack_from("<I", raw, base)
|
||||
end = base + 4 + count * ENTRY_SIZE
|
||||
if count > MAX_TABLE_BYTES // ENTRY_SIZE or end + 4 > len(raw):
|
||||
return None
|
||||
stored, = struct.unpack_from("<I", raw, end)
|
||||
if checksum.table_crc(bytes(raw[base:end])) != stored:
|
||||
return None
|
||||
out = []
|
||||
for i in range(count):
|
||||
off = base + 4 + i * ENTRY_SIZE
|
||||
nm, start, size, deleted = struct.unpack_from("<16sIIB", raw, off)
|
||||
extra = bytes(raw[off + 25: off + 28])
|
||||
out.append(Entry(nm.rstrip(b"\0").decode("latin-1"), start, size, bool(deleted), extra, nm))
|
||||
return out
|
||||
|
||||
def live(self) -> list[Entry]:
|
||||
return [e for e in self.entries if not e.deleted]
|
||||
|
||||
def find(self, name: str) -> Entry | None:
|
||||
for e in self.entries:
|
||||
if not e.deleted and e.name == name:
|
||||
return e
|
||||
return None
|
||||
|
||||
def read(self, name: str) -> bytes:
|
||||
e = self.find(name)
|
||||
if e is None:
|
||||
raise KeyError(name)
|
||||
return bytes(self.raw[e.start:e.start + e.size])
|
||||
|
||||
def names(self) -> list[str]:
|
||||
return [e.name for e in self.live()]
|
||||
|
||||
def table_ok(self) -> tuple[bool, bool]:
|
||||
return (self._read_table(self.raw, TABLE_OFFSET) is not None,
|
||||
self._read_table(self.raw, BACKUP_TABLE_OFFSET) is not None)
|
||||
|
||||
# ------------------------------------------------------------------ writing
|
||||
def write(self, name: str, data: bytes) -> None:
|
||||
"""Replace (or add) an entry the way the Editor does: append the data at the end of the
|
||||
file, mark the old entry deleted, add a new entry. Call fix_checksums()/save() after."""
|
||||
old = self.find(name)
|
||||
start = len(self.raw)
|
||||
self.raw += data
|
||||
if old is not None:
|
||||
old.deleted = True
|
||||
self.entries.append(Entry(name, start, len(data)))
|
||||
|
||||
def delete(self, name: str) -> None:
|
||||
e = self.find(name)
|
||||
if e is None:
|
||||
raise KeyError(name)
|
||||
e.deleted = True
|
||||
|
||||
def _table_bytes(self) -> bytes:
|
||||
return struct.pack("<I", len(self.entries)) + b"".join(e.pack() for e in self.entries)
|
||||
|
||||
def _store_tables(self) -> None:
|
||||
tbl = self._table_bytes()
|
||||
if len(tbl) > MAX_TABLE_BYTES:
|
||||
raise HMIError("file table too large")
|
||||
blob = tbl + struct.pack("<I", checksum.table_crc(tbl))
|
||||
for base in (TABLE_OFFSET, BACKUP_TABLE_OFFSET):
|
||||
# clear the old table area (old one may have been longer)
|
||||
old_count, = struct.unpack_from("<I", self.raw, base)
|
||||
old_len = min(4 + old_count * ENTRY_SIZE + 4, MAX_TABLE_BYTES)
|
||||
self.raw[base:base + max(old_len, len(blob))] = bytes(max(old_len, len(blob)))
|
||||
self.raw[base:base + len(blob)] = blob
|
||||
|
||||
def to_bytes(self) -> bytes:
|
||||
self._store_tables()
|
||||
return bytes(self.raw)
|
||||
|
||||
def save(self, path) -> None:
|
||||
with open(path, "wb") as f:
|
||||
f.write(self.to_bytes())
|
||||
|
||||
def compacted(self) -> "HMIFile":
|
||||
"""A fresh file containing only the live entries, packed from DATA_OFFSET."""
|
||||
return build([(e.name, self.read(e.name)) for e in self.live()])
|
||||
|
||||
|
||||
def build(items: list[tuple[str, bytes]]) -> HMIFile:
|
||||
"""Create a new .HMI container from (name, data) pairs, in the given order."""
|
||||
raw = bytearray(DATA_OFFSET)
|
||||
struct.pack_into("<I", raw, MARKER_OFFSET, 0xFFFFFFFF)
|
||||
raw[VERSION_OFFSET:VERSION_OFFSET + 8] = VERSION_MAGIC
|
||||
entries = []
|
||||
for name, data in items:
|
||||
entries.append(Entry(name, len(raw), len(data)))
|
||||
raw += data
|
||||
f = HMIFile(raw, entries)
|
||||
f._store_tables()
|
||||
return f
|
||||
Reference in new issue
Block a user