Nextion's seven firmware files cannot be in the repo, so the repo now ships their SHA-256 hashes (src/nxhmi/firmware.sha256, Editor 1.68.2.3035) and every build checks the files against them. The files live in the git-ignored firmware/ folder; `nxhmi firmware --from <Editor folder>` copies them, `nxhmi firmware` reports ok / missing / wrong hash. build-tft and the MCP tool take --firmware-dir / firmware_dir (also NXHMI_FIRMWARE_DIR) instead of the Editor folder. Co-Authored-By: Claude Opus 5.5 <noreply@anthropic.com>
4.2 KiB
4.2 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
info-- model, display size, pages, components, pictures, fonts.get_page-- the components of one page with readable values.- Change things:
set_attributes,set_event,add_component,remove_component,add_page,add_picture,add_font. Every call saves the file. verify-- all checksums must be ok.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/ycenleft|center|right/up|center|down,stacrop image|solid color|image(page:no background|solid color|image),styleflat|border|3D_Down|3D_Up(+3D_Autofor 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_kindslists the kinds (button,text,number,slider,progress_bar, ...).- Coordinates:
x,y,w,hin pixels;endx/endyare updated automatically. new_projectis landscape by default (portrait: truefor a tall screen);infoshowsdirectionandencoding.- Text needs a font:
fontis a font id. A new project has no fonts -- calladd_fontfirst (height in px; no TrueType path = bundled CC0 font).txt_maxlmust be >= the text length. - Chinese/Japanese/Korean or UTF-8 text: create the project with that
encoding, add a font withencoding+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:quality1-99 stores JPEG (Intelligent only, smaller files). build_tftcompiles to.tftwithout the Editor's compiler, but only for model NX4832T035 and a small subset (pages, hotspots, plain text, int variables, timers, touch caps, pictures, fonts, plain script); it says what it cannot compile. It needs Nextion's seven firmware files in the repo'sfirmware/folder (git-ignored; the user copies them withnxhmi firmware --from "<Editor folder>"). Each build checks them againstsrc/nxhmi/firmware.sha256and refuses missing or other-version 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_picturereturns an id forpic/picc(crop) /pic2etc. 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. objnamemust be unique per page;add_componentpicksb0,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
.tftwith the Editor (or Nexus for uploading). nxhmi cannot compile.tftfiles 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_picturehandle 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.