tft: firmware files from a local firmware/ folder, checked by SHA-256

Nextion's seven firmware files cannot be in the repo, so the repo now
ships their SHA-256 hashes (src/nxhmi/firmware.sha256, Editor
1.68.2.3035) and every build checks the files against them. The files
live in the git-ignored firmware/ folder; `nxhmi firmware --from
<Editor folder>` copies them, `nxhmi firmware` reports ok / missing /
wrong hash. build-tft and the MCP tool take --firmware-dir /
firmware_dir (also NXHMI_FIRMWARE_DIR) instead of the Editor folder.

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
This commit is contained in:
mangavalkandClaude Opus 5.5 committed 2026-11-16 23:47:16 +01:00
1 parent 0287cf21e4
commit 85422a1ef4
14 files changed
+259 -44

No files matched your search

+3 -1
View File
@@ -40,7 +40,9 @@ Back up the user's file first (copy it) unless they said not to; edits write in
- `build_tft` compiles to `.tft` without the Editor's compiler, but only for model NX4832T035 and a - `build_tft` compiles to `.tft` without the Editor's compiler, but only for model NX4832T035 and a
small subset (pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts, small subset (pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts,
plain script); it says plain script); it says
what it cannot compile. It needs the Editor's install folder for the firmware files. Its what it cannot compile. It needs Nextion's seven firmware files in the repo's `firmware/` folder
(git-ignored; the user copies them with `nxhmi firmware --from "<Editor folder>"`). Each build
checks them against `src/nxhmi/firmware.sha256` and refuses missing or other-version files. Its
output is byte-identical to the Editor's for the test projects but has never been loaded onto output is byte-identical to the Editor's for the test projects but has never been loaded onto
a display -- tell the user, and never upload it yourself. a display -- tell the user, and never upload it yourself.
- Pictures: `add_picture` returns an id for `pic` / `picc` (crop) / `pic2` etc. Works for Basic - Pictures: `add_picture` returns an id for `pic` / `picc` (crop) / `pic2` etc. Works for Basic
+3
View File
@@ -10,3 +10,6 @@ dist/
# ...except our own demo and its Editor re-save (test fixture) # ...except our own demo and its Editor re-save (test fixture)
!demo/demo.HMI !demo/demo.HMI
!tests/fixtures/demo_editor_saved.HMI !tests/fixtures/demo_editor_saved.HMI
# Nextion firmware files for the .tft builder: copied from your own Editor, never committed
firmware/*
!firmware/README.md
+9 -3
View File
@@ -19,7 +19,10 @@ src/nxhmi/
fonts.py .zi v6 fonts, generation from TrueType fonts.py .zi v6 fonts, generation from TrueType
render.py page renderer matching the Editor canvas render.py page renderer matching the Editor canvas
tft.py .tft helpers (layout table, header checksums, trailer, seal, name hash) tft.py .tft helpers (layout table, header checksums, trailer, seal, name hash)
tft_build.py .HMI -> .tft builder (subset; firmware files come from the user's Editor folder) tft_build.py .HMI -> .tft builder (subset)
firmware.py Nextion's firmware files for the builder: load from firmware/, SHA-256 check
firmware.sha256 expected hashes (Editor 1.68.2.3035), in .tft order
firmware/ git-ignored except README.md: the user's copies of Nextion's firmware files
tft_code.py Nextion script -> tokenised chunks tft_code.py Nextion script -> tokenised chunks
cli.py python -m nxhmi ... cli.py python -m nxhmi ...
mcp_server.py MCP server (stdio JSON-RPC, no deps) -- tools for Claude incl. render_page images mcp_server.py MCP server (stdio JSON-RPC, no deps) -- tools for Claude incl. render_page images
@@ -48,7 +51,9 @@ that, re-save the demo with Nextion Editor (open, File > Save As) and replace th
All findings and the fixture come from **Nextion Editor 1.68.2.3035** (`nxhmi.TESTED_EDITOR_VERSION`). All findings and the fixture come from **Nextion Editor 1.68.2.3035** (`nxhmi.TESTED_EDITOR_VERSION`).
When verifying against a different Editor build, say so in the commit and in docs/NOTES.md; if a When verifying against a different Editor build, say so in the commit and in docs/NOTES.md; if a
new build writes different bytes, document the difference in docs/FORMAT.md per version and bump new build writes different bytes, document the difference in docs/FORMAT.md per version and bump
`TESTED_EDITOR_VERSION` only after the fixture is re-saved and all tests pass. `TESTED_EDITOR_VERSION` only after the fixture is re-saved and all tests pass. A new Editor build
also ships new firmware files: update `src/nxhmi/firmware.sha256` only together with re-measured
`.tft` samples.
## Rules ## Rules
@@ -56,7 +61,8 @@ new build writes different bytes, document the difference in docs/FORMAT.md per
files, or by asking the Editor whether a hand-made file loads. Never decompile, decrypt or files, or by asking the Editor whether a hand-made file loads. Never decompile, decrypt or
patch Nextion software. patch Nextion software.
- **Never commit Nextion's files**: no `.tft` output (it embeds Nextion firmware), nothing from - **Never commit Nextion's files**: no `.tft` output (it embeds Nextion firmware), nothing from
the Editor's install folder, no third-party projects. Test data is generated (`examples/`) or the Editor's install folder (local copies live in the git-ignored `firmware/`; only their
hashes are committed), no third-party projects. Test data is generated (`examples/`) or
is our own demo re-saved by the Editor. is our own demo re-saved by the Editor.
- Every format claim in `docs/FORMAT.md` needs evidence (byte-identical Editor output, or the - Every format claim in `docs/FORMAT.md` needs evidence (byte-identical Editor output, or the
Editor accepting a file we wrote). Mark guesses as **OPEN**. Editor accepting a file we wrote). Mark guesses as **OPEN**.
+16 -1
View File
@@ -37,7 +37,22 @@ Every percentage is a count with a stated basis, so it can be checked (details i
Research stage. The goal is output byte-identical to Nextion Editor's; anything not measured is Research stage. The goal is output byte-identical to Nextion Editor's; anything not measured is
refused with the reason instead of guessed. Checked against 84 Editor-compiled sample projects. refused with the reason instead of guessed. Checked against 84 Editor-compiled sample projects.
The firmware files inside every `.tft` are read from your own Editor installation at build time.
**Firmware files (needed once, not in this repo).** Every `.tft` embeds seven of Nextion's own
firmware files (`input.bin`, `asp0.dll`, `cd0.dll`, `qr0.bin`, `syscom.bin`, `h0-0.dll`,
`h1-0.dll`). They are Nextion's property, so this repo cannot include them. Copy them from your
own Nextion Editor installation into the repo's [`firmware/`](firmware/README.md) folder, which git
ignores:
```
python -m nxhmi firmware --from "C:\Program Files (x86)\Nextion Editor"
```
Because the files cannot be shipped, the repo ships their SHA-256 hashes instead
([`src/nxhmi/firmware.sha256`](src/nxhmi/firmware.sha256), from Nextion Editor 1.68.2.3035). Every
build checks the files against these hashes first, and refuses missing files or files from another
Editor version. `python -m nxhmi firmware` shows the state per file. Use `--firmware-dir` or
`NXHMI_FIRMWARE_DIR` to keep them elsewhere.
| Sub-goal | Status | Basis | | Sub-goal | Status | Basis |
|---|---|---| |---|---|---|
+1 -1
View File
@@ -116,7 +116,7 @@ byte for byte, or a file written by nxhmi was opened in the Editor and showed th
| Compiled page format | structure solved (code blob, name hashes, RAM image, attribute records, page table, object records -- FORMAT.md 7.3-7.5); 13 of 20 Basic types in `nxhmi.tft_types` (page, hotspot, text, number, button, picture, crop, progress bar, checkbox, radio, int variable, timer, touch cap; variants and limits in the README table); missing: slider, dual-state button, float, scrolling text, gauge, waveform, QR code | | Compiled page format | structure solved (code blob, name hashes, RAM image, attribute records, page table, object records -- FORMAT.md 7.3-7.5); 13 of 20 Basic types in `nxhmi.tft_types` (page, hotspot, text, number, button, picture, crop, progress bar, checkbox, radio, int variable, timer, touch cap; variants and limits in the README table); missing: slider, dual-state button, float, scrolling text, gauge, waveform, QR code |
| Event-code tokens | solved for what was sampled (FORMAT.md 7.6): 27 commands, 33 system variables/colours, numbers, global variables, attribute references, if/else/while/for. Not sampled: string functions and attributes, the remaining commands and system variables, `>=` op code | | Event-code tokens | solved for what was sampled (FORMAT.md 7.6): 27 commands, 33 system variables/colours, numbers, global variables, attribute references, if/else/while/for. Not sampled: string functions and attributes, the remaining commands and system variables, `>=` op code |
| Builder (`nxhmi build-tft`) | byte-identical to the Editor for the supported subset (one model: NX4832T035); refuses anything else. **Never tested on a real display** | | Builder (`nxhmi build-tft`) | byte-identical to the Editor for the supported subset (one model: NX4832T035); refuses anything else. **Never tested on a real display** |
| Licensing | every `.tft` embeds Nextion's firmware files; the repo must never ship them -- a builder would read them from the user's own Editor installation | | Licensing | every `.tft` embeds Nextion's firmware files; the repo must never ship them. The user copies them from their own Editor into the git-ignored `firmware/` folder (`nxhmi firmware --from ...`); the repo ships only their SHA-256 hashes, checked before every build |
## Suggested next steps ## Suggested next steps
1. `.tft`: script token table, then component types one at a time (see NOTES.md); a second display model. 1. `.tft`: script token table, then component types one at a time (see NOTES.md); a second display model.
+28
View File
@@ -0,0 +1,28 @@
# Nextion firmware files (not in the repo)
Every `.tft` that Nextion Editor compiles embeds seven of Nextion's own firmware files. They are
Nextion's property, so this repo cannot ship them. To use `nxhmi build-tft`, copy them from your
own Nextion Editor installation into **this folder**. Git ignores everything here except this
README.
| File | |
|---|---|
| `input.bin`, `asp0.dll`, `cd0.dll`, `qr0.bin`, `syscom.bin`, `h0-0.dll`, `h1-0.dll` | from the Editor's install folder, usually `C:\Program Files (x86)\Nextion Editor` |
The `.dll` files are display firmware pieces, not Windows libraries.
Copy and check them in one step:
```
python -m nxhmi firmware --from "C:\Program Files (x86)\Nextion Editor"
python -m nxhmi firmware # check only: ok / missing / wrong hash per file
```
The builder checks every file against its SHA-256 in
[`src/nxhmi/firmware.sha256`](../src/nxhmi/firmware.sha256) before each build. The hashes belong to
**Nextion Editor 1.68.2.3035**, the version the builder was measured against. Files from another
Editor version are refused: they differ, and the output would no longer match what the Editor
produces. To check by hand: `cd firmware && sha256sum -c ../src/nxhmi/firmware.sha256`.
To keep the files elsewhere, pass `--firmware-dir <folder>` to `build-tft` or set
`NXHMI_FIRMWARE_DIR`.
+1 -1
View File
@@ -17,7 +17,7 @@ nxhmi = "nxhmi.cli:main"
where = ["src"] where = ["src"]
[tool.setuptools.package-data] [tool.setuptools.package-data]
nxhmi = ["*.json"] nxhmi = ["*.json", "firmware.sha256"]
[project.optional-dependencies] [project.optional-dependencies]
images = ["pillow>=10.1"] images = ["pillow>=10.1"]
+23 -4
View File
@@ -172,11 +172,11 @@ def cmd_dump(a):
def cmd_build_tft(a): def cmd_build_tft(a):
from . import tft_build from . import tft_build
try: try:
out = tft_build.build_tft(HMIFile.load(a.hmi), a.editor_dir) out = tft_build.build_tft(HMIFile.load(a.hmi), a.firmware_dir)
except tft_build.Unsupported as e: except tft_build.Unsupported as e:
print("error: cannot compile yet:", e, file=sys.stderr) print("error: cannot compile yet:", e, file=sys.stderr)
return 3 return 3
except FileNotFoundError as e: except (tft_build.FirmwareError, FileNotFoundError) as e:
print("error:", e, file=sys.stderr) print("error:", e, file=sys.stderr)
return 2 return 2
with open(a.tft, "wb") as fh: with open(a.tft, "wb") as fh:
@@ -184,6 +184,20 @@ def cmd_build_tft(a):
print("wrote %s (%d bytes)" % (a.tft, len(out))) print("wrote %s (%d bytes)" % (a.tft, len(out)))
def cmd_firmware(a):
from . import firmware
try:
st = firmware.copy_from(a.source, a.firmware_dir) if a.source else firmware.status(a.firmware_dir)
except firmware.FirmwareError as e:
print("error:", e, file=sys.stderr)
return 2
print("firmware folder: %s (expected: Nextion Editor %s)" % (a.firmware_dir or firmware.DEFAULT_DIR,
firmware.TESTED_EDITOR_VERSION))
for name, state in st.items():
print(" %-11s %s" % (name, state))
return 0 if all(v == "ok" for v in st.values()) else 2
def cmd_tft_info(a): def cmd_tft_info(a):
from . import tft from . import tft
with open(a.tft, "rb") as fh: with open(a.tft, "rb") as fh:
@@ -237,9 +251,14 @@ def main(argv=None):
s = sub.add_parser("dump", help="print pages as JSON"); s.add_argument("hmi"); s.add_argument("--page") s = sub.add_parser("dump", help="print pages as JSON"); s.add_argument("hmi"); s.add_argument("--page")
s.add_argument("--encoding", default="latin-1"); s.add_argument("--raw", action="store_true"); s.set_defaults(f=cmd_dump) s.add_argument("--encoding", default="latin-1"); s.add_argument("--raw", action="store_true"); s.set_defaults(f=cmd_dump)
s = sub.add_parser("build-tft", help="compile to .tft (research stage: NX4832T035, few component types; " s = sub.add_parser("build-tft", help="compile to .tft (research stage: NX4832T035, few component types; "
"needs a Nextion Editor installation for the firmware files)") "needs Nextion's firmware files in firmware/, see 'nxhmi firmware')")
s.add_argument("hmi"); s.add_argument("tft") s.add_argument("hmi"); s.add_argument("tft")
s.add_argument("--editor-dir", default=r"C:\Program Files (x86)\Nextion Editor"); s.set_defaults(f=cmd_build_tft) s.add_argument("--firmware-dir", help="folder with Nextion's firmware files (default: firmware/ in the repo)")
s.set_defaults(f=cmd_build_tft)
s = sub.add_parser("firmware", help="check the firmware files the .tft builder needs (SHA-256), or copy "
"them from your Nextion Editor folder with --from")
s.add_argument("--from", dest="source", metavar="EDITOR_DIR", help=r'e.g. "C:\Program Files (x86)\Nextion Editor"')
s.add_argument("--firmware-dir", help="target folder (default: firmware/ in the repo)"); s.set_defaults(f=cmd_firmware)
s = sub.add_parser("tft-info", help="header fields, layout table and checksum status of a .tft") s = sub.add_parser("tft-info", help="header fields, layout table and checksum status of a .tft")
s.add_argument("tft"); s.set_defaults(f=cmd_tft_info) s.add_argument("tft"); s.set_defaults(f=cmd_tft_info)
a = ap.parse_args(argv) a = ap.parse_args(argv)
+90
View File
@@ -0,0 +1,90 @@
"""Nextion's firmware files that every .tft embeds (see docs/FORMAT.md section 7).
They are Nextion's property, so the repo cannot ship them. The user copies them from their own
Nextion Editor installation into ``firmware/`` at the repo root (git-ignored), or passes another
folder. Before a build every file is checked against the SHA-256 in ``firmware.sha256`` (taken from
Nextion Editor 1.68.2.3035, the version the builder was measured against): a different Editor
version has different files, and the output would no longer be what that version produces.
"""
from __future__ import annotations
import hashlib
import os
import shutil
from . import TESTED_EDITOR_VERSION
_HERE = os.path.dirname(os.path.abspath(__file__))
MANIFEST = os.path.join(_HERE, "firmware.sha256")
#: ``$NXHMI_FIRMWARE_DIR`` if set, else ``firmware/`` at the repo root (src/nxhmi/../../firmware)
DEFAULT_DIR = os.environ.get("NXHMI_FIRMWARE_DIR") or os.path.normpath(os.path.join(_HERE, "..", "..", "firmware"))
DEFAULT_EDITOR_DIR = r"C:\Program Files (x86)\Nextion Editor"
class FirmwareError(Exception):
"""A firmware file is missing or is not the expected version."""
def expected_hashes() -> dict[str, str]:
"""File name -> SHA-256 (hex), in the order the files are stored in a .tft."""
out = {}
with open(MANIFEST, encoding="ascii") as fh:
for line in fh:
if line.strip():
digest, name = line.split(None, 1)
out[name.strip().lstrip("*")] = digest.lower()
return out
FILES = tuple(expected_hashes())
def _missing(folder: str, name: str) -> FirmwareError:
return FirmwareError(
"Nextion firmware file not found: %s\nCopy the files %s from your Nextion Editor %s "
"installation (usually %s) into %s -- or run: nxhmi firmware --from \"<Editor folder>\""
% (os.path.join(folder, name), ", ".join(FILES), TESTED_EDITOR_VERSION, DEFAULT_EDITOR_DIR, folder))
def load(folder: str | None = None) -> list[bytes]:
"""Read and verify the firmware files; raise FirmwareError if one is missing or differs."""
folder = folder or DEFAULT_DIR
out = []
for name, digest in expected_hashes().items():
path = os.path.join(folder, name)
if not os.path.isfile(path):
raise _missing(folder, name)
with open(path, "rb") as fh:
data = fh.read()
if hashlib.sha256(data).hexdigest() != digest:
raise FirmwareError(
"%s does not match the expected SHA-256 (%s): it is not the file from Nextion Editor %s, "
"which the .tft builder was measured against" % (path, digest, TESTED_EDITOR_VERSION))
out.append(data)
return out
def status(folder: str | None = None) -> dict[str, str]:
"""File name -> 'ok', 'missing' or 'wrong hash'."""
folder = folder or DEFAULT_DIR
out = {}
for name, digest in expected_hashes().items():
path = os.path.join(folder, name)
if not os.path.isfile(path):
out[name] = "missing"
continue
with open(path, "rb") as fh:
out[name] = "ok" if hashlib.sha256(fh.read()).hexdigest() == digest else "wrong hash"
return out
def copy_from(editor_dir: str, folder: str | None = None) -> dict[str, str]:
"""Copy the firmware files from a Nextion Editor folder, then return status()."""
folder = folder or DEFAULT_DIR
for name in FILES:
if not os.path.isfile(os.path.join(editor_dir, name)):
raise _missing(editor_dir, name)
os.makedirs(folder, exist_ok=True)
for name in FILES:
shutil.copyfile(os.path.join(editor_dir, name), os.path.join(folder, name))
return status(folder)
+7
View File
@@ -0,0 +1,7 @@
34a2f19b8800c13ec13284e7db609012f46e70e68c08be00c2c20a395eb49304 input.bin
17fad8f35e61f91cc16332512113b438fb7d2f0447c70120e361fb033fde2ec9 asp0.dll
38b4d19cf15b626ec92e164b006ec782adf518b545a7dad953b6423f7a5cc3f8 cd0.dll
6750f8762fab464d45af4ab4d42ce565dd549af3f8b74a03127d6a4411e8ee27 qr0.bin
9276fdc48ad6e3676be5e4a1b68acb2b954253f18d6bc6a2dad31edbdc54590f syscom.bin
287d9b321491a29074491200174a543b340ac863aed8a707d7a82466979dbd39 h0-0.dll
f97b6206a6e3d784c2851f303fc29c5816309736b3fd4adc5f250cf8fa2196db h1-0.dll
+8 -5
View File
@@ -158,12 +158,14 @@ def t_add_picture(path, image_path, quality=100):
return {"picture_id": pid} return {"picture_id": pid}
def t_build_tft(path, tft_path, editor_dir=None): def t_build_tft(path, tft_path, firmware_dir=None):
from . import tft_build from . import tft_build
try: try:
out = tft_build.build_tft(_load(path), editor_dir or tft_build.DEFAULT_EDITOR_DIR) out = tft_build.build_tft(_load(path), firmware_dir)
except tft_build.Unsupported as e: except tft_build.Unsupported as e:
raise ValueError("cannot compile this project yet: %s" % e) raise ValueError("cannot compile this project yet: %s" % e)
except tft_build.FirmwareError as e:
raise ValueError(str(e))
with open(tft_path, "wb") as f: with open(tft_path, "wb") as f:
f.write(out) f.write(out)
return {"tft": tft_path, "bytes": len(out)} return {"tft": tft_path, "bytes": len(out)}
@@ -261,9 +263,10 @@ TOOLS = {
{"path": S, "height": {"type": "integer"}, "ttf_path": S, "encoding": S, "chars": S}, ["path", "height"]), {"path": S, "height": {"type": "integer"}, "ttf_path": S, "encoding": S, "chars": S}, ["path", "height"]),
"build_tft": (t_build_tft, "Compile the project to a .tft firmware file. Research stage: model NX4832T035 only; " "build_tft": (t_build_tft, "Compile the project to a .tft firmware file. Research stage: model NX4832T035 only; "
"pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts and plain script; anything else is " "pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts and plain script; anything else is "
"refused with the reason. Needs a Nextion Editor installation (editor_dir) for the firmware " "refused with the reason. Needs Nextion's firmware files from the user's own Editor in the repo's "
"files. The output has never been tried on a real display.", "firmware/ folder (or firmware_dir), checked by SHA-256; 'nxhmi firmware --from <Editor folder>' "
{"path": S, "tft_path": S, "editor_dir": S}, ["path", "tft_path"]), "copies them. The output has never been tried on a real display.",
{"path": S, "tft_path": S, "firmware_dir": S}, ["path", "tft_path"]),
"verify": (t_verify, "Check every checksum in the project.", {"path": S}, ["path"]), "verify": (t_verify, "Check every checksum in the project.", {"path": S}, ["path"]),
"list_kinds": (t_kinds, "Component kinds that can be added.", {}, []), "list_kinds": (t_kinds, "Component kinds that can be added.", {}, []),
"schema": (t_schema, "Attributes of a component kind: names, types, defaults, allowed values.", {"kind": S}, ["kind"]), "schema": (t_schema, "Attributes of a component kind: names, types, defaults, allowed values.", {"kind": S}, ["kind"]),
+10 -15
View File
@@ -1,25 +1,24 @@
"""Build a .tft from a .HMI project -- research stage. See docs/FORMAT.md section 7. """Build a .tft from a .HMI project -- research stage. See docs/FORMAT.md section 7.
What is reproduced byte for byte (Nextion Editor 1.68.2, model NX4832T035): header, resource What is reproduced byte for byte (Nextion Editor 1.68.2, model NX4832T035): header, resource
area (the firmware files are read from the user's own Editor installation; pictures, fonts), page area (the firmware files come from the user's own Editor, see :mod:`nxhmi.firmware`; pictures, fonts), page
section for the component types in :mod:`nxhmi.tft_types` and the script subset in section for the component types in :mod:`nxhmi.tft_types` and the script subset in
:mod:`nxhmi.tft_code`, layout table and all checksums. Anything else raises :mod:`nxhmi.tft_code`, layout table and all checksums. Anything else raises
:class:`Unsupported` -- never a guess. :class:`Unsupported` -- never a guess.
""" """
from __future__ import annotations from __future__ import annotations
import os
import re import re
import struct import struct
from . import tft, tft_code, tft_types from . import firmware, tft, tft_code, tft_types
from .checksum import word_per_byte_crc from .checksum import word_per_byte_crc
from .container import HMIFile from .container import HMIFile
from .page import Page from .page import Page
from .tft_code import Unsupported from .tft_code import Unsupported
FIRMWARE_FILES = ("input.bin", "asp0.dll", "cd0.dll", "qr0.bin", "syscom.bin", "h0-0.dll", "h1-0.dll") FIRMWARE_FILES = firmware.FILES
DEFAULT_EDITOR_DIR = r"C:\Program Files (x86)\Nextion Editor" FirmwareError = firmware.FirmwareError
SUPPORTED_MODEL = 0xB23BC018 # NX4832T035_011, the only model measured SUPPORTED_MODEL = 0xB23BC018 # NX4832T035_011, the only model measured
BLOCK = 0x10000 BLOCK = 0x10000
_RECT = ("x", "y", "w", "h", "endx", "endy") _RECT = ("x", "y", "w", "h", "endx", "endy")
@@ -32,7 +31,7 @@ def _chunk(b: bytes) -> bytes:
return struct.pack("<I", len(b)) + b return struct.pack("<I", len(b)) + b
def resource_area(hmi: HMIFile, editor_dir: str) -> tuple[bytes, dict]: def resource_area(hmi: HMIFile, firmware_dir: str | None = None) -> tuple[bytes, dict]:
"""Directory + firmware files + pictures + fonts, zero-padded to a 64 KB multiple.""" """Directory + firmware files + pictures + fonts, zero-padded to a 64 KB multiple."""
def numbered(ext): def numbered(ext):
names = [n for n in hmi.names() if re.fullmatch(r"\d+\." + ext, n)] names = [n for n in hmi.names() if re.fullmatch(r"\d+\." + ext, n)]
@@ -50,13 +49,7 @@ def resource_area(hmi: HMIFile, editor_dir: str) -> tuple[bytes, dict]:
o += len(b) - head o += len(b) - head
return b"".join(heads) + b"".join(datas) return b"".join(heads) + b"".join(datas)
parts = [] parts = firmware.load(firmware_dir) # SHA-256 checked against firmware.sha256
for n in FIRMWARE_FILES:
p = os.path.join(editor_dir, n)
if not os.path.exists(p):
raise FileNotFoundError("Nextion Editor file not found: %s (pass the Editor install folder)" % p)
with open(p, "rb") as fh:
parts.append(fh.read())
pics, fonts = numbered("i"), numbered("zi") pics, fonts = numbered("i"), numbered("zi")
parts += [packed(pics, 24, 8, 4), packed(fonts, 44, 0x18)] parts += [packed(pics, 24, 8, 4), packed(fonts, 44, 0x18)]
directory, o = bytearray(0x90), 0x90 directory, o = bytearray(0x90), 0x90
@@ -296,7 +289,9 @@ def compile_pages(pages: list[Page], program: str, nfonts: int = 0, npics: int =
return bytes(blob), descriptors, bytes(records), ptable, bytes(objects), program_off return bytes(blob), descriptors, bytes(records), ptable, bytes(objects), program_off
def build_tft(hmi: HMIFile, editor_dir: str = DEFAULT_EDITOR_DIR) -> bytes: def build_tft(hmi: HMIFile, firmware_dir: str | None = None) -> bytes:
"""Compile ``hmi``. ``firmware_dir`` holds Nextion's firmware files (default: ``firmware/`` at
the repo root); each is checked against its SHA-256 first (FirmwareError if missing or wrong)."""
main = hmi.read("main.HMI") main = hmi.read("main.HMI")
model, = struct.unpack_from("<I", main, 16) model, = struct.unpack_from("<I", main, 16)
if model != SUPPORTED_MODEL: if model != SUPPORTED_MODEL:
@@ -310,7 +305,7 @@ def build_tft(hmi: HMIFile, editor_dir: str = DEFAULT_EDITOR_DIR) -> bytes:
count = lambda ext: sum(1 for x in hmi.names() if re.fullmatch(r"\d+\." + ext, x)) # noqa: E731 count = lambda ext: sum(1 for x in hmi.names() if re.fullmatch(r"\d+\." + ext, x)) # noqa: E731
blob, descriptors, records, ptable, objects, program_off = compile_pages( blob, descriptors, records, ptable, objects, program_off = compile_pages(
pages, hmi.read("Program.s").decode("latin-1"), count("zi"), count("i")) pages, hmi.read("Program.s").decode("latin-1"), count("zi"), count("i"))
area, info = resource_area(hmi, editor_dir) area, info = resource_area(hmi, firmware_dir)
base = tft.RES_START + len(area) base = tft.RES_START + len(area)
body = blob + descriptors + records + ptable + objects body = blob + descriptors + records + ptable + objects
body += b"\xff" * (-len(body) % 4) body += b"\xff" * (-len(body) % 4)
+7 -6
View File
@@ -78,13 +78,14 @@ class Tools(unittest.TestCase):
self.assertIn("pages: home", r["result"]["content"][0]["text"]) self.assertIn("pages: home", r["result"]["content"][0]["text"])
def test_build_tft(self): def test_build_tft(self):
from nxhmi import project, tft, tft_build from nxhmi import project, tft
for i, n in enumerate(tft_build.FIRMWARE_FILES): # stand-ins for the Editor's files from test_tft_build import fake_firmware # stand-ins for Nextion's files
with open(os.path.join(self.tmp, n), "wb") as f: patch = fake_firmware(self.tmp)
f.write(bytes([i]) * 50) patch.start()
self.addCleanup(patch.stop)
p, out = os.path.join(self.tmp, "min.HMI"), os.path.join(self.tmp, "min.tft") p, out = os.path.join(self.tmp, "min.HMI"), os.path.join(self.tmp, "min.tft")
project.new_project("NX4832T035_011").save(p) project.new_project("NX4832T035_011").save(p)
r = self.j("build_tft", path=p, tft_path=out, editor_dir=self.tmp) r = self.j("build_tft", path=p, tft_path=out, firmware_dir=self.tmp)
with open(out, "rb") as f: with open(out, "rb") as f:
data = f.read() data = f.read()
self.assertEqual(r["bytes"], len(data)) self.assertEqual(r["bytes"], len(data))
@@ -92,7 +93,7 @@ class Tools(unittest.TestCase):
# the demo uses component types that cannot be compiled yet: a tool error, not a crash # the demo uses component types that cannot be compiled yet: a tool error, not a crash
r = M.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call", r = M.handle({"jsonrpc": "2.0", "id": 1, "method": "tools/call",
"params": {"name": "build_tft", "arguments": {"path": self.hmi, "tft_path": out, "params": {"name": "build_tft", "arguments": {"path": self.hmi, "tft_path": out,
"editor_dir": self.tmp}}}) "firmware_dir": self.tmp}}})
self.assertTrue(r["result"]["isError"]) self.assertTrue(r["result"]["isError"])
def test_schema(self): def test_schema(self):
+53 -7
View File
@@ -1,32 +1,75 @@
"""The .tft builder. Real Editor output cannot be in the repo (it embeds Nextion firmware), so """The .tft builder. Real Editor output cannot be in the repo (it embeds Nextion firmware), so
these tests use a fake "Editor folder" with generated stand-in files and check the structure. these tests use a fake firmware folder with generated stand-in files (and their hashes) and check
the structure.
Byte-identity with the Editor is checked by test_against_editor_samples when NXHMI_TFT_SAMPLES Byte-identity with the Editor is checked by test_against_editor_samples when NXHMI_TFT_SAMPLES
points to a folder of <name>.HMI + <name>.tft pairs made with Nextion Editor 1.68.2.""" points to a folder of <name>.HMI + <name>.tft pairs made with Nextion Editor 1.68.2."""
import glob import glob
import hashlib
import os import os
import shutil import shutil
import struct import struct
import tempfile import tempfile
import unittest import unittest
from unittest import mock
from helpers import HAVE_PIL from helpers import HAVE_PIL
from nxhmi import cli, components as C, project, tft, tft_build from nxhmi import cli, components as C, firmware, project, tft, tft_build
from nxhmi.page import Page from nxhmi.page import Page
SAMPLES = os.environ.get("NXHMI_TFT_SAMPLES") SAMPLES = os.environ.get("NXHMI_TFT_SAMPLES")
def fake_firmware(folder, size=lambda i: 100 + 7 * i):
"""Write stand-ins for Nextion's firmware files and return a patch that makes their SHA-256
the expected one (the real files cannot be in the repo)."""
hashes = {}
for i, n in enumerate(firmware.FILES):
data = bytes([i + 1]) * size(i)
with open(os.path.join(folder, n), "wb") as fh:
fh.write(data)
hashes[n] = hashlib.sha256(data).hexdigest()
return mock.patch.object(firmware, "expected_hashes", return_value=hashes)
class Build(unittest.TestCase): class Build(unittest.TestCase):
def setUp(self): def setUp(self):
self.tmp = tempfile.mkdtemp() self.tmp = tempfile.mkdtemp()
for i, n in enumerate(tft_build.FIRMWARE_FILES): patch = fake_firmware(self.tmp)
with open(os.path.join(self.tmp, n), "wb") as fh: patch.start()
fh.write(bytes([i + 1]) * (100 + 7 * i)) self.addCleanup(patch.stop)
def tearDown(self): def tearDown(self):
shutil.rmtree(self.tmp) shutil.rmtree(self.tmp)
def test_firmware_hash_check(self):
with open(os.path.join(self.tmp, firmware.FILES[2]), "ab") as fh:
fh.write(b"x") # one byte more: wrong file
with self.assertRaisesRegex(tft_build.FirmwareError, "SHA-256"):
tft_build.build_tft(self.project(), self.tmp)
os.remove(os.path.join(self.tmp, firmware.FILES[2]))
with self.assertRaisesRegex(tft_build.FirmwareError, "not found"):
tft_build.build_tft(self.project(), self.tmp)
def test_firmware_command(self):
import contextlib
import io
dst = os.path.join(self.tmp, "fw")
with contextlib.redirect_stdout(io.StringIO()) as text:
self.assertEqual(cli.main(["firmware", "--from", self.tmp, "--firmware-dir", dst]), 0)
self.assertEqual(cli.main(["firmware", "--firmware-dir", self.tmp + "-none"]), 2)
self.assertEqual(sorted(os.listdir(dst)), sorted(firmware.FILES))
self.assertIn("missing", text.getvalue())
def test_manifest(self):
"""firmware.sha256: the seven files in .tft order, each with a SHA-256 (sha256sum format)."""
with open(firmware.MANIFEST, encoding="ascii") as fh:
rows = [line.split() for line in fh if line.strip()]
self.assertEqual([r[1] for r in rows], list(firmware.FILES))
self.assertEqual(firmware.FILES[:3], ("input.bin", "asp0.dll", "cd0.dll"))
for digest, _ in rows:
self.assertRegex(digest, "^[0-9a-f]{64}$")
def project(self): def project(self):
h = project.new_project("NX4832T035_011") h = project.new_project("NX4832T035_011")
p = Page.parse(h.read("0.pa")) p = Page.parse(h.read("0.pa"))
@@ -110,7 +153,7 @@ class Build(unittest.TestCase):
import contextlib import contextlib
import io import io
with contextlib.redirect_stdout(io.StringIO()) as text: with contextlib.redirect_stdout(io.StringIO()) as text:
self.assertEqual(cli.main(["build-tft", hmi, out, "--editor-dir", self.tmp]), 0) self.assertEqual(cli.main(["build-tft", hmi, out, "--firmware-dir", self.tmp]), 0)
self.assertEqual(cli.main(["tft-info", out]), 0) self.assertEqual(cli.main(["tft-info", out]), 0)
self.assertIn('"trailer_ok": true', text.getvalue()) self.assertIn('"trailer_ok": true', text.getvalue())
@@ -134,7 +177,10 @@ class Build(unittest.TestCase):
self.assertEqual(struct.unpack_from("<II", out, pics + 28), (1, 48 + len(h.read("0.i")) - 24)) self.assertEqual(struct.unpack_from("<II", out, pics + 28), (1, 48 + len(h.read("0.i")) - 24))
self.assertEqual(out[lay[12]:lay[12] + 44][:8], h.read("0.zi")[:8]) self.assertEqual(out[lay[12]:lay[12] + 44][:8], h.read("0.zi")[:8])
@unittest.skipUnless(SAMPLES and os.path.isdir(tft_build.DEFAULT_EDITOR_DIR), "needs Editor-made samples")
class EditorSamples(unittest.TestCase):
@unittest.skipUnless(SAMPLES and all(v == "ok" for v in firmware.status().values()),
"needs Editor-made samples and the real firmware files in firmware/")
def test_against_editor_samples(self): def test_against_editor_samples(self):
from nxhmi.container import HMIFile from nxhmi.container import HMIFile
done = 0 done = 0