Files
openhmi-nx/.claude/skills/nextion-hmi/SKILL.md
T
mangavalkandClaude Opus 5.5 49fee337d7 Render Intelligent-only components; fonts follow the display direction
- SLText, TextSelect, DataRecord, FileBrowser pixel-exact against the Intelligent simulator;
  ComboBox and Switch with approximate anti-aliased edges; media/file components draw nothing
- fonts: header byte 3 = 0x0A + direction, glyphs in the direction's pixel order, Intelligent
  glyph data 4-byte aligned -- reproduces the Editor's own font conversion byte for byte
- Intelligent 3D frames: left edge drawn over the bottom edge

Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
2026-11-16 00:26:27 +01:00

50 lines
3.2 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.
- 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.