- nxhmi.mcp_server: dependency-free stdio MCP server, 14 tools; readable values in and out; render_page returns a PNG image - .mcp.json for Claude Code, .claude/skills/nextion-hmi/SKILL.md - CLI: info --json, schema <kind> - fix: project.add_page(h=...) clashed with the page height keyword - 75 tests Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
47 lines
2.8 KiB
Markdown
47 lines
2.8 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.
|
|
- 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. Basic-series
|
|
displays only (Intelligent compressed pictures are not supported yet).
|
|
- 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: radio buttons are ~95 % exact, QR codes are a placeholder, Intelligent-only
|
|
components are not drawn.
|