Files
openhmi-nx/.claude/skills/nextion-hmi/SKILL.md
T
mangavalkandClaude Opus 5.5 193bcd5d97 Intelligent pictures (format 4) and direction-aware picture order
Format 4 decoded from Editor output: control words of eight 4-bit ops
(runs up to 13, 12-bit long runs, literal blocks) over 8 colour slots,
plus a run-length 7-bit alpha section. The encoder reproduces all 28
Editor samples byte for byte and the Editor keeps our pictures as is.

Pictures are stored rotated by the display direction, byte 0 of N.i is
0x0A + direction; this applies to format 0 too. add_picture now writes
the right format and order for the project; the renderer decodes format
4 and blends alpha.

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

3.0 KiB

name, description
name description
nextion-hmi 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 not drawn yet.
  • 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.