59 lines
4.0 KiB
Markdown
59 lines
4.0 KiB
Markdown
---
|
|
name: nextion-hmi
|
|
description: Create, inspect, edit and render Nextion display projects (.HMI files) without Nextion Editor, using the nxhmi tools in this repo. Use when the user wants to build or change a Nextion screen, page, button, text, slider, picture or font, look at how a page looks, or check an .HMI file.
|
|
---
|
|
|
|
# Working on Nextion .HMI projects
|
|
|
|
Prefer the **`nxhmi` MCP tools** (configured in `.mcp.json`); fall back to the CLI
|
|
(`PYTHONPATH=src python -m nxhmi ...`) or the Python API (`src/nxhmi`) when they are not available.
|
|
|
|
## Loop
|
|
|
|
1. `info` -- model, display size, pages, components, pictures, fonts.
|
|
2. `get_page` -- the components of one page with readable values.
|
|
3. Change things: `set_attributes`, `set_event`, `add_component`, `remove_component`, `add_page`,
|
|
`add_picture`, `add_font`. Every call saves the file.
|
|
4. `verify` -- all checksums must be ok.
|
|
5. `render_page` -- **look at the result** (it matches Nextion Editor's canvas) before telling the
|
|
user it is done. Fix overlaps, clipped text and wrong colours you see.
|
|
|
|
Back up the user's file first (copy it) unless they said not to; edits write in place.
|
|
|
|
## Values
|
|
|
|
- Attributes accept readable values: `xcen`/`ycen` `left|center|right` / `up|center|down`,
|
|
`sta` `crop image|solid color|image` (page: `no background|solid color|image`), `style`
|
|
`flat|border|3D_Down|3D_Up` (+`3D_Auto` for buttons), colours as `#rrggbb` (stored as RGB565,
|
|
so they snap to the nearest 5/6/5-bit colour). Numbers always work too.
|
|
- `schema <kind>` lists every attribute of a component kind with defaults and allowed values;
|
|
`list_kinds` lists the kinds (`button`, `text`, `number`, `slider`, `progress_bar`, ...).
|
|
- Coordinates: `x`, `y`, `w`, `h` in pixels; `endx`/`endy` are updated automatically.
|
|
- `new_project` is landscape by default (`portrait: true` for a tall screen); `info` shows
|
|
`direction` and `encoding`.
|
|
- Text needs a font: `font` is a font id. A new project has **no fonts** -- call `add_font`
|
|
first (height in px; no TrueType path = bundled CC0 font). `txt_maxl` must be >= the text length.
|
|
- Chinese/Japanese/Korean or UTF-8 text: create the project with that `encoding`, add a font with
|
|
`encoding` + `chars` (only the characters you need) and a TrueType file that has them; decode the
|
|
project with the same encoding to see the text readably. Pictures: `quality` 1-99 stores JPEG
|
|
(Intelligent only, smaller files).
|
|
- `build_tft` compiles to `.tft` without the Editor's compiler, but only for model NX4832T035 and a
|
|
small subset (pages, hotspots, int variables, timers, pictures, fonts, plain script); it says
|
|
what it cannot compile. It needs the Editor's install folder for the firmware files. Its
|
|
output is byte-identical to the Editor's for the test projects but has never been loaded onto
|
|
a display -- tell the user, and never upload it yourself.
|
|
- Pictures: `add_picture` returns an id for `pic` / `picc` (crop) / `pic2` etc. Works for Basic
|
|
and Intelligent displays (Intelligent keeps PNG transparency).
|
|
- Event code is Nextion script, one line per list item, e.g. `["page settings"]`,
|
|
`["n0.val++", "t0.txt=\"hi\""]`. Events: `codesdown` (press), `codesup` (release),
|
|
`codesload` / `codesloadend` (page pre/post-initialize), `codesunload`, `codestimer`, `codesslide`.
|
|
- `objname` must be unique per page; `add_component` picks `b0`, `t1`, ... if no name is given.
|
|
|
|
## Limits (see docs/COVERAGE.md)
|
|
|
|
- Writes projects for Nextion Editor 1.68.2; the user still compiles/uploads the `.tft` with the
|
|
Editor (or Nexus for uploading). nxhmi cannot compile `.tft` files yet.
|
|
- Rendering: Intelligent-only components are drawn as in the simulator (ComboBox and Switch edges are approximate). Run-time content (files, records, video) is not drawn. Fonts and pictures are stored in the project's display direction; `add_font`/`add_picture` handle it.
|
|
- QR codes on Basic displays: long texts can exceed the display RAM; the Editor then refuses to
|
|
compile ("not enough memory ... QR code"). Keep QR texts short there and compile to check.
|