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:
mangavalkandClaude Opus 5.5 committed 2026-11-15 15:11:02 +01:00
commit 69e22cfb06
70 files changed
+25058

No files matched your search

+12
View File
@@ -0,0 +1,12 @@
__pycache__/
*.pyc
*.egg-info/
build/
dist/
# never commit third-party projects or compiled firmware by accident
*.HMI
*.hmi
*.tft
# ...except our own demo and its Editor re-save (test fixture)
!demo/demo.HMI
!tests/fixtures/demo_editor_saved.HMI
+53
View File
@@ -0,0 +1,53 @@
# Working on this repo
Python package `nxhmi` (in `src/`): read, verify, edit, write and render Nextion Editor `.HMI`
projects, plus research on `.tft` firmware. No runtime dependencies; Pillow for pictures, fonts
and rendering.
## Layout
```
src/nxhmi/
checksum.py the three CRCs (page, main.HMI, file table)
container.py .HMI file system: tables, entries, Editor-style replace, fresh files
page.py pages, components, attributes, event code
components.py create components from templates_basic/intelligent.json (Editor defaults)
enums.py readable attribute values (names, #rrggbb)
models.py display models (id, series, resolution)
project.py new projects, add page/picture/font, decode to folder / encode back
pictures.py N.i / N.is
fonts.py .zi v6 fonts, generation from TrueType
render.py page renderer matching the Editor canvas
tft.py .tft research helpers (layout table, same-length trailer patch)
cli.py python -m nxhmi ...
examples/make_demo.py builds demo/ (demo.HMI, decoded/, render/)
tests/ unittest suite; fixtures/demo_editor_saved.HMI = the demo re-saved by the Editor
tools/ template generator
docs/ FORMAT.md (spec), RENDER.md, COVERAGE.md, NOTES.md (open points, what was tried)
```
## Commands
```
python -m unittest discover -s tests # all tests (run from the repo root)
python examples/make_demo.py # rebuild demo/ after changing writers or the renderer
PYTHONPATH=src python -m nxhmi verify demo/demo.HMI
```
After rebuilding the demo, `tests/test_project.py::Demo` must still pass: the generated demo has to
stay byte-identical to the Editor's re-save in `tests/fixtures/`. If a deliberate change breaks
that, re-save the demo with Nextion Editor (open, File > Save As) and replace the fixture.
## Rules
- **Black-box only.** Formats are worked out by changing projects in Nextion Editor and comparing
files, or by asking the Editor whether a hand-made file loads. Never decompile, decrypt or
patch Nextion software.
- **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
is our own demo re-saved by the Editor.
- 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**.
- Keep `docs/COVERAGE.md` and the README coverage table current when something is added.
- Writers must stay byte-identical to the Editor where we have samples; add a test when a new
rule is learned (see `tests/test_render.py` for the style: one rule, one measured expectation).
+21
View File
@@ -0,0 +1,21 @@
MIT License
Copyright (c) 2026 nextion-hmi-tools contributors
Permission is hereby granted, free of charge, to any person obtaining a copy
of this software and associated documentation files (the "Software"), to deal
in the Software without restriction, including without limitation the rights
to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
copies of the Software, and to permit persons to whom the Software is
furnished to do so, subject to the following conditions:
The above copyright notice and this permission notice shall be included in all
copies or substantial portions of the Software.
THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
SOFTWARE.
+96
View File
@@ -0,0 +1,96 @@
# openhmi-nx
Open-source tools for **Nextion HMI projects**: decode, edit, encode and render `.HMI` files
without Nextion Editor -- and, as research in progress, compile `.tft` firmware.
- decode a project into readable JSON + text (diff it, review it, keep it in git) and encode it back
- create projects, pages, components, pictures and fonts (rasterized from any TrueType font) from code
- render pages to PNG, matching the Editor's canvas pixel for pixel for nearly every component
- verify every checksum in a project
The file format, including its checksums, is documented in [docs/FORMAT.md](docs/FORMAT.md). It
was worked out black-box -- by editing projects in Nextion Editor and comparing the files it
writes; no Nextion software was decompiled.
> Not affiliated with or endorsed by Nextion / ITEAD. "Nextion" is their trademark.
![demo home page rendered by nxhmi](demo/render/home.png)
## Status
| Area | Coverage |
|---|---|
| `.HMI` read / write / build from scratch | complete for Basic (T) and Intelligent (P) series projects; output byte-identical to Nextion Editor 1.68 |
| Checksums | all three (page, project header, file table) |
| Components | all 31 types, with the Editor's own defaults |
| Readable JSON | enum names and `#rrggbb` colours, still byte-exact on the way back |
| Pictures | Basic series format complete; Intelligent compressed format not yet |
| Fonts | black/white `.zi` v6 complete, incl. generation from TrueType; anti-aliased not yet |
| Rendering | pixel-identical for text, numbers, buttons, sliders, bars, checkboxes, pictures, waveform...; radio ~95 %, QR placeholder ([docs/RENDER.md](docs/RENDER.md)) |
| `.tft` compile | research: layout mapped, partial checksum support; not usable yet |
Details and the full list of gaps: [docs/COVERAGE.md](docs/COVERAGE.md).
## Install
Python 3.9+. Pillow is only needed for pictures, font generation and rendering.
```
pip install -e . # or run with PYTHONPATH=src
pip install pillow # optional
```
## Command line
```
python -m nxhmi info project.HMI # entries, pages, checksum status
python -m nxhmi verify project.HMI # check every checksum
python -m nxhmi decode project.HMI folder/ # -> manifest.json, Program.s, pages/*.json, resources/
python -m nxhmi encode folder/ new.HMI # folder -> fresh .HMI
python -m nxhmi dump project.HMI --page home # one page as JSON
python -m nxhmi set project.HMI home title txt "Hello"
python -m nxhmi add project.HMI home button x=10 y=60 w=120 h=40 txt=Hi --name bHi
python -m nxhmi new-page project.HMI settings
python -m nxhmi add-picture project.HMI logo.png
python -m nxhmi add-font project.HMI DejaVuSans.ttf 24
python -m nxhmi render project.HMI pngs/ # one PNG per page
python -m nxhmi kinds # component kinds for `add`
```
## Python
```python
from nxhmi import project, fonts, components as C
from nxhmi.render import Renderer
h = project.new_project("NX4832T035_011", "home") # no Nextion files needed
font = project.add_font(h, fonts.from_ttf(None, 24)) # None = Pillow's bundled CC0 font
page = project.add_page(h, "settings")
C.add(page, "button", x=10, y=10, w=140, h=40, txt="back", font=font,
events={"codesup": ["page home"]})
h.write("1.pa", page.pack())
h.save("my.HMI") # opens in Nextion Editor
Renderer(h).render("settings").save("settings.png")
```
## Demo
`demo/` is generated by [examples/make_demo.py](examples/make_demo.py): a 3-page project
(`demo.HMI`), its decoded form (`decoded/`) and renders (`render/`). Nextion Editor re-saves it
byte for byte unchanged -- that re-save is the test fixture in `tests/fixtures/`.
## Tests
```
python -m unittest discover -s tests
```
## Credits
[Nextion2Text](https://github.com/MMMZZZZ/Nextion2Text) (MPL-2.0) first documented the page record
layout (read-only); [nextion-font-editor](https://github.com/hagronnestad/nextion-font-editor)
documented older font versions. This is an independent implementation.
## License
MIT, see [LICENSE](LICENSE).
+4
View File
@@ -0,0 +1,4 @@
//Program.s runs once at power-on, before the first page is shown.
//Global variables can be declared here: int sys0=0
baud=115200
page 0
+53
View File
@@ -0,0 +1,53 @@
{
"crc_ok": true,
"model_id": "0xB23BC018",
"model": "NX4832T035_011",
"model_desc": "Nextion 3.5\" Basic 480x320",
"resources": [
[
"i",
"0.i"
],
[
"i",
"1.i"
],
[
"i",
"2.i"
],
[
"i",
"3.i"
],
[
"i",
"4.i"
],
[
"i",
"5.i"
],
[
"zi",
"0.zi"
],
[
"zi",
"1.zi"
],
[
"pa",
"0.pa"
],
[
"pa",
"1.pa"
],
[
"pa",
"2.pa"
]
],
"raw_hex": "a9664eb5600000000144210001034f0018c03bb200000000600000000b000000000000000200000000000000000000000000000000000000000000000000000000030000000000000000000000000000000000000000000000000000000000006900000000000000302e6900000000006900000000000000312e6900000000006900000000000000322e6900000000006900000000000000332e6900000000006900000000000000342e6900000000006900000000000000352e6900000000007a69000000000000302e7a69000000007a69000000000000312e7a69000000007061000000000000302e7061000000007061000000000000312e7061000000007061000000000000322e706100000000"
}
+83
View File
@@ -0,0 +1,83 @@
{
"format": "nxhmi-folder-1",
"encoding": "latin-1",
"entries": [
{
"name": "Program.s",
"file": "Program.s"
},
{
"name": "0.zi",
"file": "resources/0.zi"
},
{
"name": "1.zi",
"file": "resources/1.zi"
},
{
"name": "0.is",
"file": "resources/0.is"
},
{
"name": "0.i",
"file": "resources/0.i"
},
{
"name": "1.is",
"file": "resources/1.is"
},
{
"name": "1.i",
"file": "resources/1.i"
},
{
"name": "2.is",
"file": "resources/2.is"
},
{
"name": "2.i",
"file": "resources/2.i"
},
{
"name": "3.is",
"file": "resources/3.is"
},
{
"name": "3.i",
"file": "resources/3.i"
},
{
"name": "4.is",
"file": "resources/4.is"
},
{
"name": "4.i",
"file": "resources/4.i"
},
{
"name": "5.is",
"file": "resources/5.is"
},
{
"name": "5.i",
"file": "resources/5.i"
},
{
"name": "0.pa",
"page": "pages/0_home.json"
},
{
"name": "1.pa",
"page": "pages/1_controls.json"
},
{
"name": "main.HMI",
"main": "main.HMI.json"
},
{
"name": "2.pa",
"page": "pages/2_gallery.json"
}
],
"model": "NX4832T035_011"
}
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
Binary file not shown.
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 4.6 KiB

Binary file not shown.
File diff suppressed because it is too large. Load diff
Binary file not shown.
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 449 B

Binary file not shown.
File diff suppressed because it is too large. Load diff
Binary file not shown.
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 221 B

Binary file not shown.
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 252 B

Binary file not shown.
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 182 B

Binary file not shown.
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 167 B

BIN
View File
Binary file not shown.
Binary file not shown.

After

Width:  |  Height:  |  Size: 3.7 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 4.8 KiB

Binary file not shown.

After

Width:  |  Height:  |  Size: 5.4 KiB

+105
View File
@@ -0,0 +1,105 @@
# Coverage report (updated 2026-11-15)
What nextion-hmi-tools covers today compared with Nextion Editor 1.68, and what is missing.
"Verified" means checked against the real Editor: either the Editor's own output is reproduced
byte for byte, or a file written by nxhmi was opened in the Editor and showed the expected result.
## Summary
| Area | Status |
|---|---|
| Reading `.HMI` files | **complete** for everything seen so far |
| Writing `.HMI` files (edit, add, build from scratch) | **complete** for Basic-series projects |
| Checksums (page, project header, file table) | **complete**, verified |
| Components | **31 / 31 types** (20 Basic + 11 Intelligent-only) read/write/create |
| Readable JSON (enum names, colours) | done for every value list the Editor documents |
| Pictures | Basic series **complete**; Intelligent compressed format **missing** |
| Fonts | black/white **complete** incl. generation from TrueType; anti-aliased **missing** |
| Rendering pages like the Editor | **pixel-identical** for most components incl. picture skins; radio ~93-97 %, QR placeholder |
| New projects from scratch | `project.new_project(model)` for 12 Basic/Intelligent models; the generated demo is byte-identical to the Editor's re-save |
| Compiling `.tft` firmware | **research only** -- not possible yet |
## Covered in detail
### File container and integrity
- File table + backup table at 0x80000, Editor-style replace (append + delete), fresh compact
files. Verified: 34 sample files re-written byte-identical; from-scratch files open in the Editor.
- All three checksums (CRC-32/0x04C11DB7, STM32-style feeding) -- 276 Editor-written pages verify.
### Project header (`main.HMI`)
- Model id + series byte, text-encoding index, resource list (pages, pictures, fonts).
- Adding pages, pictures and fonts updates it correctly (verified in the Editor).
### Pages and components
- Byte-exact round trip of every page tested (204 pages).
- All 31 component types with the Editor's own default attributes (`templates_*.json`):
page, text, scrolling text, number, xfloat, button, dual-state button, progress bar, picture,
crop, hotspot, touch cap, gauge, waveform, slider, timer, variable, checkbox, radio, QR code,
and Intelligent-only video, audio, Gmov, ExPicture, ComboBox, SLText, FileStream, FileBrowser,
DataRecord, Switch, TextSelect.
- Event code (all event groups) as plain text lines.
- Text vs. number attributes detected reliably (length-limit companion rule).
- Signed values (e.g. number `val`) supported.
### Readable values
- Value names for `vscope`, `sta` (per component type), `style`, `xcen`, `ycen`, `isbr`, `pw`,
`format`, `dir`, `en`, `mode`, `psta`, `dez`, variable type, QR logo -- taken from the Editor's
own attribute notes. Colours as `#rrggbb`. Still round-trips byte for byte.
### Pictures (Basic series)
- `N.i` (RGB565, panel-native rotated order) and `N.is` (original file) -- encoder output is
byte-identical to the Editor's; adding pictures verified in the Editor.
### Fonts
- `.zi` version 6, black/white: decode/encode byte-identical to the Editor (224-glyph font).
- New fonts from any TrueType/OpenType file (proportional or fixed width, ascii / iso-8859-1);
verified rendering in the Editor.
### Rendering
- See [RENDER.md](RENDER.md): a real 6-page project renders pixel-identical; per-component tests
100 % for text, number, xfloat, buttons, progress bar, slider, checkbox, picture, crop, waveform.
### Tooling
- CLI: `info verify decode encode set add add-picture add-font new-page kinds render dump`.
- 66 unit tests; the only binary fixture is our own demo re-saved by Nextion Editor (no Nextion files).
### Demo project
- `examples/make_demo.py` builds a 3-page project from code (fonts from Pillow's CC0 font, generated
pictures). Nextion Editor re-saves it byte for byte unchanged, every entry including `main.HMI`.
## Missing
### `.HMI` side
| Item | Notes |
|---|---|
| Intelligent picture format 4 | block codec with 8-bit alpha; first findings in FORMAT.md |
| Anti-aliased fonts, multi-byte encodings (GB2312, Big5, ...) | only B/W single-byte fonts seen |
| Other display series | Discovery / Enhanced / Edge not sampled; only Basic + Intelligent templates |
| Display direction | picture/glyph order verified for one direction (main.HMI byte 13 = 3) only |
| Some header fields | main.HMI bytes 8, 13, 36, 0x41; page header 21/23; entry bytes 25-27 |
| Font name shown in the Editor's Fonts panel | cosmetic, generated fonts show an odd label |
| Media resources | video / audio / Gmov files themselves (not just the components) |
| Editor features beyond the file | simulator/debugger, upload over serial (Nexus covers upload) |
### Rendering
| Item | Notes |
|---|---|
| Radio circle | ~93-97 %: outline/dot differ by +-1 px at some radii (in progress) |
| QR code | placeholder; needs the Editor's QR settings |
| Pressed / runtime states, Intelligent-only components | not drawn |
### `.tft` compilation (firmware for the display)
| Item | Status |
|---|---|
| File layout | mapped (header, embedded Nextion files, project section, trailer) |
| Layout table | decoded (fixed XOR key) |
| Trailer checksum | works for same-length edits; **unknown for different lengths** (stuck) |
| 3 header checksums (0x44, 0xC4, 0x18C) | not analysed |
| Compiled page format, event-code tokens | first look only |
| Pictures and fonts inside the TFT | not analysed |
| 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 |
## Suggested next steps
1. Intelligent picture format 4 (needed for Intelligent displays).
2. `.tft`: try the remaining trailer-checksum ideas listed in NOTES.md; then the compiled page format.
3. Sample the other display series to confirm templates and picture order.
+251
View File
@@ -0,0 +1,251 @@
# The Nextion Editor `.HMI` project format
Reverse-engineered black-box: by editing projects in Nextion Editor (v1.68), saving, and comparing
files, and by asking the Editor whether hand-made files load ("oracle" tests). The Editor itself was
never decompiled or decrypted. Everything here was checked against real files; open points are
marked **OPEN**.
All integers are little-endian.
## 1. Container
An `.HMI` file is a tiny file system.
| Offset | Contents |
|---|---|
| `0x000000` | file table: `count` (u32), `count` × 28-byte entries, then the table checksum (u32) |
| `0x080000` | backup copy of the file table (byte-identical, incl. checksum) |
| `0x380000` | u32 `0xFFFFFFFF` |
| `0x6FFFF8` | ASCII `ver21234` |
| `0x700000` | entry data, packed back to back |
The space between these areas is normally zero (older files can contain stale data, e.g. at
`0x100000`, which is ignored).
### File table entry (28 bytes)
| Offset | Size | Field |
|---|---|---|
| 0 | 16 | name, NUL padded (`main.HMI`, `Program.s`, `0.pa`, `0.i`, `0.is`, `0.zi`, ...) |
| 16 | 4 | start offset in the file |
| 20 | 4 | size |
| 24 | 1 | deleted flag |
| 25 | 3 | unknown (looks like uninitialised memory; **is** covered by the table checksum) |
When the Editor replaces an entry it appends the new data to the end of the file, adds a new
entry, and marks the old entry deleted: deleted flag = 1 **and first byte of the name = 0**
(e.g. `\0ain.HMI`). The Editor finds entries by name, so setting only the flag is not enough.
Deleted entries stay in the table and their data stays in the file.
If the primary table's checksum fails the Editor silently uses the backup table. If both fail it
reports "Version mismatch". The Editor also rewrites a file when opening it (it repairs the
primary table from the backup, among other things) -- never reuse a test file after opening it.
### Entry names
| Name | Contents |
|---|---|
| `main.HMI` | project header (display model, resource list) -- 224 bytes |
| `Program.s` | start-up script, plain text (no checksum) |
| `N.pa` | page N |
| `N.i` | picture N as the display uses it (section 4) |
| `N.is` | picture N's original source file (section 4) |
| `N.zi` | font N (section 5) |
### `main.HMI` (project header)
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | checksum (section 2) |
| 4 | 4 | header size = 0x60 = start of the resource list |
| 8 | 1 | 1 (**OPEN**) |
| 9 | 1 | 0x41 in a 2019 file, 0x44 after saving with Editor 1.68 (Editor/format revision?) |
| 10 | 1 | 0x21 |
| 11 | 1 | display series: 0 = Basic (T), 3 = Intelligent (P); others **OPEN** |
| 12 | 1 | text encoding index (1 = iso-8859-1; an unknown value makes the Editor fail with "'null' is not a supported encoding name") |
| 13 | 1 | 3 (**OPEN**; not the model index) |
| 14 | 1 | 0x4F |
| 16 | 4 | model id (e.g. 0xB23BC018 NX4832T035_011, 0x181169DA NX4827P043_011); must match the series byte, otherwise the Editor falls back to its first model |
| 24 | 4 | 0x60 |
| 28 | 4 | resource count |
| 36 | 4 | 1 or 2 (**OPEN**) |
| 0x41 | 1 | 3 after switching to an Intelligent model (**OPEN**) |
| 0x60 | 16 × count | resource list: type[8] + name[8], e.g. `pa`/`3.pa`, `i`/`0.i`, `zi`/`0.zi` |
Adding a page = new `N.pa` entry + one resource-list entry + count + 1 + new checksum (verified:
the Editor shows pages added this way). `.is` entries are not listed.
## 2. Checksums
All three use CRC-32 with polynomial `0x04C11DB7`, MSB-first (not reflected), initial value
`0xFFFFFFFF`, no final XOR -- the algorithm of the STM32 hardware CRC unit. They differ in how
input is fed.
### Page checksum (first 4 bytes of every `N.pa`)
Every input **byte** is zero-extended to a 32-bit word and fed as one word. Input:
```
page[4:] # whole page after the checksum field
+ datasize (4 bytes, LE) # = page header offset 4
+ numberobj (4 bytes, LE) # = page header offset 12
+ page[20] + page[21] # header bytes 20 and 21
```
Evidence: two saves differing in one bit place that bit's influence at `x^(32·k)` -- adjacent file
bytes are exactly 32 bits apart in the CRC stream; a fixed 10-word tail appears after the page;
the tail contents were solved over pages of different lengths and component counts; then
verified on 276 Editor-written pages (including a 2019 file) and by the Editor accepting pages
built from scratch.
### `main.HMI` checksum (first 4 bytes)
Same word-per-byte scheme. Input: `main[4:] + main[16:20] + main[4:8] + main[10] + main[14]`.
**OPEN**: the last two tail bytes were 0x21, 0x4F in every sample; they may be constants (they equal
the page header's "version" bytes) rather than fields.
### File table checksum (u32 right after the last entry)
Input read as **little-endian 32-bit words**: the table from `count` through the last entry, then
the constant word `0x43454441` (ASCII "ADEC").
## 3. Pages (`N.pa`)
### Header (56 bytes)
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | checksum (above) |
| 4 | 4 | datasize = total page length |
| 8 | 4 | infoaddr = 56 (start of component table) |
| 12 | 4 | numberobj = component count |
| 16 | 4 | password |
| 20 | 1 | locked |
| 21 | 1 | 0x4F in every file seen (**OPEN**) |
| 22 | 1 | 0x21 (33) in every file seen -- format version? |
| 23 | 1 | 0 (**OPEN**) |
| 24 | 16 | page name |
| 40 | 16 | reserved (zero) |
### Component table
`numberobj` entries of `(u32 offset, u32 size, u32 unknown=0)`. Offset is relative to byte 56.
The page itself is component 0.
### Component data
A sequence of records `u32 length + bytes`, ending with an empty record. Records are grouped:
a header record `"<group>-<n>"` is followed by n records.
* `att-<n>`: attributes. Each record = 16-byte NUL-padded name + value. Integers are unsigned
LE of 1, 2 or 4 bytes (`val` has a different width per component type); `objname`, `txt`
(and other text attributes) are raw text in the project encoding (iso-8859-1 by default).
* `codes<event>-<n>`: event code, one record per line. Seen: `codesload` (preinitialize),
`codesloadend` (postinitialize), `codesdown` (touch press), `codesup` (touch release),
`codesunload` (page exit), `codestimer`, `codesslide` (slider move).
Attribute names seen so far: `aph bco bco1 bco2 borderc borderw ch dis disup down drag effect en
endx endy first font format groupid0 groupid1 h hig id isbr key left lenth lockobj maxval minval
mode movex movey objname pco pco2 pic pic1 pic2 picc picc1 picc2 psta pw right sendkey spax spay
sta style tim time txt txt_maxl type up val vscope w wid x xcen y ycen`.
Text attributes are `objname` and every attribute that has a length-limit companion in the same
component (`txt`/`txt_maxl`, `path`/`path_m`, `dir`/`dir_m`, `filter`/`filter_m`,
`format`/`format_m`, `vvs2`/`vvs2_m`). The same name can be a number elsewhere (`dir` is a u8 on
scrolling text, `format` a u8 on number).
Component `type` values (all placed in Editor 1.68; full default attribute lists in
`src/nxhmi/templates_*.json`):
| type | component | | type | component |
|---|---|---|---|---|
| 0 | waveform | | 59 | xfloat |
| 1 | slider | | 60 | ExPicture * |
| 2 | Gmov * | | 61 | ComboBox * |
| 3 | Video * | | 62 | SLText * |
| 4 | Audio * | | 63 | FileStream * |
| 5 | TouchCap | | 65 | FileBrowser * |
| 51 | timer | | 66 | DataRecord * |
| 52 | variable | | 67 | Switch * |
| 53 | dual-state button | | 68 | TextSelect * |
| 54 | number | | 98 | button |
| 55 | scrolling text | | 106 | progress bar |
| 56 | checkbox | | 109 | hotspot |
| 57 | radio | | 112 | picture |
| 58 | QRcode | | 113 | crop |
| 116 | text | | 121 | page |
| 122 | gauge | | | |
\* Intelligent series only. Attribute sets of shared types are identical on Basic and Intelligent
projects. `sta` on pages/texts: 1 = solid colour, 2 = picture.
## 4. Pictures
`N.is` = 27-byte header + the original image file, untouched (verified byte-identical with the
PNG that was imported):
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | `0A 64 01 01` |
| 8 | 4 | data offset = 27 |
| 12 | 2+2 | width, height |
| 16 | 4 | length of the embedded file |
| 24 | 3 | file type, e.g. `png` |
`N.i` = 24-byte header + pixels:
| Offset | Size | Field |
|---|---|---|
| 0 | 4 | `0B 64 01 <format>` -- 0 = raw RGB565 (Basic series), 4 = compressed (Intelligent, **OPEN**) |
| 8 | 4 | data offset = 24 |
| 12 | 2+2 | width, height |
| 16 | 4 | data length (format 0: w × h × 2) |
Format 0: RGB565 little-endian, converted by plain truncation (`r>>3, g>>2, b>>3`), stored in the
panel's native scan order -- column by column, each column bottom-to-top:
`offset = 2 * (x * height + (height - 1 - y))`. Verified pixel-exact (480×320 and 64×64, Editor
output byte-identical to ours). **OPEN**: whether the order changes with the project's display
direction (all samples: main.HMI byte 13 = 3).
Format 4 (Intelligent series, **OPEN**): header field at 20 is non-zero for small pictures
(e.g. 2640 for a 3307-byte payload); payload starts with u32 1, u32 height, u32 width (note:
swapped vs. the header, i.e. panel orientation), ... then a block codec: runs of RGB565 colours
followed by small index bytes (e.g. `18c6 38c6 18c6 38c6 2131 1111`), with a variable number of
bytes per 4x4 block, and full 8-bit alpha (a PNG with 256 alpha levels was imported). A 480x320
photo compresses to 215,052 bytes at "Q:100".
Adding a picture = `N.is` + `N.i` + a `i`/`N.i` resource-list entry (kept grouped with the other
`i` entries) -- verified in the Editor.
## 5. Fonts (`N.zi`, format version 6)
Header 44 bytes: magic `04 FF 00 0B`, u16 encoding (3 = iso-8859-1), u8 width, u8 height,
multi-byte range (2 bytes), code range first/last, u32 character count, u8 version = 6,
u8 name length (twice) + 0, u32 length of name+map+glyphs, u32 name offset = 0x2C, 16 unknown
bytes. Then the name, the character map, the glyph data.
Character map: 10 bytes per character: u16 code, u8 glyph width, 2 unknown bytes,
u24 glyph offset (relative to the map start), u16 glyph length.
Glyph: mode byte (0x01 = black/white), then run-length codes over the pixels in the same
column-by-column, bottom-to-top order as pictures (runs continue across columns):
| Code | Meaning |
|---|---|
| `00 0xxxxx` | x transparent |
| `00 1xxxxx` | x ink |
| `01 0xxxxx` | x transparent, 1 ink |
| `01 1xxxxx` | x transparent, 2 ink |
| `10 0xxxxx` | x transparent, 3 ink |
| `10 1xxxxx` | x transparent, 4 ink |
| `11 tttiii` | ttt transparent, iii ink |
The Editor encodes greedily (transparent run + 1..4 ink if possible, else the 3+3-bit form, else a
plain run); our encoder reproduces a 224-glyph Editor font byte for byte. The v3/v5 write-ups in
github.com/hagronnestad/nextion-font-editor were a useful starting point; v6 differs (scan order,
B/W codes `10`/`11`). **OPEN**: anti-aliased glyphs (other mode bytes), multi-byte encodings,
the 16 unknown header bytes.
## 6. Not yet covered
See `docs/NOTES.md`.
+117
View File
@@ -0,0 +1,117 @@
# Status and open points
## Done (verified against the real Editor)
- Container read/write: file table + backup table, table checksum, Editor-style replace
(append + delete), building a fresh compact file from scratch.
- Page checksum, `main.HMI` checksum, table checksum.
- Pages: header, component table, attribute and event-code records -- byte-exact round trip on
every page tested (204 pages in 34 files).
- Decode to a JSON/text folder and encode back; edits made in JSON (text, position, new length)
load correctly in the Editor.
- Component factory (`nxhmi.components`) with the Editor's defaults for **all 31 component types**
(20 Basic + 11 Intelligent-only); `add(page, "button", x=.., txt=.., events=..)`. A page with 7
tool-added components renders correctly in the Editor.
- `main.HMI` resource list and model/series/encoding fields; adding pages (`project.add_page`,
CLI `new-page`) -- the Editor shows the new page with its components.
- Pictures (Basic series): `N.i` and `N.is` decode/encode, byte-identical to the Editor; adding
pictures (`project.add_picture`, CLI `add-picture`) verified in the Editor.
- Fonts (`.zi` v6, black/white): decode/encode byte-identical to the Editor.
- `decode` also writes the original picture files and a text dump of every font.
- Font generation from TrueType (`fonts.from_ttf`, CLI `add-font`): proportional fonts render
correctly in the Editor. Cosmetic OPEN: the Editor's Fonts panel derives the shown name/encoding
from the name string in a way not yet matched (shows "DejaVuSans-(h:24,encode:24asc...").
- CLI: `info verify decode encode set add add-picture add-font kinds new-page dump`.
Full overview of what is covered and missing: [COVERAGE.md](COVERAGE.md).
- Readable JSON values (enum names, `#rrggbb` colours); page renderer pixel-identical to the
Editor for most components ([RENDER.md](RENDER.md)).
## Next steps (in order)
1. Intelligent picture format 4 (block codec with alpha, see FORMAT.md 4 -- first look only); anti-aliased fonts.
3. `.tft` compilation research.
## Open
- `main.HMI`: bytes 8, 13, 36, 0x41; series codes other than Basic (0) and Intelligent (3);
whether the last two checksum tail bytes are fields or constants (only one value ever seen).
- Pictures, picture sources, fonts: carried as raw blobs for now.
- Unknown bytes: page header offsets 21/23, entry bytes 25..27, component-table third word.
- Templates come from Editor 1.68 on NX4832T035 (Basic) and NX4827P043 (Intelligent);
Discovery/Enhanced/Edge series not sampled yet.
## .tft compilation -- first look (2026-11-15), paused for a decision
How to get one: Compile, then File > "TFT file output" > Output (written to
`%AppData%\Nextion Editor\work\<id>\output\`). Compile also leaves `run.run` there (the simulator
build, much smaller -- pictures are stored differently).
Observed in a 740,544-byte TFT of a 6-page NX4832T035 project:
- 0x000-0x0C3: header -- model id (0xB23BC018 at 0x2C), screen size (480/320 at 0x0C), several
sizes/offsets; then FF padding.
- 0x0C4-0x117: a block of 32-bit words that all share the same high bytes (`.. .. AB EB`) --
i.e. XOR-obfuscated with a fixed key. A 4-byte value at 0x18C, then FF up to ~64 KB.
- The rest: project data, plus **Nextion's own binaries embedded verbatim** from the Editor's
install folder: `input.bin` (all of it), `qr0.bin`, `syscom.bin`. `ApplicationRUN.s0` (the
display runtime, 105 KB) was not found in plain form.
Consequences for an open-source compiler:
1. The repo must not ship Nextion's binaries. A compiler would have to read them from the user's
own Editor installation at build time.
2. The XOR-obfuscated parts are a deliberate protection, not just a format. Reproducing them
needs a decision on whether that is acceptable (interoperability research vs. circumvention).
3. Real work beyond that: Nextion script -> bytecode compiler, per-component runtime layout,
pictures/fonts in TFT layout, TFT checksums.
### Second look: minimal projects (one empty page, no pictures/fonts), NX4832T035
Method: build tiny projects with nxhmi that differ in one thing, compile + "TFT file output" via
the Editor, diff. **Compilation is deterministic** (same HMI -> byte-identical TFT).
Layout of a minimal TFT (328,920 bytes):
| Range | Contents |
|---|---|
| 0x00000-0x10090 | header (0x00-0xC3), XOR-obfuscated block (0xC4-0x117), value at 0x18C, FF padding, 144 bytes at 0x10000 |
| 0x10090-0x47F7B | Nextion files, verbatim, in this order: `input.bin`, `asp0.dll`, `cd0.dll`, `qr0.bin`, `syscom.bin`, `h0-0.dll`, `h1-0.dll` (the `.dll` files in the Editor folder are display firmware pieces, not Windows DLLs) |
| 0x47F7B-end-4 | project section: ~32 KB of zeros, then the compiled page(s) (~1 KB for an empty page) |
| last 4 bytes | file checksum |
Header fields (byte offsets, LE): 0x0C u16 480, u16 320, u16 320, u16 480; 0x18 and 0x1E u32
= offset of `cd0.dll`; 0x22 u32 = size of `cd0.dll`; 0x26 u32 = offset of `asp0.dll`; 0x2A u32
= size of `asp0.dll`; 0x2E u32 model id; 0x3C u32 file size; 0x40 u32 0x40000 (0x90000 for the
6-page project); 0x44 u32 hash-like value; 0x58 u32 grows with the project data.
Compiled page (plain, not obfuscated): contains `0,0,480,320,` (page area), event names
(`down`, `up`, `unload`), attribute values in place (page `bco` as u16 LE). Event code is
**tokenized, not compiled to bytecode**: `dim=50` becomes a 1-byte token for `dim` followed by the
literal text `=50`.
Obfuscated block 0xC4-0x117: word 0xC4 is a per-file checksum; words 0xC8..0x113 are a
**layout table XORed with the fixed key 0xEBAB2932** (offsets/sizes/counts -- e.g. the project
section start 0x47F7B twice, a size that grows with the code, page/picture counts). Decoder:
`nxhmi.tft.layout_table`.
Three more per-file values -- 0x44, 0xC4, 0x18C -- do **not** change when only content changes
(page colour, one code character); they depend on layout only (likely header checksums).
File checksum (last 4 bytes, LE): word-per-byte CRC (same family as the page checksum), stream
ending right before the trailer -- proved on two independent one-change pairs. Consequently
**same-length edits can be re-checksummed** (`nxhmi.tft.patch_trailer`, reproduces the Editor's
output byte for byte for a colour change and for `dim=50` -> `dim=51`).
**STUCK (2026-11-15):** start offset / seed of the trailer CRC across files of different lengths.
Tried, all without a fit (three minimal files of different lengths + the 6-page project):
every start offset 0..end with a constant seed (solved exactly by GF(2) linear algebra); seeds
taken from header fields 0x44/0xC4/0x18C (raw, inverted, LE/BE); the header checksum fields
zeroed or 0xFF in every combination; the layout table de-obfuscated before checksumming.
Ideas not yet tried: the stream skipping a region whose size varies (e.g. FF padding after the
page data); a seed derived from file size or layout words; the trailer covering only the
project section in a different order (e.g. pages then the zero area).
Not started: the 3 header checksums, the compiled page format (component records, the token
table for event code), pictures/fonts inside the TFT.
+55
View File
@@ -0,0 +1,55 @@
# Page rendering vs. Nextion Editor
`python -m nxhmi render project.HMI out/` draws every page the way Nextion Editor 1.68 shows it on
its canvas. Verified by capturing the Editor's canvas at 100 % zoom and comparing pixel by pixel
(ignoring the Editor's yellow name tags and its 2-px selection outline).
## Results
The demo project (`demo/demo.HMI`, built by `examples/make_demo.py`):
| Page | Differing pixels | Notes |
|---|---|---|
| home | 94 | all in the two radio buttons and at name-tag edges |
| controls | 5 | name-tag edges |
| gallery | 1 | name-tag edge |
A real 6-page user project (pictures, 32-px bitmap font, texts, 3D buttons, sliders): every page
pixel-identical apart from 0-5 px at name-tag edges.
Per component (dedicated test pages):
| Component | Match | Notes |
|---|---|---|
| text (all xcen/ycen, solid / crop / image background, border, 3D up/down) | 100 % | |
| text with word wrap | 100 % | the text block is aligned as a whole, lines left-aligned in it |
| number (plain, fixed length, hex, currency, negative), xfloat | 100 % | |
| button, dual-state button (colour and picture skins, on/off) | 100 % | "on" with 3D style is drawn pressed (3D down) |
| scrolling text (static) | 100 % | |
| progress bar (horizontal, vertical, picture mode) | 100 % | |
| slider (horizontal, vertical, auto cursor, picture background and cursor) | 100 % | auto cursor = square as thick as the slider; position truncates |
| checkbox (3D down, border, flat) | 100 % | |
| picture, crop (also smaller than the component) | 100 % | only the picture's real area is drawn |
| waveform (frame + grid) | 100 % | horizontal grid lines count from the bottom |
| gauge | 99.3 - 100 % | needle anti-aliasing differs by a few px |
| radio | ~93 - 97 % | circle outline/dot differ by +-1 px at some radii (work in progress) |
| QR code | placeholder only | |
| hotspot, touch cap, timer, variable | nothing drawn (same as the Editor) | |
## Rules learned from the Editor
- Text never starts above/left of its box: centring clamps at 0 (a 32-px font in a 30-px box
starts at the top).
- Text is laid out inside the border: 1 px for 3D styles, `borderw` for style "border".
- 3D colours are fixed: light (230,226,230), dark (65,68,65) -- top/left light for 3D up/auto,
dark for 3D down.
- Buttons with a picture background (`sta` crop or image) get no frame.
- Pictures are pasted at their real size; a smaller picture leaves the rest untouched.
- Checkbox: `bco` fill, `style` frame, checked = `pco` square from w/4 to 3w/4.
- Radio: circle sized by the component *width* (clipped to the height); ring radius
`(w-1)//2`, colour (65,68,65), filled with `bco`; checked = `pco` dot.
- Slider: auto cursor (255) is a square as thick as the slider; position = `int(frac * free)`.
- Waveform: vertical grid lines from the left edge, horizontal ones counted from the bottom.
Not covered yet: exact radio circles, QR codes, Intelligent-only components (need Intelligent
picture format 4), anti-aliased fonts, pressed/runtime states.
+152
View File
@@ -0,0 +1,152 @@
"""Build the demo project (demo/demo.HMI) entirely from code -- no Nextion files involved.
python examples/make_demo.py # writes demo/demo.HMI, demo/decoded/, demo/render/
Needs Pillow (pictures, the bundled CC0 "Aileron" font, rendering).
"""
import io
import os
import shutil
import sys
HERE = os.path.dirname(os.path.abspath(__file__))
ROOT = os.path.dirname(HERE)
sys.path.insert(0, os.path.join(ROOT, "src"))
from PIL import Image, ImageDraw # noqa: E402
from nxhmi import components as C, fonts, project # noqa: E402
from nxhmi.render import Renderer # noqa: E402
W, H = 480, 320
def png(img):
b = io.BytesIO()
img.save(b, "PNG")
return b.getvalue()
def background():
img = Image.new("RGB", (W, H))
d = ImageDraw.Draw(img)
for y in range(H):
t = y / (H - 1)
d.line([(0, y), (W - 1, y)], fill=(int(20 + 40 * t), int(40 + 80 * t), int(90 + 120 * t)))
for i in range(0, W, 40):
d.line([(i, 0), (i + 120, H)], fill=(60, 110, 170))
return png(img)
def icon(size=64):
img = Image.new("RGB", (size, size), (255, 255, 255))
d = ImageDraw.Draw(img)
d.ellipse([4, 4, size - 5, size - 5], fill=(255, 170, 0), outline=(120, 60, 0), width=3)
d.rectangle([size // 2 - 4, 12, size // 2 + 3, size - 13], fill=(255, 255, 255))
return png(img)
def skin(w, h, c1, c2):
img = Image.new("RGB", (w, h))
d = ImageDraw.Draw(img)
for x in range(w):
t = x / max(1, w - 1)
d.line([(x, 0), (x, h - 1)], fill=tuple(int(a + (b - a) * t) for a, b in zip(c1, c2)))
d.rectangle([0, 0, w - 1, h - 1], outline=(255, 255, 255))
return png(img)
def build():
h = project.new_project("NX4832T035_011", "home")
small = project.add_font(h, fonts.from_ttf(None, 16)) # font 0
big = project.add_font(h, fonts.from_ttf(None, 32)) # font 1
bg = project.add_picture(h, background())
ico = project.add_picture(h, icon())
sk1 = project.add_picture(h, skin(140, 40, (200, 40, 40), (60, 40, 200)))
sk2 = project.add_picture(h, skin(140, 40, (40, 160, 60), (220, 200, 40)))
bar = project.add_picture(h, skin(200, 24, (40, 40, 40), (110, 110, 110)))
barfg = project.add_picture(h, skin(200, 24, (255, 140, 0), (255, 240, 0)))
# ---- page 0: home
from nxhmi.page import Page
home = Page.parse(h.read("0.pa"))
home.components[0].set("sta", 2)
home.components[0].set("pic", bg)
home.components[0].set_event("codesloadend", ["tm0.en=1"])
C.add(home, "text", "title", x=10, y=6, w=460, h=40, txt="nxhmi demo", font=big, sta=0, picc=bg,
pco=0xFFFF, xcen=0)
C.add(home, "button", "bControls", x=330, y=60, w=140, h=40, txt="controls", font=small,
events={"codesup": ["page controls"]})
C.add(home, "button", "bGallery", x=330, y=110, w=140, h=40, txt="gallery", font=small,
events={"codesup": ["page gallery"]})
C.add(home, "number", "nCount", x=10, y=60, w=150, h=40, val=1234, font=big, sta=1, bco=0xFFFF)
C.add(home, "xfloat", "xTemp", x=170, y=60, w=150, h=40, val=2155, vvs0=0, vvs1=2, font=big, sta=1, bco=0xFFFF)
C.add(home, "progress_bar", "jLoad", x=10, y=110, w=310, h=24, val=65)
C.add(home, "slider", "hLevel", x=10, y=145, w=310, h=30, val=40, minval=0, maxval=100,
events={"codesslide": ["jLoad.val=hLevel.val"]})
C.add(home, "checkbox", "cOn", x=10, y=190, w=30, h=30, val=1)
C.add(home, "text", "tOn", x=45, y=190, w=100, h=30, txt="enabled", font=small, sta=0, picc=bg, pco=0xFFFF, xcen=0)
C.add(home, "radio", "rA", x=150, y=190, w=30, h=30, val=1)
C.add(home, "radio", "rB", x=190, y=190, w=30, h=30, val=0)
C.add(home, "gauge", "zSpeed", x=10, y=230, w=80, h=80, val=135, wid=3, sta=1, bco=0xFFFF)
C.add(home, "picture", "pIcon", x=100, y=240, w=64, h=64, pic=ico)
C.add(home, "text", "tStatus", x=180, y=270, w=290, h=40, txt="status: ok", font=small, sta=1,
bco=0x0000, pco=0x07E0, xcen=0, style=1, borderw=2, borderc=0x07E0)
C.add(home, "timer", "tm0", tim=1000, en=0, events={"codestimer": ["nCount.val++"]})
C.add(home, "variable", "vaMode", val=1)
h.write("0.pa", home.pack())
# ---- page 1: controls
ctl = project.add_page(h, "controls", sta=1, bco=0xEF7D)
C.add(ctl, "button", "bBack", x=10, y=6, w=80, h=34, txt="< back", font=small, events={"codesup": ["page home"]})
C.add(ctl, "text", "tHead", x=100, y=6, w=370, h=34, txt="controls", font=big, sta=1, bco=0xEF7D, xcen=2)
for i, (xc, yc, st, label) in enumerate([(0, 0, 0, "left/top flat"), (1, 1, 1, "center border"),
(2, 2, 2, "right 3D down"), (1, 1, 3, "3D up")]):
C.add(ctl, "text", "tAlign%d" % i, x=10 + (i % 2) * 235, y=50 + (i // 2) * 55, w=225, h=48,
txt=label, font=small, xcen=xc, ycen=yc, style=st, borderw=2, borderc=0x001F, sta=1, bco=0xFFFF)
C.add(ctl, "text", "tWrap", x=10, y=162, w=150, h=60, txt="word wrap inside a narrow box", font=small,
isbr=1, sta=1, bco=0xFFFF, style=1, borderw=1, borderc=0)
C.add(ctl, "dual_state_button", "btOff", x=170, y=162, w=140, h=28, txt="off", font=small, val=0)
C.add(ctl, "dual_state_button", "btOn", x=170, y=194, w=140, h=28, txt="on", font=small, val=1)
C.add(ctl, "scrolling_text", "gNews", x=320, y=162, w=150, h=28, txt="scrolling text", font=small, sta=1, bco=0xFFFF)
C.add(ctl, "number", "nHex", x=320, y=194, w=150, h=28, val=48879, format=2, font=small, sta=1, bco=0xFFFF)
C.add(ctl, "waveform", "sWave", x=10, y=230, w=300, h=80, ch=1)
C.add(ctl, "progress_bar", "jVert", x=320, y=230, w=30, h=80, val=70, dez=1)
C.add(ctl, "slider", "hVert", x=360, y=230, w=30, h=80, val=30, mode=1)
C.add(ctl, "hotspot", "mHot", x=400, y=230, w=70, h=80, events={"codesup": ["page home"]})
h.write("1.pa", ctl.pack())
# ---- page 2: gallery (pictures as backgrounds and skins)
gal = project.add_page(h, "gallery", sta=1, bco=0xFFFF)
C.add(gal, "button", "bBack", x=10, y=6, w=80, h=34, txt="< back", font=small, events={"codesup": ["page home"]})
C.add(gal, "crop", "qBg", x=100, y=6, w=370, h=34, picc=bg)
C.add(gal, "picture", "pIcon", x=10, y=50, w=64, h=64, pic=ico)
C.add(gal, "button", "bSkin", x=90, y=50, w=140, h=40, txt="skinned", font=small, sta=2, pic=sk1, pic2=sk2, pco=0xFFFF)
C.add(gal, "dual_state_button", "btSkin", x=240, y=50, w=140, h=40, txt="dual on", font=small, sta=2,
pic=sk1, pic2=sk2, pco=0xFFFF, val=1)
C.add(gal, "progress_bar", "jSkin", x=90, y=100, w=200, h=24, sta=1, bpic=bar, ppic=barfg, val=55)
C.add(gal, "text", "tCrop", x=10, y=140, w=460, h=60, txt="text on a cropped background", font=big,
sta=0, picc=bg, pco=0xFFFF)
C.add(gal, "text", "tImg", x=10, y=210, w=200, h=40, txt="image bg", font=small, sta=2, pic=sk2, pco=0)
h.write("2.pa", gal.pack())
return h
def main():
out = os.path.join(ROOT, "demo")
os.makedirs(out, exist_ok=True)
h = build()
path = os.path.join(out, "demo.HMI")
h.save(path)
dec = os.path.join(out, "decoded")
shutil.rmtree(dec, ignore_errors=True)
project.decode(path, dec)
r = Renderer(h)
os.makedirs(os.path.join(out, "render"), exist_ok=True)
for name in ("home", "controls", "gallery"):
r.render(name).save(os.path.join(out, "render", name + ".png"))
print("wrote", path, "+ decoded/ + render/")
if __name__ == "__main__":
main()
+23
View File
@@ -0,0 +1,23 @@
[build-system]
requires = ["setuptools>=61"]
build-backend = "setuptools.build_meta"
[project]
name = "openhmi-nx"
version = "0.1.0"
description = "Read, verify and write Nextion Editor .HMI project files without the Editor"
readme = "README.md"
license = {text = "MIT"}
requires-python = ">=3.9"
[project.scripts]
nxhmi = "nxhmi.cli:main"
[tool.setuptools.packages.find]
where = ["src"]
[tool.setuptools.package-data]
nxhmi = ["*.json"]
[project.optional-dependencies]
images = ["pillow>=10.1"]
+7
View File
@@ -0,0 +1,7 @@
"""nxhmi -- read, verify and write Nextion Editor .HMI project files without the Editor."""
from .checksum import page_crc, main_crc, table_crc
from .container import HMIFile, build
from .page import Page, Component, Attr, Group
__version__ = "0.1.0"
__all__ = ["page_crc", "main_crc", "table_crc", "HMIFile", "build", "Page", "Component", "Attr", "Group"]
+5
View File
@@ -0,0 +1,5 @@
import sys
from .cli import main
sys.exit(main())
+91
View File
@@ -0,0 +1,91 @@
"""Checksums used inside Nextion Editor .HMI project files.
All three are CRC-32 with polynomial 0x04C11DB7, processed MSB-first (no bit reflection),
initial value 0xFFFFFFFF and no final XOR -- i.e. the algorithm of the STM32 hardware CRC unit.
They differ only in how the input is fed:
* ``word_per_byte_crc`` -- every input *byte* is zero-extended and fed as one 32-bit word.
Used for pages (``*.pa``) and the project header (``main.HMI``), each followed by a
10-byte "tail" (see :func:`page_crc` / :func:`main_crc`).
* ``dword_crc`` -- input is read as little-endian 32-bit words. Used for the file table,
followed by the constant word 0x43454441 (ASCII "ADEC").
These were reverse-engineered black-box (by editing projects in the Editor and comparing
saved files); see docs/FORMAT.md for the evidence.
"""
from __future__ import annotations
import struct
POLY = 0x04C11DB7
INIT = 0xFFFFFFFF
TABLE_MAGIC = 0x43454441 # "ADEC"
_TABLE = []
for _i in range(256):
_c = _i << 24
for _ in range(8):
_c = ((_c << 1) ^ POLY) & 0xFFFFFFFF if _c & 0x80000000 else (_c << 1) & 0xFFFFFFFF
_TABLE.append(_c)
def _feed_byte(c: int, b: int) -> int:
return ((c << 8) & 0xFFFFFFFF) ^ _TABLE[((c >> 24) ^ b) & 0xFF]
def _feed_word(c: int, w: int) -> int:
"""Feed one 32-bit word MSB-first (== its 4 big-endian bytes)."""
c = _feed_byte(c, (w >> 24) & 0xFF)
c = _feed_byte(c, (w >> 16) & 0xFF)
c = _feed_byte(c, (w >> 8) & 0xFF)
return _feed_byte(c, w & 0xFF)
def _feed_byte_as_word(c: int, b: int) -> int:
# word 0x000000bb: three zero bytes then b
c = _TABLE[(c >> 24) & 0xFF] ^ ((c << 8) & 0xFFFFFFFF)
c = _TABLE[(c >> 24) & 0xFF] ^ ((c << 8) & 0xFFFFFFFF)
c = _TABLE[(c >> 24) & 0xFF] ^ ((c << 8) & 0xFFFFFFFF)
return _feed_byte(c, b)
def word_per_byte_crc(data: bytes, crc: int = INIT) -> int:
for b in data:
crc = _feed_byte_as_word(crc, b)
return crc
def dword_crc(data: bytes, crc: int = INIT) -> int:
if len(data) % 4:
raise ValueError("dword_crc needs a multiple of 4 bytes")
for (w,) in struct.iter_unpack("<I", data):
crc = _feed_word(crc, w)
return crc
def page_crc(page: bytes) -> int:
"""CRC stored in the first 4 bytes of a page (``N.pa``) blob.
Input: page[4:], then datasize (LE32, header offset 4), numberobj (LE32, offset 12),
and the header bytes at offsets 20 and 21 -- each byte fed as a word.
"""
datasize, = struct.unpack_from("<I", page, 4)
nobj, = struct.unpack_from("<I", page, 12)
tail = struct.pack("<II", datasize, nobj) + page[20:22]
return word_per_byte_crc(page[4:] + tail)
def main_crc(main: bytes) -> int:
"""CRC stored in the first 4 bytes of the ``main.HMI`` project header blob.
Input: main[4:], then main[16:20] (model id), main[4:8], main[10], main[14].
NOTE: the last two tail bytes were 0x21, 0x4F in every sample seen; they are taken from
offsets 10 and 14 where those values live, but could also be constants (format version).
"""
tail = main[16:20] + main[4:8] + main[10:11] + main[14:15]
return word_per_byte_crc(main[4:] + tail)
def table_crc(table: bytes) -> int:
"""Checksum stored right after the file table (count + entries)."""
return _feed_word(dword_crc(table), TABLE_MAGIC)
+195
View File
@@ -0,0 +1,195 @@
"""Command line interface: ``python -m nxhmi <command> ...``"""
from __future__ import annotations
import argparse
import json
import sys
from . import checksum, project
from .container import HMIFile
from .page import Page
def cmd_info(a):
h = HMIFile.load(a.hmi)
t0, t1 = h.table_ok()
print("file table: primary %s, backup %s" % ("ok" if t0 else "BAD", "ok" if t1 else "BAD"))
for e in h.entries:
flag = "deleted" if e.deleted else ""
shown = e.name if not e.deleted else "(%s)" % e.name.encode("latin-1").decode("ascii", "replace").replace("�", "?").replace("\0", "?")
line = "%-16s %8d bytes @0x%07X %s" % (shown, e.size, e.start, flag)
if not e.deleted and e.name.endswith(".pa"):
blob = h.read(e.name)
ok = checksum.page_crc(blob) == int.from_bytes(blob[:4], "little")
p = Page.parse(blob, verify=False)
line += " page %-14s %3d components crc %s" % (p.name, len(p.components), "ok" if ok else "BAD")
print(line)
def cmd_verify(a):
bad = 0
for path in a.hmi:
h = HMIFile.load(path)
for e in h.live():
blob = h.read(e.name)
stored = int.from_bytes(blob[:4], "little")
if e.name.endswith(".pa") and checksum.page_crc(blob) != stored:
print("%s: %s page checksum BAD" % (path, e.name)); bad += 1
if e.name == "main.HMI" and checksum.main_crc(blob) != stored:
print("%s: main.HMI checksum BAD" % path); bad += 1
t0, t1 = h.table_ok()
if not (t0 and t1):
print("%s: file table checksum BAD (primary %s, backup %s)" % (path, t0, t1)); bad += 1
if not bad:
print("%s: ok" % path)
return 1 if bad else 0
def cmd_decode(a):
m = project.decode(a.hmi, a.out, a.encoding, not a.raw)
print("decoded %d entries into %s" % (len(m["entries"]), a.out))
def cmd_encode(a):
project.encode(a.folder, a.hmi)
print("wrote", a.hmi)
def cmd_set(a):
"""Set one attribute in place: nxhmi set file.HMI page objname attr value [-o out]"""
h = HMIFile.load(a.hmi)
for e in h.live():
if not e.name.endswith(".pa"):
continue
p = Page.parse(h.read(e.name))
if p.name != a.page:
continue
c = p.component(a.component)
if c is None:
sys.exit("no component %r on page %r" % (a.component, a.page))
kind, _ = c.attr(a.attr).decoded()
c.set(a.attr, a.value if kind in ("str", "hex") else int(a.value, 0))
h.write(e.name, p.pack())
h.save(a.out or a.hmi)
print("set %s.%s.%s = %s" % (a.page, a.component, a.attr, a.value))
return
sys.exit("no page %r" % a.page)
def cmd_add(a):
"""Add a component: nxhmi add file.HMI page kind [name=value ...] [--name obj] [-o out]"""
from . import components
h = HMIFile.load(a.hmi)
for e in h.live():
if not e.name.endswith(".pa"):
continue
p = Page.parse(h.read(e.name))
if p.name != a.page:
continue
kw = {}
for item in a.attrs:
k, _, v = item.partition("=")
try:
kw[k] = int(v, 0)
except ValueError:
kw[k] = v
c = components.add(p, a.kind, a.name, **kw)
h.write(e.name, p.pack())
h.save(a.out or a.hmi)
print("added %s (%s, id %d) to page %s" % (c.name, a.kind, c.get("id"), p.name))
return
sys.exit("no page %r" % a.page)
def cmd_new_page(a):
from . import project
h = HMIFile.load(a.hmi)
project.add_page(h, a.name)
h.save(a.out or a.hmi)
print("added page", a.name)
def cmd_add_font(a):
from . import fonts, project
h = HMIFile.load(a.hmi)
f = fonts.from_ttf(a.ttf, a.height, a.encoding, a.fixed_width)
fid = project.add_font(h, f)
h.save(a.out or a.hmi)
print("added font id %d (%s, %d chars)" % (fid, f.name, len(f.glyphs)))
def cmd_add_picture(a):
from . import project
h = HMIFile.load(a.hmi)
with open(a.image, "rb") as f:
pid = project.add_picture(h, f.read())
h.save(a.out or a.hmi)
print("added picture id", pid)
def cmd_render(a):
import os
from .render import Renderer
r = Renderer(HMIFile.load(a.hmi))
names = [k for k in r.pages if isinstance(k, str)]
todo = names if a.page in (None, "all") else [a.page]
os.makedirs(a.out, exist_ok=True)
for n in todo:
path = os.path.join(a.out, "%s.png" % n)
r.render(n).save(path)
print("wrote", path)
def cmd_kinds(a):
from . import components
for k in components.kinds():
print(k)
def cmd_dump(a):
h = HMIFile.load(a.hmi)
for e in h.live():
if e.name.endswith(".pa"):
p = Page.parse(h.read(e.name))
if a.page and p.name != a.page:
continue
print(json.dumps(project.page_to_json(e.name, p, a.encoding, not a.raw), indent=1, ensure_ascii=False))
def main(argv=None):
ap = argparse.ArgumentParser(prog="nxhmi", description="Read, verify and write Nextion Editor .HMI projects")
sub = ap.add_subparsers(dest="cmd", required=True)
s = sub.add_parser("info", help="list entries, pages and checksum status"); s.add_argument("hmi"); s.set_defaults(f=cmd_info)
s = sub.add_parser("verify", help="check every checksum"); s.add_argument("hmi", nargs="+"); s.set_defaults(f=cmd_verify)
s = sub.add_parser("decode", help="HMI -> folder of JSON/text"); s.add_argument("hmi"); s.add_argument("out")
s.add_argument("--encoding", default="latin-1"); s.add_argument("--raw", action="store_true", help="numbers instead of names/colours")
s.set_defaults(f=cmd_decode)
s = sub.add_parser("encode", help="folder -> new HMI"); s.add_argument("folder"); s.add_argument("hmi"); s.set_defaults(f=cmd_encode)
s = sub.add_parser("set", help="change one attribute")
for n in ("hmi", "page", "component", "attr", "value"):
s.add_argument(n)
s.add_argument("-o", "--out"); s.set_defaults(f=cmd_set)
s = sub.add_parser("add", help="add a component to a page (kind: see 'kinds')")
s.add_argument("hmi"); s.add_argument("page"); s.add_argument("kind")
s.add_argument("attrs", nargs="*", help="attribute=value, e.g. x=10 y=20 txt=Hi")
s.add_argument("--name"); s.add_argument("-o", "--out"); s.set_defaults(f=cmd_add)
s = sub.add_parser("render", help="render pages to PNG like the Editor's canvas (needs Pillow)")
s.add_argument("hmi"); s.add_argument("out", help="output folder"); s.add_argument("--page", help="page name (default: all)")
s.set_defaults(f=cmd_render)
s = sub.add_parser("kinds", help="list component kinds that can be added"); s.set_defaults(f=cmd_kinds)
s = sub.add_parser("add-font", help="rasterize a .ttf into a new font (needs Pillow)")
s.add_argument("hmi"); s.add_argument("ttf"); s.add_argument("height", type=int)
s.add_argument("--encoding", default="ascii", choices=["ascii", "iso-8859-1"])
s.add_argument("--fixed-width", type=int); s.add_argument("-o", "--out"); s.set_defaults(f=cmd_add_font)
s = sub.add_parser("add-picture", help="add a picture (png/jpg/bmp; needs Pillow)")
s.add_argument("hmi"); s.add_argument("image"); s.add_argument("-o", "--out"); s.set_defaults(f=cmd_add_picture)
s = sub.add_parser("new-page", help="add an empty page"); s.add_argument("hmi"); s.add_argument("name")
s.add_argument("-o", "--out"); s.set_defaults(f=cmd_new_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)
a = ap.parse_args(argv)
return a.f(a) or 0
if __name__ == "__main__":
sys.exit(main())
+88
View File
@@ -0,0 +1,88 @@
"""Create new components from the Editor's own defaults.
templates_basic.json / templates_intelligent.json hold, per component type, the full attribute
list (name, kind, default) and event groups exactly as Nextion Editor writes a freshly placed
component (regenerate with tools/make_templates.py). Basic types are available on every series;
the Intelligent file adds the types that only exist there (video, audio, combobox, ...).
"""
from __future__ import annotations
import json
import os
from .page import Attr, Component, Group, Page
_HERE = os.path.dirname(os.path.abspath(__file__))
def _load(fn):
with open(os.path.join(_HERE, fn), encoding="utf-8") as f:
return {int(k): v for k, v in json.load(f)["types"].items()}
BASIC = _load("templates_basic.json")
INTELLIGENT = _load("templates_intelligent.json")
TYPES = dict(INTELLIGENT)
TYPES.update(BASIC) # basic defaults win for shared types
KINDS = {v["kind"]: k for k, v in TYPES.items()}
INTELLIGENT_ONLY = sorted(v["kind"] for k, v in INTELLIGENT.items() if k not in BASIC)
def kinds() -> list[str]:
return sorted(KINDS)
def _type(kind) -> dict:
return TYPES[KINDS[kind] if isinstance(kind, str) else int(kind)]
def make(kind, objname: str, id_: int, **attrs) -> Component:
"""Build a component of ``kind`` (name like "button" or numeric type) with Editor defaults.
Keyword arguments set attributes (x=, y=, w=, h=, txt=, ...); endx/endy follow x/y/w/h.
``events={"codesdown": ["page 1"]}`` sets event code.
"""
t = _type(kind)
events = attrs.pop("events", {})
comp = Component([Group("att", [Attr.encode(n, k, v) for n, k, v in t["att"]])] +
[Group(g, []) for g in t["events"]])
comp.set("objname", objname)
comp.set("id", id_)
for k, v in attrs.items():
comp.set(k, v)
_fix_ends(comp)
for g, lines in events.items():
comp.set_event(g, lines)
return comp
def _fix_ends(c: Component) -> None:
names = {a.name for a in c.attrs()}
if {"x", "w", "endx"} <= names:
c.set("endx", c.get("x") + c.get("w") - 1)
if {"y", "h", "endy"} <= names:
c.set("endy", c.get("y") + c.get("h") - 1)
def add(page: Page, kind, objname: str | None = None, **attrs) -> Component:
"""Append a new component to ``page`` with the next free id and a unique objname."""
t = _type(kind)
used = {c.name for c in page.components}
if objname is None:
n = 0
while "%s%d" % (t["prefix"], n) in used:
n += 1
objname = "%s%d" % (t["prefix"], n)
elif objname in used:
raise ValueError("objname %r already used on page %r" % (objname, page.name))
next_id = max((c.get("id") or 0) for c in page.components) + 1 if page.components else 0
comp = make(kind, objname, next_id, **attrs)
page.components.append(comp)
return comp
def new_page(name: str, **attrs) -> Page:
"""A page with only its page component (id 0). Defaults to a plain white background."""
attrs.setdefault("sta", 1) # 1 = solid colour, 2 = picture
attrs.setdefault("bco", 0xFFFF)
return Page(name, [make(121, name, 0, **attrs)])
+172
View File
@@ -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
+86
View File
@@ -0,0 +1,86 @@
"""Readable names for attribute values.
All value lists come from Nextion Editor 1.68's own attribute notes (read via UI Automation from the
Attribute panel), e.g. "Horizontal alignment:0-Left;1-Center;2-Right". A few attributes mean
different things per component type, hence the per-type overrides.
Colours (RGB565 in the file) are shown as "#rrggbb"; conversion is exact in both directions for
values that came from a file (5/6-bit channels are expanded by bit replication).
"""
from __future__ import annotations
# attribute -> {value: label}, valid for every component type unless overridden below
GENERAL = {
"vscope": {0: "local", 1: "global"},
"sta": {0: "crop image", 1: "solid color", 2: "image"},
"style": {0: "flat", 1: "border", 2: "3D_Down", 3: "3D_Up"},
"xcen": {0: "left", 1: "center", 2: "right"},
"ycen": {0: "up", 1: "center", 2: "down"},
"isbr": {0: "false", 1: "true"},
"pw": {0: "character", 1: "password"},
}
# component type -> attribute -> {value: label}
BY_TYPE = {
121: {"sta": {0: "no background", 1: "solid color", 2: "image"}}, # page
98: {"style": {0: "flat", 1: "border", 2: "3D_Down", 3: "3D_Up", 4: "3D_Auto"}}, # button
53: {"style": {0: "flat", 1: "border", 2: "3D_Down", 3: "3D_Up", 4: "3D_Auto"}}, # dual-state button
54: {"format": {0: "decimal", 1: "currency", 2: "hex"}}, # number
59: {"format": {0: "decimal", 1: "currency", 2: "hex"}}, # xfloat
55: {"dir": {0: "left to right", 1: "right to left", 2: "up to down", 3: "down to up"},
"en": {0: "disable", 1: "enable"}}, # scrolling text
51: {"en": {0: "disable", 1: "enable"}}, # timer
52: {"sta": {0: "number", 1: "string"}}, # variable
1: {"mode": {0: "horizontal", 1: "vertical"}, "psta": {0: "solid", 1: "image"}}, # slider
106: {"sta": {0: "solid color", 1: "image"}, "dez": {0: "horizontal", 1: "vertical"}}, # progress bar
0: {"dir": {0: "left to right", 1: "right to left", 2: "right align"}}, # waveform
58: {"sta": {0: "none", 1: "has"}}, # qrcode (logo)
}
COLOR_ATTRS = {"bco", "bco1", "bco2", "pco", "pco0", "pco1", "pco2", "pco3", "borderc", "gdc"}
def table(ctype: int | None, attr: str) -> dict | None:
if ctype is not None and attr in BY_TYPE.get(ctype, {}):
return BY_TYPE[ctype][attr]
return GENERAL.get(attr)
def rgb565_to_hex(v: int) -> str:
r, g, b = v >> 11, (v >> 5) & 63, v & 31
return "#%02x%02x%02x" % (r << 3 | r >> 2, g << 2 | g >> 4, b << 3 | b >> 2)
def hex_to_rgb565(s: str) -> int:
s = s.lstrip("#")
r, g, b = int(s[0:2], 16), int(s[2:4], 16), int(s[4:6], 16)
return (r >> 3) << 11 | (g >> 2) << 5 | (b >> 3)
def to_label(ctype: int | None, attr: str, kind: str, value):
"""int -> readable value (label / '#rrggbb'), or the value unchanged."""
if kind not in ("u8", "u16", "u32"):
return value
if attr in COLOR_ATTRS and kind == "u16":
return rgb565_to_hex(value)
t = table(ctype, attr)
if t and value in t:
return t[value]
return value
def from_label(ctype: int | None, attr: str, kind: str, value):
"""Inverse of to_label; accepts plain ints too."""
if not isinstance(value, str) or kind not in ("u8", "u16", "u32"):
return value
if value.startswith("#") and len(value) == 7:
return hex_to_rgb565(value)
t = table(ctype, attr)
if t:
for k, v in t.items():
if v.lower() == value.lower():
return k
try:
return int(value, 0)
except ValueError:
raise ValueError("unknown value %r for attribute %r" % (value, attr))
+213
View File
@@ -0,0 +1,213 @@
"""Nextion fonts (``N.zi`` entries), file format version 6, black/white glyphs.
Header (44 bytes, little-endian)::
0 4 magic 04 FF 00 0B (byte 3: 0x0B -- 0x0A "vertical" in older docs; OPEN)
4 2 encoding (1 ascii, 3 iso-8859-1, ...)
6 1 character width (fixed-width fonts; per-glyph width in the map)
7 1 character height
8 1 multi-byte first-byte start 9 1 ... end
10 1 code range start 11 1 code range end
12 4 character count
16 1 format version (6)
17 1 name length
18 1 name length (again)
19 1 0
20 4 length of name + map + glyph data
24 4 start of name (0x2C)
28 16 unknown (kept as-is)
44 . name, then character map, then glyph data
Character map: ``count`` entries of 10 bytes::
0 2 character code 2 1 glyph width 3 1 ? 4 1 ?
5 3 glyph data offset (relative to the start of the map)
8 2 glyph data length
Glyph data: one mode byte (0x01 = black/white), then run-length codes. Pixels are scanned
column by column (x = 0..w-1), each column from the bottom row up -- the same 90-degree panel
rotation as pictures. Codes (top two bits = op)::
00 0xxxxx x transparent 00 1xxxxx x ink
01 0xxxxx x transparent + 1 ink 01 1xxxxx x transparent + 2 ink
10 0xxxxx x transparent + 3 ink 10 1xxxxx x transparent + 4 ink
11 tttiii ttt transparent + iii ink
Runs continue across column boundaries.
"""
from __future__ import annotations
import struct
from dataclasses import dataclass, field
HEADER_SIZE = 0x2C
MAP_ENTRY = 10
@dataclass
class Glyph:
code: int
width: int
pixels: list # rows top->bottom of 0/1 (len = height, each len = width)
map_extra: bytes = b"\0\0" # map bytes 3..4
mode: int = 1
@dataclass
class Font:
name: str
width: int
height: int
encoding: int
first: int
last: int
glyphs: list = field(default_factory=list)
header: bytes = b"" # original 44-byte header, for fields not modelled
# ------------------------------------------------------------------ decode
@classmethod
def parse(cls, blob: bytes) -> "Font":
if blob[:3] != b"\x04\xff\x00":
raise ValueError("not a .zi font")
if blob[16] != 6:
raise ValueError("unsupported .zi version %d (only 6 is implemented)" % blob[16])
w, h = blob[6], blob[7]
count, = struct.unpack_from("<I", blob, 12)
nlen = blob[17]
start, = struct.unpack_from("<I", blob, 24)
name = blob[start:start + nlen].decode("latin-1")
m = start + nlen
f = cls(name, w, h, struct.unpack_from("<H", blob, 4)[0], blob[10], blob[11], [], bytes(blob[:HEADER_SIZE]))
for i in range(count):
e = blob[m + MAP_ENTRY * i: m + MAP_ENTRY * (i + 1)]
code, gw = struct.unpack_from("<HB", e, 0)
off = e[5] | e[6] << 8 | e[7] << 16
ln, = struct.unpack_from("<H", e, 8)
data = blob[m + off: m + off + ln]
f.glyphs.append(Glyph(code, gw, decode_glyph(data, gw, h), bytes(e[3:5]), data[0]))
return f
# ------------------------------------------------------------------ encode
def pack(self) -> bytes:
name = self.name.encode("latin-1")
bodies = [bytes([g.mode]) + encode_glyph(g.pixels, g.width, self.height) for g in self.glyphs]
mp = bytearray()
off = MAP_ENTRY * len(self.glyphs)
for g, b in zip(self.glyphs, bodies):
mp += struct.pack("<HB", g.code, g.width) + g.map_extra[:2].ljust(2, b"\0")
mp += bytes([off & 0xFF, (off >> 8) & 0xFF, off >> 16]) + struct.pack("<H", len(b))
off += len(b)
payload = name + bytes(mp) + b"".join(bodies)
hdr = bytearray(self.header or bytes(HEADER_SIZE))
hdr[0:4] = hdr[0:4] if self.header else b"\x04\xff\x00\x0b"
struct.pack_into("<H", hdr, 4, self.encoding)
hdr[6], hdr[7], hdr[10], hdr[11] = self.width, self.height, self.first, self.last
struct.pack_into("<I", hdr, 12, len(self.glyphs))
hdr[16], hdr[17], hdr[18] = 6, len(name), len(name)
struct.pack_into("<II", hdr, 20, len(payload), HEADER_SIZE)
return bytes(hdr) + payload
def glyph(self, ch) -> Glyph | None:
code = ord(ch) if isinstance(ch, str) else ch
for g in self.glyphs:
if g.code == code:
return g
return None
def _scan_order(w: int, h: int):
for x in range(w):
for y in range(h - 1, -1, -1):
yield x, y
def decode_glyph(data: bytes, w: int, h: int) -> list:
stream = []
for b in data[1:]:
op, bit, x = b >> 6, (b >> 5) & 1, b & 0x1F
if op == 0:
stream += [bit] * x
elif op == 3:
stream += [0] * ((b >> 3) & 7) + [1] * (b & 7)
else:
stream += [0] * x + [1] * (op * 2 - 1 + bit)
rows = [[0] * w for _ in range(h)]
for v, (x, y) in zip(stream, _scan_order(w, h)):
rows[y][x] = v
return rows
def encode_glyph(rows: list, w: int, h: int) -> bytes:
"""Run-length encode a glyph (rows top->bottom). Greedy, see docs for the code table."""
s = [rows[y][x] for x, y in _scan_order(w, h)]
out = bytearray()
i, n = 0, len(s)
while i < n:
t = 0
while i + t < n and s[i + t] == 0:
t += 1
k = 0
while i + t + k < n and s[i + t + k] == 1:
k += 1
if t == 0: # ink run
run = min(k, 31)
out.append(0x20 | run); i += run; continue
if k == 0: # transparent up to end
run = min(t, 31)
out.append(run); i += run; continue
# The Editor's choice (reproduces its output byte for byte): "x transparent + 1..4 ink" when
# it fits, else "ttt transparent + iii ink", else a plain transparent run.
if t <= 31 and 1 <= k <= 4:
op, bit = (k + 1) // 2, (k + 1) % 2
out.append(op << 6 | bit << 5 | t); i += t + k; continue
if t <= 7 and k <= 7:
out.append(0xC0 | t << 3 | k); i += t + k; continue
run = min(t, 31)
out.append(run); i += run
return bytes(out)
ENCODINGS = {"ascii": (1, 0x20, 0x7E), "iso-8859-1": (3, 0x20, 0xFF)}
def from_ttf(path: str | None, height: int, encoding: str = "ascii", fixed_width: int | None = None,
name: str | None = None, threshold: int = 128) -> "Font":
"""Rasterize a TrueType/OpenType font into a black/white Nextion font (needs Pillow).
``path=None`` uses Pillow's bundled default font (Aileron Regular, CC0) -- handy for tests and
demos. The font size is chosen so ascent + descent fills ``height`` pixels. Glyph widths follow
the font's advance widths unless ``fixed_width`` is given.
"""
import os
from PIL import Image, ImageDraw, ImageFont
enc, first, last = ENCODINGS[encoding]
def load(size):
return ImageFont.load_default(size=size) if path is None else ImageFont.truetype(path, size)
size = height
while size > 4:
f = load(size)
a, d = f.getmetrics()
if a + d <= height:
break
size -= 1
ascent, descent = f.getmetrics()
top = (height - ascent - descent) // 2
glyphs = []
for code in range(first, last + 1):
ch = bytes([code]).decode("latin-1")
adv = fixed_width or max(1, int(round(f.getlength(ch))))
img = Image.new("L", (adv, height), 0)
ImageDraw.Draw(img).text((0, top), ch, font=f, fill=255)
px = img.load()
rows = [[1 if px[x, y] >= threshold else 0 for x in range(adv)] for y in range(height)]
glyphs.append(Glyph(code, adv, rows))
width = fixed_width or max(g.width for g in glyphs)
stem = "Aileron" if path is None else os.path.splitext(os.path.basename(path))[0]
base = name or "%s-%d%s" % (stem, height, encoding)
hdr = bytearray(HEADER_SIZE)
hdr[0:4] = b"\x04\xff\x00\x0b"
hdr[0x1C] = last
hdr[0x20] = 0x0B
struct.pack_into("<I", hdr, 0x24, len(glyphs))
return Font(base[:255], width, height, enc, first, last, glyphs, bytes(hdr))
+33
View File
@@ -0,0 +1,33 @@
"""Display models: id stored in main.HMI (offset 16), series byte (offset 11), native resolution.
Only series whose series byte was confirmed in the Editor are listed (Basic = 0, Intelligent = 3).
Model ids are the 32-bit values the Editor writes for each model.
"""
from __future__ import annotations
# name: (model id, series byte, width, height)
MODELS = {
"NX3224T024_011": (0xF59677A7, 0, 320, 240),
"NX3224T028_011": (0x1443383B, 0, 320, 240),
"NX4024T032_011": (0x6D494DA9, 0, 400, 240),
"NX4832T035_011": (0xB23BC018, 0, 480, 320),
"NX4827T043_011": (0xCA296EB1, 0, 480, 272),
"NX8048T050_011": (0x87AD3AE3, 0, 800, 480),
"NX8048T070_011": (0x081FBDCC, 0, 800, 480),
"NX4827P043_011": (0x181169DA, 3, 480, 272),
"NX8048P050_011": (0x55953D88, 3, 800, 480),
"NX8048P070_011": (0xDA27BAA7, 3, 800, 480),
"NX1060P070_011": (0xC43473C2, 3, 1024, 600),
"NX1060P101_011": (0x4FC44FA0, 3, 1024, 600),
}
BY_ID = {v[0]: k for k, v in MODELS.items()}
SERIES = {0: "Basic", 3: "Intelligent"}
# main.HMI text-encoding index (offset 12). Only the value seen in real projects is listed.
ENCODINGS = {"iso-8859-1": 1}
def lookup(model: str):
if model not in MODELS:
raise KeyError("unknown model %r; known: %s" % (model, ", ".join(sorted(MODELS))))
return MODELS[model]
+228
View File
@@ -0,0 +1,228 @@
"""Pages (``N.pa`` entries): header, component table, components.
Page blob layout (little-endian):
0 u32 crc (checksum.page_crc)
4 u32 datasize (= len(blob))
8 u32 infoaddr (= 56, start of the component table)
12 u32 numberobj (component count)
16 u32 password
20 u8 locked
21 u8 unknown (0x4F in every file seen)
22 u8 version (0x21 = 33 in every file seen)
23 u8 unknown
24 16s page name
40 16s reserved
56 numberobj * (u32 offset, u32 size, u32 unknown) -- offset relative to byte 56
... component data
Component data is a sequence of length-prefixed records (u32 len + bytes) ending with an empty
record. Records are grouped: a header record ``b"<group>-<n>"`` is followed by n records.
Group ``att`` holds attributes (16-byte NUL padded name + value); the other groups
(``codesload``, ``codesdown``, ``codesup``, ``codestimer``, ...) hold event code lines.
"""
from __future__ import annotations
import struct
from dataclasses import dataclass, field
from . import checksum
HEADER_SIZE = 56
TABLE_ENTRY = 12
# Text attributes: objname, plus every attribute that has a length-limit companion in the same
# component (txt/txt_maxl, path/path_m, dir/dir_m, filter/filter_m, format/format_m, ...).
# The same name can be text in one component and a number in another (e.g. `dir`, `format`).
# Everything else is an unsigned little-endian integer of 1, 2 or 4 bytes.
ALWAYS_STRING = {"objname"}
def _string_names(names) -> set:
names = set(names)
return {n for n in names if n in ALWAYS_STRING or n + "_m" in names or n + "_maxl" in names}
@dataclass
class Attr:
name: str
value: bytes
string: bool = False
def decoded(self, encoding: str = "latin-1"):
if self.string:
return ("str", self.value.decode(encoding))
n = len(self.value)
if n in (1, 2, 4):
return ({1: "u8", 2: "u16", 4: "u32"}[n], int.from_bytes(self.value, "little"))
return ("hex", self.value.hex())
@staticmethod
def encode(name: str, kind: str, value, encoding: str = "latin-1") -> "Attr":
if kind == "str":
return Attr(name, value.encode(encoding), True)
if kind in ("u8", "u16", "u32"):
n = {"u8": 1, "u16": 2, "u32": 4}[kind]
v = int(value)
if v < 0: # signed values (e.g. number.val) are stored two's complement
v &= (1 << (8 * n)) - 1
return Attr(name, v.to_bytes(n, "little"))
if kind == "hex":
return Attr(name, bytes.fromhex(value))
raise ValueError(kind)
def pack(self) -> bytes:
return self.name.encode("latin-1")[:16].ljust(16, b"\0") + self.value
@dataclass
class Group:
name: str # "att", "codesdown", ...
records: list # list[Attr] for "att", list[bytes] for code groups
@dataclass
class Component:
groups: list[Group] = field(default_factory=list)
table_extra: int = 0 # third u32 of the component-table entry
trailing: bytes = b"" # bytes after the terminating empty record (normally none)
# --- convenience ------------------------------------------------------
def attrs(self) -> list[Attr]:
for g in self.groups:
if g.name == "att":
return g.records
return []
def attr(self, name: str) -> Attr | None:
for a in self.attrs():
if a.name == name:
return a
return None
def get(self, name: str, encoding: str = "latin-1"):
a = self.attr(name)
return None if a is None else a.decoded(encoding)[1]
def set(self, name: str, value, encoding: str = "latin-1") -> None:
a = self.attr(name)
if a is None:
raise KeyError(name)
kind, _ = a.decoded(encoding)
if kind == "hex" and not isinstance(value, (bytes, str)):
raise ValueError("raw attribute; pass hex string")
a.value = Attr.encode(name, kind, value, encoding).value
def event(self, group: str) -> list[str] | None:
for g in self.groups:
if g.name == group:
return [r.decode("latin-1") for r in g.records]
return None
def set_event(self, group: str, lines: list[str]) -> None:
for g in self.groups:
if g.name == group:
g.records = [ln.encode("latin-1") for ln in lines]
return
self.groups.append(Group(group, [ln.encode("latin-1") for ln in lines]))
@property
def name(self) -> str:
return self.get("objname") or ""
# --- (de)serialization -------------------------------------------------
@classmethod
def parse(cls, data: bytes, table_extra: int = 0) -> "Component":
recs = []
p = 0
while p < len(data):
n, = struct.unpack_from("<I", data, p)
rec = data[p + 4:p + 4 + n]
p += 4 + n
if n == 0:
break
recs.append(rec)
trailing = data[p:]
groups = []
i = 0
while i < len(recs):
gname, cnt = recs[i].rsplit(b"-", 1)
cnt = int(cnt)
body = recs[i + 1:i + 1 + cnt]
gname = gname.decode("latin-1")
if gname == "att":
body = [Attr(r[:16].rstrip(b"\0").decode("latin-1"), r[16:]) for r in body]
strs = _string_names(a.name for a in body)
for a in body:
a.string = a.name in strs
groups.append(Group(gname, list(body)))
i += 1 + cnt
return cls(groups, table_extra, trailing)
def pack(self) -> bytes:
out = bytearray()
def rec(b: bytes):
out.extend(struct.pack("<I", len(b)))
out.extend(b)
for g in self.groups:
rec(("%s-%d" % (g.name, len(g.records))).encode("latin-1"))
for r in g.records:
rec(r.pack() if isinstance(r, Attr) else r)
rec(b"")
out.extend(self.trailing)
return bytes(out)
@dataclass
class Page:
name: str
components: list[Component]
password: int = 0
locked: int = 0
b21: int = 0x4F
version: int = 0x21
b23: int = 0
reserved: bytes = bytes(16)
header_extra: bytes = b"" # unused; kept for symmetry
@classmethod
def parse(cls, blob: bytes, verify: bool = True) -> "Page":
if len(blob) < HEADER_SIZE:
raise ValueError("page too short")
crc, datasize, infoaddr, nobj, password = struct.unpack_from("<IIIII", blob, 0)
locked, b21, version, b23 = blob[20], blob[21], blob[22], blob[23]
name = blob[24:40].rstrip(b"\0").decode("latin-1")
reserved = bytes(blob[40:56])
if verify and crc != checksum.page_crc(blob):
raise ValueError("page %r: checksum mismatch" % name)
comps = []
for i in range(nobj):
off, size, extra = struct.unpack_from("<III", blob, infoaddr + TABLE_ENTRY * i)
start = infoaddr + off
comps.append(Component.parse(blob[start:start + size], extra))
return cls(name, comps, password, locked, b21, version, b23, reserved)
def pack(self) -> bytes:
bodies = [c.pack() for c in self.components]
table = bytearray()
off = TABLE_ENTRY * len(bodies)
for c, b in zip(self.components, bodies):
table += struct.pack("<III", off, len(b), c.table_extra)
off += len(b)
total = HEADER_SIZE + len(table) + sum(len(b) for b in bodies)
hdr = bytearray(HEADER_SIZE)
struct.pack_into("<IIIII", hdr, 0, 0, total, HEADER_SIZE, len(bodies), self.password)
hdr[20], hdr[21], hdr[22], hdr[23] = self.locked, self.b21, self.version, self.b23
hdr[24:40] = self.name.encode("latin-1")[:16].ljust(16, b"\0")
hdr[40:56] = self.reserved[:16].ljust(16, b"\0")
blob = bytearray(hdr + table + b"".join(bodies))
struct.pack_into("<I", blob, 0, checksum.page_crc(bytes(blob)))
return bytes(blob)
def component(self, objname: str) -> Component | None:
for c in self.components:
if c.name == objname:
return c
return None
+102
View File
@@ -0,0 +1,102 @@
"""Pictures: ``N.i`` (what the display uses) and ``N.is`` (the original source file).
``N.is`` header (27 bytes) + the original image file, unchanged::
0 4 0A 64 01 01
4 4 0
8 4 27 (data offset)
12 2 width 14 2 height
16 4 length of the embedded file
20 4 0
24 3 file type, e.g. b"png"
27 . the file
``N.i`` header (24 bytes) + pixels::
0 4 0B 64 01 <format> format 0 = raw RGB565 (Basic series), 4 = compressed (Intelligent; OPEN)
4 4 0
8 4 24 (data offset)
12 2 width 14 2 height
16 4 data length (format 0: width * height * 2)
20 4 0
Format 0 pixels are RGB565 little-endian, converted by plain truncation (r>>3, g>>2, b>>3) and
stored in the panel's native order: rotated 90 degrees, i.e. for each source column x, the rows
from bottom to top -- byte offset 2 * (x * height + (height - 1 - y)). Verified pixel-exact against
Editor output for a 480x320 and a 64x64 picture on a project with display direction 270 (OPEN:
other directions, main.HMI byte 13).
Pillow is only needed for converting to/from image files.
"""
from __future__ import annotations
import io
import struct
IS_MAGIC = b"\x0a\x64\x01\x01"
I_MAGIC = b"\x0b\x64\x01"
def source_info(blob: bytes) -> dict:
w, h, n = struct.unpack_from("<HHI", blob, 12)
return {"width": w, "height": h, "type": blob[24:27].rstrip(b"\0").decode("latin-1"), "length": n}
def source_file(blob: bytes) -> bytes:
"""The original image file embedded in an ``N.is`` entry."""
off, = struct.unpack_from("<I", blob, 8)
n, = struct.unpack_from("<I", blob, 16)
return blob[off:off + n]
def make_source(data: bytes, width: int, height: int, ftype: str = "png") -> bytes:
hdr = IS_MAGIC + struct.pack("<IIHHII", 0, 27, width, height, len(data), 0) + ftype.encode()[:3].ljust(3, b"\0")
return hdr + data
def info(blob: bytes) -> dict:
w, h, n = struct.unpack_from("<HHI", blob, 12)
return {"format": blob[3], "width": w, "height": h, "length": n}
def to_rgb565(pixels_rgb, width: int, height: int) -> bytes:
"""pixels_rgb: callable (x, y) -> (r, g, b)."""
out = bytearray(width * height * 2)
for x in range(width):
for y in range(height):
r, g, b = pixels_rgb(x, y)[:3]
v = (r >> 3) << 11 | (g >> 2) << 5 | (b >> 3)
struct.pack_into("<H", out, 2 * (x * height + (height - 1 - y)), v)
return bytes(out)
def make_picture(rgb565: bytes, width: int, height: int) -> bytes:
return I_MAGIC + b"\x00" + struct.pack("<IIHHII", 0, 24, width, height, len(rgb565), 0) + rgb565
def from_image_file(data: bytes):
"""Image file bytes (png/jpg/bmp) -> (N.i blob, N.is blob). Needs Pillow."""
from PIL import Image
img = Image.open(io.BytesIO(data))
ftype = (img.format or "png").lower()[:3]
rgb = img.convert("RGB")
px = rgb.load()
w, h = rgb.size
return make_picture(to_rgb565(lambda x, y: px[x, y], w, h), w, h), make_source(data, w, h, ftype)
def to_image(blob: bytes):
"""Decode a format-0 ``N.i`` to a Pillow image."""
from PIL import Image
d = info(blob)
if d["format"] != 0:
raise NotImplementedError("picture format %d (Intelligent compressed) not supported yet" % d["format"])
w, h = d["width"], d["height"]
img = Image.new("RGB", (w, h))
px = img.load()
for x in range(w):
for y in range(h):
v, = struct.unpack_from("<H", blob, 24 + 2 * (x * h + (h - 1 - y)))
r, g, b = v >> 11, (v >> 5) & 63, v & 31
px[x, y] = (r << 3 | r >> 2, g << 2 | g >> 4, b << 3 | b >> 2)
return img
+306
View File
@@ -0,0 +1,306 @@
"""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)
+362
View File
@@ -0,0 +1,362 @@
"""Render pages to images, the way Nextion Editor draws them on its canvas (needs Pillow).
Usage::
from nxhmi.render import Renderer
r = Renderer(HMIFile.load("project.HMI"))
r.render("main").save("main.png")
Covered: page background (colour / picture), picture, crop, text, scrolling text (static), number,
xfloat, button, dual-state button, slider, progress bar, checkbox, radio, gauge, waveform (frame +
grid), QR code (placeholder pattern). Invisible components (timer, variable, hotspot, touch cap)
draw nothing. See docs/RENDER.md for how close each one is to the Editor.
"""
from __future__ import annotations
import math
from .container import HMIFile
from .fonts import Font
from .page import Component, Page
from . import pictures
def rgb(v: int):
r, g, b = v >> 11, (v >> 5) & 63, v & 31
return (r << 3 | r >> 2, g << 2 | g >> 4, b << 3 | b >> 2)
class Renderer:
def __init__(self, hmi: HMIFile):
from PIL import Image # noqa: F401 (fail early if Pillow is missing)
self.h = hmi
self._pics = {}
self._fonts = {}
self.pages = {}
for e in hmi.live():
if e.name.endswith(".pa"):
p = Page.parse(hmi.read(e.name))
self.pages[p.name] = p
self.pages[int(e.name[:-3])] = p
# ------------------------------------------------------------------ resources
def pic(self, n: int):
if n not in self._pics:
try:
self._pics[n] = pictures.to_image(self.h.read("%d.i" % n))
except (KeyError, NotImplementedError):
self._pics[n] = None
return self._pics[n]
def font(self, n: int):
if n not in self._fonts:
try:
self._fonts[n] = Font.parse(self.h.read("%d.zi" % n))
except (KeyError, ValueError):
self._fonts[n] = None
return self._fonts[n]
# ------------------------------------------------------------------ page
def render(self, page) -> "Image":
from PIL import Image
p = self.pages[page]
pc = p.components[0]
w, h = pc.get("w") or 480, pc.get("h") or 320
img = Image.new("RGB", (w, h), (255, 255, 255))
sta = pc.get("sta")
if sta == 1:
img.paste(rgb(pc.get("bco")), (0, 0, w, h))
elif sta == 2:
pic = self.pic(pc.get("pic"))
if pic:
self._paste(img, pic, 0, 0, w, h, 0, 0)
for c in p.components[1:]:
self.draw(img, c)
return img
# ------------------------------------------------------------------ components
def draw(self, img, c: Component):
t = c.get("type")
fn = {116: self.text, 55: self.text, 98: self.text, 53: self.dual, 54: self.number, 59: self.xfloat,
112: self.picture, 113: self.crop, 1: self.slider, 106: self.progress, 56: self.checkbox,
57: self.radio, 122: self.gauge, 0: self.waveform, 58: self.qrcode}.get(t)
if fn:
fn(img, c)
@staticmethod
def _paste(img, src, sx, sy, w, h, dx, dy):
"""Paste src[sx:sx+w, sy:sy+h] at (dx, dy), clipped to src's real size (no black padding)."""
w = min(w, src.width - sx)
h = min(h, src.height - sy)
if w > 0 and h > 0:
img.paste(src.crop((sx, sy, sx + w, sy + h)), (dx, dy))
def _box(self, c):
x, y, w, h = c.get("x"), c.get("y"), c.get("w"), c.get("h")
return x, y, w, h
def _background(self, img, c, x, y, w, h):
sta = c.get("sta")
if sta == 0: # crop image: same area of picture picc
src = self.pic(c.get("picc"))
if src:
self._paste(img, src, x, y, w, h, x, y)
elif sta == 1:
img.paste(rgb(c.get("bco")), (x, y, x + w, y + h))
elif sta == 2:
src = self.pic(c.get("pic"))
if src:
self._paste(img, src, 0, 0, w, h, x, y)
def _border(self, img, c, x, y, w, h, override=None):
from PIL import ImageDraw
d = ImageDraw.Draw(img)
style = c.get("style") if override is None else override
if c.get("sta") in (0, 2) and c.get("type") in (98, 53):
return # picture-skinned buttons have no frame
if style == 1: # border
bw, bc = c.get("borderw") or 0, rgb(c.get("borderc") or 0)
for i in range(bw):
d.rectangle((x + i, y + i, x + w - 1 - i, y + h - 1 - i), outline=bc)
elif style in (2, 3, 4): # 3D down / up / auto(=up when released)
light, dark = (230, 226, 230), (65, 68, 65) # measured in Editor 1.68
if style == 2:
light, dark = dark, light
d.line((x, y, x + w - 1, y), fill=light); d.line((x, y, x, y + h - 1), fill=light)
d.line((x, y + h - 1, x + w - 1, y + h - 1), fill=dark); d.line((x + w - 1, y, x + w - 1, y + h - 1), fill=dark)
def _text(self, img, c, s, x, y, w, h, color):
font = self.font(c.get("font") or 0)
if font is None or not s:
return
spax, spay = c.get("spax") or 0, c.get("spay") or 0
xcen, ycen = c.get("xcen"), c.get("ycen")
wrap = c.get("isbr")
glyphs = {g.code: g for g in font.glyphs}
def gw(ch):
g = glyphs.get(ord(ch))
return (g.width if g else font.width) + spax
lines = []
for para in s.replace("\r\n", "\n").split("\n"):
cur = ""
for ch in para:
if wrap and cur and sum(gw(k) for k in cur + ch) - spax > w:
lines.append(cur); cur = ""
cur += ch
lines.append(cur)
line_h = font.height + spay
total_h = len(lines) * line_h - spay
if ycen == 1:
ty = y + max(0, (h - total_h) // 2) # never starts above the box
elif ycen == 2:
ty = y + max(0, h - total_h)
else:
ty = y
px = img.load()
W, H = img.size
# the Editor aligns the text *block* (widest line); lines are left-aligned inside it
block_w = max((sum(gw(k) for k in ln) - (spax if ln else 0)) for ln in lines)
for ln in lines:
lw = block_w
if xcen == 1:
tx = x + max(0, (w - lw) // 2)
elif xcen == 2:
tx = x + max(0, w - lw)
else:
tx = x
for ch in ln:
g = glyphs.get(ord(ch))
if g:
for gy, row in enumerate(g.pixels):
yy = ty + gy
if yy < y or yy >= y + h or yy >= H:
continue
for gx, v in enumerate(row):
xx = tx + gx
if v and x <= xx < x + w and 0 <= xx < W and yy >= 0:
px[xx, yy] = color
tx += gw(ch)
ty += line_h
def dual(self, img, c):
"""Dual-state button: val=1 shows the second skin (bco2 / pic2 / picc2) and pco2."""
x, y, w, h = self._box(c)
on = bool(c.get("val"))
sta = c.get("sta")
if sta == 1:
img.paste(rgb((c.get("bco2") if on else c.get("bco")) or 0), (x, y, x + w, y + h))
elif sta == 2:
src = self.pic(c.get("pic2") if on else c.get("pic"))
if src:
self._paste(img, src, 0, 0, w, h, x, y)
elif sta == 0:
src = self.pic(c.get("picc2") if on else c.get("picc"))
if src:
self._paste(img, src, x, y, w, h, x, y)
if on and c.get("style") == 4 and sta == 1:
self._border(img, c, x, y, w, h, override=2) # "on" looks pressed: 3D down
else:
self._border(img, c, x, y, w, h)
self._text(img, c, c.get("txt") or "", *self._inner(c, x, y, w, h),
rgb((c.get("pco2") if on else c.get("pco")) or 0))
def _inner(self, c, x, y, w, h):
"""Text area inside the border."""
style = c.get("style")
b = (c.get("borderw") or 0) if style == 1 else (1 if style in (2, 3, 4) else 0)
return x + b, y + b, w - 2 * b, h - 2 * b
def text(self, img, c):
x, y, w, h = self._box(c)
self._background(img, c, x, y, w, h)
self._border(img, c, x, y, w, h)
self._text(img, c, c.get("txt") or "", *self._inner(c, x, y, w, h), rgb(c.get("pco") or 0))
def number(self, img, c):
v = c.get("val") or 0
if v >= 0x80000000:
v -= 1 << 32
fmt, length = c.get("format"), c.get("lenth") or 0
s = ("%X" % (v & 0xFFFFFFFF)) if fmt == 2 else ("{:,}".format(v) if fmt == 1 else str(v))
if length and fmt != 1:
s = s.zfill(length)[-length:]
x, y, w, h = self._box(c)
self._background(img, c, x, y, w, h)
self._border(img, c, x, y, w, h)
self._text(img, c, s, *self._inner(c, x, y, w, h), rgb(c.get("pco") or 0))
def xfloat(self, img, c):
v = c.get("val") or 0
if v >= 0x80000000:
v -= 1 << 32
ints, decs = c.get("vvs0") or 0, c.get("vvs1") or 0
s = str(abs(v)).zfill(decs + 1)
s = (s[:-decs] + "." + s[-decs:]) if decs else s
if ints:
ip, _, dp = s.partition(".")
s = ip.zfill(ints)[-ints:] + ("." + dp if dp else "")
s = ("-" if v < 0 else "") + s
x, y, w, h = self._box(c)
self._background(img, c, x, y, w, h)
self._border(img, c, x, y, w, h)
self._text(img, c, s, *self._inner(c, x, y, w, h), rgb(c.get("pco") or 0))
def picture(self, img, c):
src = self.pic(c.get("pic"))
if src:
x, y, w, h = self._box(c)
self._paste(img, src, 0, 0, w, h, x, y)
def crop(self, img, c):
src = self.pic(c.get("picc"))
if src:
x, y, w, h = self._box(c)
self._paste(img, src, x, y, w, h, x, y)
def slider(self, img, c):
from PIL import ImageDraw
x, y, w, h = self._box(c)
self._background(img, c, x, y, w, h)
d = ImageDraw.Draw(img)
vmin, vmax, val = c.get("minval") or 0, c.get("maxval") or 100, c.get("val") or 0
frac = 0 if vmax == vmin else (val - vmin) / (vmax - vmin)
vertical = c.get("mode") == 1
cw = c.get("wid"); ch = c.get("hig")
if c.get("psta") == 1: # picture cursor (pic2) at its own size
knob = self.pic(c.get("pic2"))
if knob:
kw, kh = knob.size
if vertical:
ky = y + h - kh - int(frac * (h - kh))
img.paste(knob, (x + (w - kw) // 2, ky))
else:
kx = x + int(frac * (w - kw))
img.paste(knob, (kx, y + (h - kh) // 2))
return
# "auto" (255) cursor = a square as thick as the slider
if vertical:
cw = w if cw in (None, 255) else cw
ch = w if ch in (None, 255) else ch
cy = y + h - ch - int(frac * (h - ch)) # truncates, like the Editor
d.rectangle((x + (w - cw) // 2, cy, x + (w - cw) // 2 + cw - 1, cy + ch - 1), fill=rgb(c.get("pco") or 0))
else:
ch = h if ch in (None, 255) else ch
cw = h if cw in (None, 255) else cw
cx = x + int(frac * (w - cw)) # truncates, like the Editor
d.rectangle((cx, y + (h - ch) // 2, cx + cw - 1, y + (h - ch) // 2 + ch - 1), fill=rgb(c.get("pco") or 0))
def progress(self, img, c):
from PIL import ImageDraw
x, y, w, h = self._box(c)
d = ImageDraw.Draw(img)
val = max(0, min(100, c.get("val") or 0))
if c.get("sta") == 1: # picture mode: bpic background, ppic foreground
bg, fg = self.pic(c.get("bpic")), self.pic(c.get("ppic"))
if bg:
self._paste(img, bg, 0, 0, w, h, x, y)
if fg:
if c.get("dez") == 1:
fh = h * val // 100
if fh:
self._paste(img, fg, 0, h - fh, w, fh, x, y + h - fh)
else:
fw = w * val // 100
if fw:
self._paste(img, fg, 0, 0, fw, h, x, y)
return
d.rectangle((x, y, x + w - 1, y + h - 1), fill=rgb(c.get("bco") or 0))
if c.get("dez") == 1:
fh = h * val // 100
if fh:
d.rectangle((x, y + h - fh, x + w - 1, y + h - 1), fill=rgb(c.get("pco") or 0))
else:
fw = w * val // 100
if fw:
d.rectangle((x, y, x + fw - 1, y + h - 1), fill=rgb(c.get("pco") or 0))
def checkbox(self, img, c):
from PIL import ImageDraw
x, y, w, h = self._box(c)
d = ImageDraw.Draw(img)
d.rectangle((x, y, x + w - 1, y + h - 1), fill=rgb(c.get("bco") or 0))
self._border(img, c, x, y, w, h)
if c.get("val"): # filled square, half the size, centred
d.rectangle((x + w // 4, y + h // 4, x + 3 * w // 4 - 1, y + 3 * h // 4 - 1), fill=rgb(c.get("pco") or 0))
def radio(self, img, c):
from PIL import ImageDraw
x, y, w, h = self._box(c)
d = ImageDraw.Draw(img)
d.ellipse((x, y, x + w - 2, y + h - 2), fill=rgb(c.get("bco") or 0), outline=(65, 68, 65))
if c.get("val"):
d.ellipse((x + w // 4, y + h // 4, x + 3 * w // 4 - 2, y + 3 * h // 4 - 2), fill=rgb(c.get("pco") or 0))
def gauge(self, img, c):
from PIL import ImageDraw
x, y, w, h = self._box(c)
self._background(img, c, x, y, w, h)
d = ImageDraw.Draw(img)
r = min(w, h) // 2 - 1
cx, cy = x + w // 2, y + h // 2
a = math.radians(c.get("val") or 0)
d.line((cx, cy, cx - int(r * math.cos(a)), cy - int(r * math.sin(a))), fill=rgb(c.get("pco") or 0),
width=max(1, c.get("wid") or 1))
def waveform(self, img, c):
from PIL import ImageDraw
x, y, w, h = self._box(c)
self._background(img, c, x, y, w, h)
d = ImageDraw.Draw(img)
gw, gh, gc = c.get("gdw") or 0, c.get("gdh") or 0, rgb(c.get("gdc") or 0)
if gw:
for xx in range(x, x + w, gw):
d.line((xx, y, xx, y + h - 1), fill=gc)
if gh: # horizontal lines count from the bottom
for yy in range(y + h - 1, y - 1, -gh):
d.line((x, yy, x + w - 1, yy), fill=gc)
def qrcode(self, img, c):
x, y, w, h = self._box(c)
img.paste(rgb(c.get("bco") or 0xFFFF), (x, y, x + w, y + h))
File diff suppressed because it is too large. Load diff
File diff suppressed because it is too large. Load diff
+54
View File
@@ -0,0 +1,54 @@
"""Nextion .tft (compiled firmware) -- research-stage helpers. See docs/NOTES.md.
Only what is verified is implemented here:
* the obfuscated layout table at 0xC8..0x113 is XOR 0xEBAB2932 per 32-bit word;
* the trailer (last 4 bytes, LE) is a word-per-byte CRC whose stream ends at the trailer -- so
for edits that keep the file length, the trailer can be updated by linearity
(:func:`patch_trailer`). Building a .tft from scratch is not possible yet: the trailer's start
offset / seed are unknown, and every .tft embeds Nextion's own firmware files, which this
project does not and must not distribute.
"""
from __future__ import annotations
import struct
from .checksum import _feed_byte_as_word, _feed_word
LAYOUT_KEY = 0xEBAB2932
LAYOUT_START, LAYOUT_END = 0xC8, 0x114
def layout_table(tft: bytes) -> list[int]:
"""De-obfuscated words of the layout table (offsets/sizes/counts)."""
return [struct.unpack_from("<I", tft, o)[0] ^ LAYOUT_KEY for o in range(LAYOUT_START, LAYOUT_END, 4)]
def header_info(tft: bytes) -> dict:
return {
"width": struct.unpack_from("<H", tft, 0x0C)[0],
"height": struct.unpack_from("<H", tft, 0x0E)[0],
"model_id": "0x%08X" % struct.unpack_from("<I", tft, 0x2E)[0],
"file_size": struct.unpack_from("<I", tft, 0x3C)[0],
"layout": layout_table(tft),
}
def _zero_words(n: int, c: int) -> int:
for _ in range(n):
c = _feed_word(c, 0)
return c
def patch_trailer(old: bytes, new: bytes) -> bytes:
"""Return ``new`` with its trailer CRC updated, given the Editor-made ``old`` of the same length."""
if len(old) != len(new):
raise ValueError("only same-length edits are supported")
n = len(new) - 4
delta = 0
for j in range(n):
d = old[j] ^ new[j]
if d:
delta ^= _zero_words(n - 1 - j, _feed_byte_as_word(0, d))
crc = struct.unpack_from("<I", old, n)[0] ^ delta
return bytes(new[:n]) + struct.pack("<I", crc)
Binary file not shown.
+37
View File
@@ -0,0 +1,37 @@
import os
import sys
ROOT = os.path.dirname(os.path.dirname(os.path.abspath(__file__)))
sys.path.insert(0, os.path.join(ROOT, "src"))
FIXTURE = os.path.join(ROOT, "tests", "fixtures", "demo_editor_saved.HMI")
try:
import PIL # noqa: F401
HAVE_PIL = True
except ImportError:
HAVE_PIL = False
def demo_project():
"""The demo project, built from code (needs Pillow)."""
sys.path.insert(0, os.path.join(ROOT, "examples"))
import make_demo
return make_demo.build()
def bitwise_word_crc(data, crc=0xFFFFFFFF):
"""Reference: STM32-style CRC-32, each byte zero-extended to a 32-bit word, bit by bit."""
for b in data:
crc ^= b
for _ in range(32):
crc = ((crc << 1) ^ 0x04C11DB7) & 0xFFFFFFFF if crc & 0x80000000 else (crc << 1) & 0xFFFFFFFF
return crc
def bitwise_dword_crc(data, crc=0xFFFFFFFF):
"""Reference: STM32-style CRC-32 over little-endian 32-bit words, bit by bit."""
for i in range(0, len(data), 4):
crc ^= int.from_bytes(data[i:i + 4], "little")
for _ in range(32):
crc = ((crc << 1) ^ 0x04C11DB7) & 0xFFFFFFFF if crc & 0x80000000 else (crc << 1) & 0xFFFFFFFF
return crc
+52
View File
@@ -0,0 +1,52 @@
import struct
import unittest
from helpers import FIXTURE, bitwise_dword_crc, bitwise_word_crc
from nxhmi import checksum
from nxhmi.container import HMIFile
class ChecksumAlgorithms(unittest.TestCase):
def test_word_per_byte_matches_bitwise_reference(self):
for data in (b"", b"\x00", bytes(range(256)), b"nextion" * 13):
self.assertEqual(checksum.word_per_byte_crc(data), bitwise_word_crc(data))
def test_dword_matches_bitwise_reference(self):
for data in (b"", bytes(range(64)), b"abcd" * 50):
self.assertEqual(checksum.dword_crc(data), bitwise_dword_crc(data))
def test_dword_needs_multiple_of_4(self):
with self.assertRaises(ValueError):
checksum.dword_crc(b"abc")
def test_table_crc_appends_magic(self):
tbl = struct.pack("<I", 0)
expect = bitwise_dword_crc(tbl + struct.pack("<I", checksum.TABLE_MAGIC))
self.assertEqual(checksum.table_crc(tbl), expect)
def test_page_crc_definition(self):
page = bytearray(80)
struct.pack_into("<IIII", page, 4, 80, 56, 2, 0)
page[20], page[21] = 0x00, 0x4F
tail = struct.pack("<II", 80, 2) + bytes(page[20:22])
self.assertEqual(checksum.page_crc(bytes(page)), bitwise_word_crc(bytes(page[4:]) + tail))
class ChecksumsOfEditorOutput(unittest.TestCase):
"""Every checksum in a file written by Nextion Editor 1.68 must verify."""
def test_fixture(self):
h = HMIFile.load(FIXTURE)
self.assertEqual(h.table_ok(), (True, True))
for e in h.live():
blob = h.read(e.name)
stored = struct.unpack_from("<I", blob, 0)[0]
if e.name.endswith(".pa"):
self.assertEqual(checksum.page_crc(blob), stored, e.name)
if e.name == "main.HMI":
self.assertEqual(checksum.main_crc(blob), stored)
if __name__ == "__main__":
unittest.main()
+56
View File
@@ -0,0 +1,56 @@
import unittest
import helpers # noqa: F401
from nxhmi import components as C
from nxhmi.page import Page
class Templates(unittest.TestCase):
def test_all_31_types(self):
self.assertEqual(len(C.TYPES), 31)
self.assertEqual(len(C.INTELLIGENT_ONLY), 11)
for t, tpl in C.TYPES.items():
names = [a[0] for a in tpl["att"]]
self.assertEqual(names[:3], ["type", "id", "objname"], tpl["kind"])
self.assertEqual(dict((a[0], a[2]) for a in tpl["att"])["type"], t)
def test_templates_have_no_project_specific_names(self):
self.assertEqual(dict((a[0], a[2]) for a in C.TYPES[121]["att"])["objname"], "page0")
class Factory(unittest.TestCase):
def test_add_every_kind(self):
p = C.new_page("p0")
for k in C.kinds():
if k == "page":
continue
att = {a[0] for a in C.TYPES[C.KINDS[k]]["att"]}
kw = dict(x=5, y=6, w=50, h=20) if "x" in att else {}
C.add(p, k, **kw)
q = Page.parse(p.pack())
self.assertEqual(len(q.components), len(C.kinds()))
ids = [c.get("id") for c in q.components]
self.assertEqual(sorted(ids), list(range(len(ids))))
self.assertEqual(len({c.name for c in q.components}), len(q.components))
def test_endx_endy_and_events(self):
p = C.new_page("p0")
b = C.add(p, "button", x=10, y=20, w=30, h=40, txt="ok", events={"codesup": ["page 1"]})
self.assertEqual((b.get("endx"), b.get("endy")), (39, 59))
self.assertEqual(b.event("codesup"), ["page 1"])
def test_duplicate_name_rejected(self):
p = C.new_page("p0")
C.add(p, "text", "t0")
with self.assertRaises(ValueError):
C.add(p, "text", "t0")
def test_new_page_defaults(self):
p = C.new_page("x", w=800, h=480)
pc = p.components[0]
self.assertEqual((pc.get("sta"), pc.get("bco"), pc.get("w"), pc.get("h")), (1, 0xFFFF, 800, 480))
if __name__ == "__main__":
unittest.main()
+61
View File
@@ -0,0 +1,61 @@
import struct
import unittest
from helpers import FIXTURE
from nxhmi.container import (BACKUP_TABLE_OFFSET, DATA_OFFSET, MARKER_OFFSET, VERSION_MAGIC, VERSION_OFFSET,
HMIError, HMIFile, build)
class Container(unittest.TestCase):
def test_build_layout(self):
f = build([("a.bin", b"hello"), ("b.bin", b"world!")])
raw = f.to_bytes()
self.assertEqual(raw[VERSION_OFFSET:VERSION_OFFSET + 8], VERSION_MAGIC)
self.assertEqual(struct.unpack_from("<I", raw, MARKER_OFFSET)[0], 0xFFFFFFFF)
self.assertEqual(raw[DATA_OFFSET:DATA_OFFSET + 5], b"hello")
g = HMIFile.from_bytes(raw)
self.assertEqual(g.names(), ["a.bin", "b.bin"])
self.assertEqual(g.read("b.bin"), b"world!")
self.assertEqual(raw[0:200], raw[BACKUP_TABLE_OFFSET:BACKUP_TABLE_OFFSET + 200])
def test_replace_like_the_editor(self):
g = HMIFile.from_bytes(build([("a.bin", b"one")]).to_bytes())
g.write("a.bin", b"two, longer")
raw = g.to_bytes()
h = HMIFile.from_bytes(raw)
self.assertEqual(h.read("a.bin"), b"two, longer")
old = [e for e in h.entries if e.deleted]
self.assertEqual(len(old), 1)
self.assertEqual(old[0].raw_name[:1], b"\0") # deleted entries lose name[0]
self.assertEqual(h.table_ok(), (True, True))
def test_delete(self):
g = HMIFile.from_bytes(build([("a", b"1"), ("b", b"2")]).to_bytes())
g.delete("a")
self.assertEqual(HMIFile.from_bytes(g.to_bytes()).names(), ["b"])
with self.assertRaises(KeyError):
g.read("a")
def test_backup_table_fallback_and_both_corrupt(self):
raw = bytearray(build([("x", b"data")]).to_bytes())
raw[5] ^= 0xFF
self.assertEqual(HMIFile.from_bytes(bytes(raw)).names(), ["x"])
raw[BACKUP_TABLE_OFFSET + 5] ^= 0xFF
with self.assertRaises(HMIError):
HMIFile.from_bytes(bytes(raw))
def test_compacted(self):
g = HMIFile.from_bytes(build([("a", b"1" * 10)]).to_bytes())
g.write("a", b"2" * 10)
c = g.compacted()
self.assertEqual(len(c.entries), 1)
self.assertEqual(c.read("a"), b"2" * 10)
def test_editor_file_roundtrip_byte_identical(self):
data = open(FIXTURE, "rb").read()
self.assertEqual(HMIFile.from_bytes(data).to_bytes(), data)
if __name__ == "__main__":
unittest.main()
+35
View File
@@ -0,0 +1,35 @@
import unittest
import helpers # noqa: F401
from nxhmi import enums
class Enums(unittest.TestCase):
def test_colours_exact_roundtrip(self):
for v in range(0, 0x10000, 37):
self.assertEqual(enums.hex_to_rgb565(enums.rgb565_to_hex(v)), v)
self.assertEqual(enums.rgb565_to_hex(0xF800), "#ff0000")
def test_general_and_per_type(self):
self.assertEqual(enums.to_label(116, "xcen", "u8", 2), "right")
self.assertEqual(enums.to_label(52, "sta", "u8", 1), "string") # variable type
self.assertEqual(enums.to_label(121, "sta", "u8", 0), "no background")
self.assertEqual(enums.to_label(58, "sta", "u8", 1), "has") # QR logo
self.assertEqual(enums.to_label(98, "style", "u8", 4), "3D_Auto")
self.assertEqual(enums.to_label(116, "style", "u8", 4), 4) # not a text style
def test_from_label(self):
self.assertEqual(enums.from_label(116, "xcen", "u8", "Center"), 1)
self.assertEqual(enums.from_label(116, "bco", "u16", "#ffffff"), 0xFFFF)
self.assertEqual(enums.from_label(116, "x", "u16", 7), 7)
self.assertEqual(enums.from_label(116, "x", "u16", "0x10"), 16)
with self.assertRaises(ValueError):
enums.from_label(116, "xcen", "u8", "sideways")
def test_strings_untouched(self):
self.assertEqual(enums.to_label(116, "txt", "str", "#abc"), "#abc")
if __name__ == "__main__":
unittest.main()
+93
View File
@@ -0,0 +1,93 @@
"""Pictures and fonts."""
import io
import random
import struct
import unittest
from helpers import FIXTURE, HAVE_PIL
from nxhmi import fonts, pictures
from nxhmi.container import HMIFile
class Pictures(unittest.TestCase):
def test_layout_rotated_bottom_up(self):
px = {(0, 0): (255, 0, 0), (1, 0): (0, 255, 0), (0, 1): (0, 0, 255), (1, 1): (255, 255, 255)}
raw = pictures.to_rgb565(lambda x, y: px[(x, y)], 2, 2)
self.assertEqual([struct.unpack_from("<H", raw, 2 * i)[0] for i in range(4)], [0x001F, 0xF800, 0xFFFF, 0x07E0])
def test_truncation(self):
raw = pictures.to_rgb565(lambda x, y: (7, 3, 255), 1, 1)
self.assertEqual(struct.unpack("<H", raw)[0], (0 << 11) | (0 << 5) | 31)
def test_headers(self):
i = pictures.make_picture(b"\0" * 8, 2, 2)
self.assertEqual(pictures.info(i), {"format": 0, "width": 2, "height": 2, "length": 8})
s = pictures.make_source(b"PNGDATA", 2, 2)
self.assertEqual(pictures.source_file(s), b"PNGDATA")
self.assertEqual(pictures.source_info(s)["type"], "png")
@unittest.skipUnless(HAVE_PIL, "needs Pillow")
def test_image_roundtrip(self):
from PIL import Image
img = Image.new("RGB", (5, 3))
for x in range(5):
for y in range(3):
img.putpixel((x, y), (x * 50, y * 100, 200))
b = io.BytesIO(); img.save(b, "PNG")
pic, src = pictures.from_image_file(b.getvalue())
self.assertEqual(pictures.source_file(src), b.getvalue())
back = pictures.to_image(pic)
for x in range(5):
for y in range(3):
r, g, bb = img.getpixel((x, y))
self.assertEqual(back.getpixel((x, y))[0] >> 3, r >> 3)
def test_editor_pictures_decode(self):
h = HMIFile.load(FIXTURE)
for n in h.names():
if n.endswith(".i"):
self.assertEqual(pictures.info(h.read(n))["format"], 0)
class Fonts(unittest.TestCase):
def test_rle_roundtrip_random(self):
random.seed(3)
for _ in range(60):
w, h = random.choice([(8, 16), (16, 32), (12, 24), (5, 7)])
rows = [[1 if random.random() < 0.35 else 0 for _ in range(w)] for _ in range(h)]
self.assertEqual(fonts.decode_glyph(b"\x01" + fonts.encode_glyph(rows, w, h), w, h), rows)
def test_codes(self):
# pixels are scanned per column from the bottom row up; rows are returned top -> bottom
col = [r[0] for r in fonts.decode_glyph(b"\x01\x7e", 1, 32)] # 01 1 11110: 30 transparent, 2 ink
self.assertEqual(col, [1, 1] + [0] * 30)
self.assertEqual(fonts.decode_glyph(b"\x01\x22", 1, 2), [[1], [1]]) # 00 1 00010: 2 ink
self.assertEqual(fonts.decode_glyph(b"\x01\x02\x41", 1, 4), [[1], [0], [0], [0]]) # 2 t, then 01 0: 1 t + 1 ink
self.assertEqual(fonts.decode_glyph(b"\x01\xca", 1, 4), [[0], [1], [1], [0]]) # 11 001 010: 1 t + 2 ink
self.assertEqual(fonts.decode_glyph(b"\x01\x84", 1, 7), [[1], [1], [1], [0], [0], [0], [0]]) # 10 0: 4 t + 3 ink
def test_font_pack_parse(self):
f = fonts.Font("T-8", 8, 8, 1, 0x20, 0x21, [fonts.Glyph(0x20, 8, [[0] * 8 for _ in range(8)]),
fonts.Glyph(0x21, 4, [[1, 0, 0, 1] for _ in range(8)])])
g = fonts.Font.parse(f.pack())
self.assertEqual((g.name, g.glyph("!").width, g.glyph("!").pixels), ("T-8", 4, f.glyphs[1].pixels))
def test_editor_fonts_reencode_identical(self):
h = HMIFile.load(FIXTURE)
for n in h.names():
if n.endswith(".zi"):
blob = h.read(n)
self.assertEqual(fonts.Font.parse(blob).pack(), blob, n)
@unittest.skipUnless(HAVE_PIL, "needs Pillow")
def test_from_ttf_default_font(self):
f = fonts.from_ttf(None, 20)
self.assertEqual(len(f.glyphs), 95)
self.assertTrue(any(any(r) for r in f.glyph("A").pixels))
self.assertFalse(any(any(r) for r in f.glyph(" ").pixels))
self.assertEqual(fonts.Font.parse(f.pack()).name, "Aileron-20ascii")
if __name__ == "__main__":
unittest.main()
+64
View File
@@ -0,0 +1,64 @@
import unittest
from helpers import FIXTURE
from nxhmi.container import HMIFile
from nxhmi.page import Attr, Component, Group, Page
def small_page():
pc = Component([Group("att", [Attr.encode("type", "u8", 121), Attr.encode("id", "u8", 0),
Attr.encode("objname", "str", "p0"), Attr.encode("w", "u16", 480)]),
Group("codesload", []), Group("codesdown", [b"page 1"])])
t = Component([Group("att", [Attr.encode("type", "u8", 116), Attr.encode("id", "u8", 1),
Attr.encode("objname", "str", "t0"), Attr.encode("txt", "str", "hi"),
Attr.encode("txt_maxl", "u16", 10), Attr.encode("dir", "u8", 1)])])
return Page("p0", [pc, t])
class PageModel(unittest.TestCase):
def test_roundtrip(self):
blob = small_page().pack()
self.assertEqual(Page.parse(blob).pack(), blob)
def test_checksum_verified_on_parse(self):
blob = bytearray(small_page().pack())
blob[-5] ^= 1
with self.assertRaises(ValueError):
Page.parse(bytes(blob))
Page.parse(bytes(blob), verify=False)
def test_header_fields(self):
p = Page.parse(small_page().pack())
self.assertEqual((p.name, p.b21, p.version), ("p0", 0x4F, 0x21))
self.assertEqual(len(p.components), 2)
def test_string_detection_by_companion(self):
t = Page.parse(small_page().pack()).component("t0")
self.assertEqual(t.attr("txt").decoded()[0], "str") # has txt_maxl
self.assertEqual(t.attr("dir").decoded(), ("u8", 1)) # no dir_m -> number
self.assertEqual(t.attr("objname").decoded()[0], "str")
def test_set_get_and_grow(self):
p = Page.parse(small_page().pack())
t = p.component("t0")
t.set("txt", "a much longer text")
t.set_event("codesdown", ["click t0,1", "page 0"])
q = Page.parse(p.pack())
self.assertEqual(q.component("t0").get("txt"), "a much longer text")
self.assertEqual(q.component("t0").event("codesdown"), ["click t0,1", "page 0"])
def test_signed_values(self):
a = Attr.encode("val", "u32", -1234567)
self.assertEqual(a.value, (-1234567 & 0xFFFFFFFF).to_bytes(4, "little"))
def test_editor_pages_roundtrip(self):
h = HMIFile.load(FIXTURE)
for e in h.live():
if e.name.endswith(".pa"):
blob = h.read(e.name)
self.assertEqual(Page.parse(blob).pack(), blob, e.name)
if __name__ == "__main__":
unittest.main()
+115
View File
@@ -0,0 +1,115 @@
import json
import os
import shutil
import struct
import tempfile
import unittest
from helpers import FIXTURE, HAVE_PIL, demo_project
from nxhmi import checksum, models, project
from nxhmi.container import HMIFile
from nxhmi.page import Page
class NewProject(unittest.TestCase):
def test_new_project(self):
h = project.new_project("NX4832T035_011", "start")
self.assertEqual(h.names(), ["main.HMI", "Program.s", "0.pa"])
main = h.read("main.HMI")
self.assertEqual(checksum.main_crc(main), struct.unpack_from("<I", main, 0)[0])
self.assertEqual(project.parse_main(main)["resources"], [["pa", "0.pa"]])
self.assertEqual(Page.parse(h.read("0.pa")).name, "start")
self.assertEqual(project.project_size(h), (480, 320))
def test_every_model(self):
for name, (mid, series, w, hgt) in models.MODELS.items():
h = project.new_project(name)
main = h.read("main.HMI")
self.assertEqual(struct.unpack_from("<I", main, 16)[0], mid)
self.assertEqual(main[11], series)
self.assertEqual(Page.parse(h.read("0.pa")).components[0].get("w"), w)
def test_unknown_model(self):
with self.assertRaises(KeyError):
project.new_project("NX0000X000_000")
def test_add_page_registers_resource(self):
h = project.new_project()
project.add_page(h, "two")
h2 = HMIFile.from_bytes(h.to_bytes())
self.assertIn(["pa", "1.pa"], project.parse_main(h2.read("main.HMI"))["resources"])
with self.assertRaises(ValueError):
project.add_page(h2, "two")
def test_resource_order(self):
main = project.make_main("NX4832T035_011", [("pa", "0.pa")])
main = project.main_insert_resource(main, "i", "0.i")
main = project.main_insert_resource(main, "zi", "0.zi")
main = project.main_insert_resource(main, "i", "1.i")
self.assertEqual([r[1] for r in project.parse_main(main)["resources"]], ["0.i", "1.i", "0.zi", "0.pa"])
class DecodeEncode(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.mkdtemp()
def tearDown(self):
shutil.rmtree(self.tmp)
def test_editor_file_decode_encode_identical(self):
out = os.path.join(self.tmp, "dec")
project.decode(FIXTURE, out)
re = os.path.join(self.tmp, "re.HMI")
project.encode(out, re)
a, b = HMIFile.load(FIXTURE), HMIFile.load(re)
self.assertEqual(sorted(a.names()), sorted(b.names()))
for n in a.names():
self.assertEqual(a.read(n), b.read(n), n)
def test_readable_json(self):
out = os.path.join(self.tmp, "dec")
project.decode(FIXTURE, out)
pj = json.load(open(os.path.join(out, "pages", "0_home.json"), encoding="utf-8"))
att = {c["att"][2][2]: {a[0]: a[2] for a in c["att"]} for c in pj["components"]}
self.assertEqual(att["home"]["sta"], "image")
self.assertEqual(att["tStatus"]["pco"], "#00ff00")
self.assertEqual(att["tStatus"]["style"], "border")
def test_raw_json(self):
out = os.path.join(self.tmp, "raw")
project.decode(FIXTURE, out, readable=False)
pj = json.load(open(os.path.join(out, "pages", "0_home.json"), encoding="utf-8"))
self.assertEqual({a[0]: a[2] for a in pj["components"][0]["att"]}["sta"], 2)
def test_edit_through_json(self):
out = os.path.join(self.tmp, "dec")
project.decode(FIXTURE, out)
path = os.path.join(out, "pages", "0_home.json")
pj = json.load(open(path, encoding="utf-8"))
for c in pj["components"]:
for a in c["att"]:
if c["att"][2][2] == "title" and a[0] == "txt":
a[2] = "changed"
if c["att"][2][2] == "title" and a[0] == "xcen":
a[2] = "right"
json.dump(pj, open(path, "w", encoding="utf-8"))
re = os.path.join(self.tmp, "re.HMI")
project.encode(out, re)
t = Page.parse(HMIFile.load(re).read("0.pa")).component("title")
self.assertEqual((t.get("txt"), t.get("xcen")), ("changed", 2))
@unittest.skipUnless(HAVE_PIL, "needs Pillow")
class Demo(unittest.TestCase):
def test_demo_matches_editor_resave(self):
"""The demo built by nxhmi is byte-identical to the same project re-saved by Nextion Editor."""
ours = HMIFile.from_bytes(demo_project().to_bytes())
editor = HMIFile.load(FIXTURE)
self.assertEqual(sorted(ours.names()), sorted(editor.names()))
for n in ours.names():
self.assertEqual(ours.read(n), editor.read(n), n)
if __name__ == "__main__":
unittest.main()
+98
View File
@@ -0,0 +1,98 @@
"""Renderer rules, each one measured against Nextion Editor 1.68 (see docs/RENDER.md)."""
import unittest
from helpers import FIXTURE, HAVE_PIL
from nxhmi import components as C
from nxhmi.container import HMIFile, build
@unittest.skipUnless(HAVE_PIL, "needs Pillow")
class Render(unittest.TestCase):
def render(self, page):
from nxhmi.render import Renderer
return Renderer(build([("0.pa", page.pack())])).render(page.name)
def test_page_solid(self):
p = C.new_page("p", w=40, h=20, bco=0x001F)
self.assertEqual(self.render(p).getpixel((5, 5)), (0, 0, 255))
def test_progress_bar(self):
p = C.new_page("p", w=100, h=40)
C.add(p, "progress_bar", x=10, y=10, w=50, h=10, val=50, bco=0, pco=0xF800)
img = self.render(p)
self.assertEqual(img.getpixel((20, 15)), (255, 0, 0))
self.assertEqual(img.getpixel((50, 15)), (0, 0, 0))
def test_slider_auto_cursor_truncates(self):
p = C.new_page("p", w=240, h=40)
C.add(p, "slider", x=0, y=0, w=200, h=25, val=50, minval=0, maxval=100, pco=0x07E0, bco=0)
img = self.render(p)
# cursor is 25 px wide (auto = slider thickness), at int(0.5 * 175) = 87
self.assertEqual(img.getpixel((87, 10)), (0, 255, 0))
self.assertEqual(img.getpixel((86, 10)), (0, 0, 0))
self.assertEqual(img.getpixel((111, 10)), (0, 255, 0))
self.assertEqual(img.getpixel((112, 10)), (0, 0, 0))
def test_3d_border_colours(self):
p = C.new_page("p", w=60, h=40)
C.add(p, "button", x=0, y=0, w=50, h=30, style=4, sta=1, bco=0xBDF7, txt="")
img = self.render(p)
self.assertEqual(img.getpixel((10, 0)), (230, 226, 230))
self.assertEqual(img.getpixel((10, 29)), (65, 68, 65))
def test_picture_button_has_no_frame(self):
p = C.new_page("p", w=60, h=40)
b = C.add(p, "button", x=0, y=0, w=50, h=30, style=4, sta=1, bco=0x0000, txt="")
b.set("sta", 2) # picture skin, picture missing -> nothing drawn
img = self.render(p)
self.assertEqual(img.getpixel((10, 0)), (255, 255, 255))
def test_waveform_grid_from_bottom(self):
p = C.new_page("p", w=100, h=100)
C.add(p, "waveform", x=0, y=0, w=50, h=50, gdw=20, gdh=20, gdc=0x07E0, sta=1, bco=0)
img = self.render(p)
self.assertEqual(img.getpixel((5, 49)), (0, 255, 0)) # bottom row is a grid line
self.assertEqual(img.getpixel((5, 29)), (0, 255, 0))
self.assertEqual(img.getpixel((5, 0)), (0, 0, 0))
def test_checkbox(self):
p = C.new_page("p", w=100, h=100)
C.add(p, "checkbox", x=0, y=0, w=40, h=40, val=1, bco=0xFFFF, pco=0x001F, style=0)
img = self.render(p)
self.assertEqual(img.getpixel((10, 10)), (0, 0, 255))
self.assertEqual(img.getpixel((9, 9)), (255, 255, 255))
self.assertEqual(img.getpixel((29, 29)), (0, 0, 255))
self.assertEqual(img.getpixel((30, 30)), (255, 255, 255))
def test_dual_state_on_is_pressed(self):
p = C.new_page("p", w=60, h=40)
C.add(p, "dual_state_button", x=0, y=0, w=50, h=30, val=1, style=4, sta=1, txt="")
img = self.render(p)
self.assertEqual(img.getpixel((10, 0)), (65, 68, 65)) # dark top edge when on
def test_demo_pages_render(self):
from nxhmi.render import Renderer
r = Renderer(HMIFile.load(FIXTURE))
for name in ("home", "controls", "gallery"):
img = r.render(name)
self.assertEqual(img.size, (480, 320))
self.assertEqual(r.render("home").getpixel((0, 319)), r.pic(0).getpixel((0, 319)))
def test_text_clamped_inside_box(self):
from nxhmi import fonts, project
from nxhmi.render import Renderer
h = project.new_project()
fid = project.add_font(h, fonts.from_ttf(None, 32))
from nxhmi.page import Page
p = Page.parse(h.read("0.pa"))
C.add(p, "text", x=0, y=0, w=200, h=20, txt="Hg", font=fid, ycen=1, sta=1, bco=0xFFFF, pco=0)
h.write("0.pa", p.pack())
img = Renderer(h).render("page0")
ink_rows = [y for y in range(20) if any(img.getpixel((x, y)) == (0, 0, 0) for x in range(200))]
self.assertTrue(ink_rows and ink_rows[0] >= 0)
self.assertEqual(img.getpixel((10, 25)), (255, 255, 255)) # nothing drawn below the box
if __name__ == "__main__":
unittest.main()
+91
View File
@@ -0,0 +1,91 @@
import contextlib
import io
import os
import shutil
import struct
import tempfile
import unittest
from helpers import FIXTURE, HAVE_PIL, bitwise_word_crc
from nxhmi import cli, tft
def fake_tft(payload: bytes) -> bytes:
"""A synthetic .tft-shaped blob: layout table + trailer CRC computed the way the trailer behaves
(word-per-byte CRC whose stream ends at the trailer). Real .tft files cannot be used in tests:
they contain Nextion's firmware."""
head = bytearray(0x200)
struct.pack_into("<HH", head, 0x0C, 480, 320)
for i, o in enumerate(range(tft.LAYOUT_START, tft.LAYOUT_END, 4)):
struct.pack_into("<I", head, o, (i * 1000) ^ tft.LAYOUT_KEY)
body = bytes(head) + payload
return body + struct.pack("<I", bitwise_word_crc(body, 0x12345678))
class Tft(unittest.TestCase):
def test_layout_table(self):
t = fake_tft(b"x" * 10)
self.assertEqual(tft.layout_table(t)[:3], [0, 1000, 2000])
self.assertEqual(tft.header_info(t)["width"], 480)
def test_patch_trailer_same_length(self):
old = fake_tft(b"page data: colour ff ff")
new_body = old[:-4].replace(b"ff ff", b"00 f8")
expect = fake_tft(b"page data: colour 00 f8")
self.assertEqual(tft.patch_trailer(old, new_body + b"\0\0\0\0"), expect)
def test_patch_trailer_rejects_length_change(self):
with self.assertRaises(ValueError):
tft.patch_trailer(b"\0" * 20, b"\0" * 24)
class Cli(unittest.TestCase):
def setUp(self):
self.tmp = tempfile.mkdtemp()
self.hmi = os.path.join(self.tmp, "p.HMI")
shutil.copy(FIXTURE, self.hmi)
def tearDown(self):
shutil.rmtree(self.tmp)
def run_cli(self, *args):
out = io.StringIO()
with contextlib.redirect_stdout(out):
rc = cli.main(list(args))
return rc, out.getvalue()
def test_info_verify_dump(self):
self.assertIn("home", self.run_cli("info", self.hmi)[1])
self.assertEqual(self.run_cli("verify", self.hmi)[0], 0)
self.assertIn('"title"', self.run_cli("dump", self.hmi, "--page", "home")[1])
def test_decode_encode(self):
d = os.path.join(self.tmp, "dec")
self.run_cli("decode", self.hmi, d)
self.run_cli("encode", d, os.path.join(self.tmp, "re.HMI"))
self.assertEqual(self.run_cli("verify", os.path.join(self.tmp, "re.HMI"))[0], 0)
def test_set_add_newpage_kinds(self):
self.run_cli("set", self.hmi, "home", "title", "txt", "hello")
self.run_cli("add", self.hmi, "home", "button", "x=1", "y=2", "w=30", "h=20", "txt=ok", "--name", "bNew")
self.run_cli("new-page", self.hmi, "extra")
out = self.run_cli("info", self.hmi)[1]
self.assertIn("extra", out)
self.assertEqual(self.run_cli("verify", self.hmi)[0], 0)
self.assertIn("button", self.run_cli("kinds")[1])
@unittest.skipUnless(HAVE_PIL, "needs Pillow")
def test_add_picture_font_render(self):
from PIL import Image
png = os.path.join(self.tmp, "i.png")
Image.new("RGB", (8, 8), (1, 2, 3)).save(png)
self.run_cli("add-picture", self.hmi, png)
self.assertEqual(self.run_cli("verify", self.hmi)[0], 0)
out = os.path.join(self.tmp, "png")
self.run_cli("render", self.hmi, out)
self.assertTrue(os.path.exists(os.path.join(out, "home.png")))
if __name__ == "__main__":
unittest.main()
+41
View File
@@ -0,0 +1,41 @@
"""Regenerate component templates from a project in which every component type was freshly placed.
Usage: python tools/make_templates.py project.HMI PAGE_ENTRY out.json "source description"
For each component type the *last* instance on the page is used (fresh Editor defaults when the
components were placed in toolbox order onto an existing page).
"""
import json
import os
import sys
sys.path.insert(0, os.path.join(os.path.dirname(__file__), "..", "src"))
from nxhmi.container import HMIFile # noqa: E402
from nxhmi.page import Page # noqa: E402
KINDS = {121: "page", 116: "text", 55: "scrolling_text", 54: "number", 59: "xfloat", 98: "button",
106: "progress_bar", 112: "picture", 113: "crop", 109: "hotspot", 5: "touch_cap", 122: "gauge",
0: "waveform", 1: "slider", 51: "timer", 52: "variable", 53: "dual_state_button", 56: "checkbox",
57: "radio", 58: "qrcode", 2: "gmov", 3: "video", 4: "audio", 60: "ex_picture", 61: "combobox",
62: "sl_text", 63: "file_stream", 65: "file_browser", 66: "data_record", 67: "switch",
68: "text_select"}
def main(hmi, entry, out, source):
page = Page.parse(HMIFile.load(hmi).read(entry))
types = {}
for c in reversed(page.components):
t = c.get("type")
if str(t) in types:
continue
types[str(t)] = {"kind": KINDS.get(t, "type%d" % t),
"prefix": "page" if t == 121 else c.name.rstrip("0123456789"),
"att": [[a.name, *a.decoded()] for a in c.attrs()],
"events": [g.name for g in c.groups if g.name != "att"]}
with open(out, "w", encoding="utf-8") as f:
json.dump({"source": source, "types": dict(sorted(types.items(), key=lambda kv: int(kv[0])))}, f, indent=1)
print("%d types -> %s" % (len(types), out))
if __name__ == "__main__":
main(*sys.argv[1:5])