nextion-tools 0.1.0__py3-none-any.whl

nextion_tools/__init__.py

@@ -0,0 +1,14 @@
+"""Tools for Nextion HMI displays: the Editor's project files and the display itself.
+
+- `nextion_tools.hmi`: .HMI projects: pages, components, ids, geometry, event code, Program.s;
+  numeric edits and re-stamping
+- `nextion_tools.fonts`: .zi fonts: glyph bitmaps and metrics (numpy)
+- `nextion_tools.images`: pictures as RGB arrays, RGB565 (numpy, Pillow)
+- `nextion_tools.tft`: a compiled .tft's picture table, checksums and orientation
+- `nextion_tools.crc`: the CRC behind TFT checksums and HMI stamps
+- `nextion_tools.render`: draw a page as the display shows it (numpy, Pillow)
+- `nextion_tools.emu`: an emulated display, driven by an HMI, for testing MCU firmware, with a
+  browser viewer (`nextion_tools.emu.viewer`)
+"""
+
+__version__ = "0.1.0"

nextion_tools/crc.py

@@ -0,0 +1,26 @@
+"""The CRC behind TFT checksums and HMI page stamps.
+
+Both are CRC-32/MPEG-2 (poly 0x04C11DB7, MSB first, init 0xFFFFFFFF, no final XOR) over the
+data with each byte widened to a big-endian 32-bit word, which is how an STM32's CRC unit
+checksums a byte stream. See https://github.com/UNUF/TFTTool for the TFT side.
+"""
+import zlib
+
+_REVERSED = bytes(int(f'{i:08b}'[::-1], 2) for i in range(256))
+
+
+def crc32_mpeg2(data):
+    """CRC-32/MPEG-2. zlib computes the bit-reflected CRC-32 with the same polynomial, so this is
+    zlib's CRC of the bit-reversed input, bit-reversed, without zlib's final XOR."""
+    return int(f'{zlib.crc32(data.translate(_REVERSED)) ^ 0xFFFFFFFF:032b}'[::-1], 2)
+
+
+def widen(data):
+    """Each byte as a big-endian 32-bit word."""
+    words = bytearray(4 * len(data))
+    words[3::4] = data
+    return bytes(words)
+
+
+def nextion(data):
+    return crc32_mpeg2(widen(data))

nextion_tools/emu/__init__.py

@@ -0,0 +1,16 @@
+"""An emulated Nextion display, for testing the firmware that drives one. See display.py."""
+
+from .clock import ManualClock
+from .devices import NX4832T035, Device
+from .display import COMOK, REDRAW_S, Display
+from .flow import FlowModel
+from .model import Screen
+from .script import ScriptError, ScriptSyntaxError, UnsupportedCode
+from .transport import NotConnected, Pty, Serial, SocketTransport, TcpServer, Transport
+from .upload import Upload
+
+__all__ = [
+    "COMOK", "REDRAW_S", "Device", "Display", "NX4832T035", "FlowModel", "ManualClock", "NotConnected", "Screen", "ScriptError",
+    "ScriptSyntaxError", "UnsupportedCode", "Pty", "Serial", "SocketTransport",
+    "TcpServer", "Transport", "Upload",
+]

nextion_tools/emu/__main__.py

@@ -0,0 +1,55 @@
+"""Run an emulated display and log what it is sent.
+
+  python -m nextion_tools.emu --tcp 4000          # listen; e.g. qemu ... -serial tcp:127.0.0.1:4000
+  python -m nextion_tools.emu --pty               # prints the pty to point a program at
+  python -m nextion_tools.emu --serial /dev/ttyUSB0
+  python -m nextion_tools.emu --tcp 4000 --hmi gui.HMI   # the project's pages and code
+"""
+
+import argparse
+import logging
+import time
+
+from .display import Display
+from ..hmi import Project
+from .protocol import TERMINATOR
+from .transport import Pty, Serial, TcpServer
+
+
+def main(argv=None) -> None:
+    parser = argparse.ArgumentParser(prog="python -m nextion_tools.emu", description=__doc__.split("\n")[0])
+    where = parser.add_mutually_exclusive_group(required=True)
+    where.add_argument("--tcp", type=int, metavar="PORT", help="listen on 127.0.0.1:PORT (0 picks one)")
+    where.add_argument("--pty", action="store_true", help="create a pseudo-terminal")
+    where.add_argument("--serial", metavar="DEVICE", help="use a serial port (needs pyserial)")
+    parser.add_argument("--baud", type=int, default=115200)
+    parser.add_argument("--flow", action="store_true", help="model the input buffer and stalls")
+    parser.add_argument("--banner", default="", help="a frame the TFT prints when it starts, e.g. NSPM")
+    parser.add_argument("--hmi", help="the project's .HMI: its pages, ids and code")
+    args = parser.parse_args(argv)
+
+    logging.basicConfig(level=logging.DEBUG, format="%(asctime)s %(name)s %(message)s")
+    if args.tcp is not None:
+        transport = TcpServer(port=args.tcp)
+        print("listening on %s:%d" % (transport.host, transport.port), flush=True)
+    elif args.pty:
+        transport = Pty()
+        print("pty: %s" % transport.path, flush=True)
+    else:
+        transport = Serial(args.serial, args.baud)
+    banner = args.banner.encode() + TERMINATOR if args.banner else b""
+    display = Display(transport, flow_model=args.flow, baud=args.baud, banner=banner,
+                      hmi=Project.load(args.hmi) if args.hmi else None)
+    try:
+        # Power on (the banner, Program.s) once the MCU is there to hear it.
+        while not display.connected:
+            time.sleep(0.1)
+        display.boot()
+        while True:
+            time.sleep(1)
+    except KeyboardInterrupt:
+        display.close()
+
+
+if __name__ == "__main__":
+    main()

nextion_tools/emu/clock.py

@@ -0,0 +1,23 @@
+"""A clock a test moves by hand, for timers that must fire exactly when the test says.
+
+    clock = ManualClock()
+    display = Display(..., hmi=hmi, clock=clock)
+    clock.advance(0.05)
+    display.tick()          # runs whatever is now due
+"""
+
+import threading
+
+
+class ManualClock:
+    def __init__(self, start: float = 1000.0):
+        self._now = start
+        self._lock = threading.Lock()
+
+    def __call__(self) -> float:
+        with self._lock:
+            return self._now
+
+    def advance(self, seconds: float) -> None:
+        with self._lock:
+            self._now += seconds

nextion_tools/emu/devices.py

@@ -0,0 +1,29 @@
+"""What differs between Nextion display models, as measured on each.
+
+A Device holds the numbers the emulator needs that belong to the display, not to the project it
+runs or the MCU that drives it. Only one model has been measured so far. Another gets its own
+profile once someone measures it: replay the probes in tests/emu/test_calibration.py against
+the real display and record what it does.
+"""
+
+from dataclasses import dataclass
+
+
+@dataclass(frozen=True)
+class Device:
+    model: str
+    comok: bytes  # the reply to `connect`, without its terminator
+    flash_size: int  # bytes, for TFT uploads
+    buffer_capacity: int  # bytes of input the display holds before it drops what arrives
+    redraw_s: float  # how long a full-page redraw (`page`, `ref`) blocks the next instruction
+
+
+# The Sonoff NSPanel's display, measured on a panel ("Office") 2026-10-23/24: the input buffer
+# held 1080-1092 bytes, and a page change blocked the next instruction for about 400 ms.
+NX4832T035 = Device(
+    model="NX4832T035_011R",
+    comok=b"comok 2,30614-0,NX4832T035_011R,163,61488,D264B8204F0E1828,16777216",
+    flash_size=16777216,
+    buffer_capacity=1088,
+    redraw_s=0.4,
+)