Nextion Display Template creation using mapping editor
Since 6.5.0 Simhub offers an editor to edit nextion mappings.
The process of creating a template works as follows :
- Create the nextion template using the nextion editor, this will act as a "skeleton" containing pages, fonts, texts slots - When this template is done it's uploaded to the nextion.
- Configure simhub to use the new template
- Create the "mapping" in SimHub, the mapping will allow to give life to your nextion template, define roles for your pages, set text for each pages, trigger a page when an event occurs ...
Simhub uses a custom version of the nextion editor bundled with it. In your start menu you will find it under the name "Simhub nextion editor"
Create a new template and save it inside simhub nextion templates folder (usually C:\Program Files (x86)\SimHub\NextionTemplate)
This step is critical for simhub to work correctly make sure not to forget it when you will add another page !
baud=115200
sendme
I won't cover in details the editor usage since it only relies on the itead editor manipulation, you can refer to the manufacturer documentation https://nextion.itead.cc/editor_guide/
Create your skeleton by putting all the texts/progressbars/Images required. it will act as a skeleton, A few advice to make your life easier :
- Dont use too much pictures, fonts, and avoid leaving unused pictures in your template, it will slow down upload.
- Uses clean default text and values in your template.
- Give proper names to your texts and component names.
- Keep consistant in your component names ! If on multiple pages you have a text showing speed for instance, always give it the same name, so you will be able to map all of them in one shot later.
- Only use lower cases component names !
- You can create a "idle page", ideally it should be the first one, so if Simhub is not running if will show anyway.
You can find a little step by step video (click to view) :
If you use an arduino micro as a bridge please see dedicated iunstructions here : https://github.com/zegreatclan/SimHub/wiki/Nextion-Display#uploading-nextion-template-through-arduino-micro
Before uploading always close simhub to avoid any conflicts !
Before going to simhub, make sure to generate the structure file, and after any changes to your nextion template :
In simhub choose your template, your nextion serial port,check use editor, set is as enabled and hit apply :
If the template does not appears make sure you have saved your nextion template inside the correct folder (see
The editor uses the template file to draw a preview of the template and easily configure the data to be shown. It's heavily based on the names of the components and pages, so it's not recommended to rename later components in the nextion template, otherwise the editor would lose the mappings.
Hit edit mapping to open the editor.
- Pages list
- Components list
- Page roles, defines when the page will be shown or if it will be allowed in the current mode (game running or not)
- Mappings and roles : allows to set the data shown in the template
- Virtual touch areas : Allows to set some touch areas handled by simhub in order to trigger actions such as next page ...)
- Event triggers, event triggers allows to show the page for a defined time after an event as been triggered (such as new lap...)
For each page you must set one or more roles, these roles will be used by SimHub to choose which page will be shown depending if the game is running or not.
There are three options available which can be combined :
- Idle : The page will be allowed and will be accessible by next/previous navigation on the nextion when the game is not running
- Ingame : The page will be allowed and will be accessible by next/previous navigation on the nextion when the game is running
- Skip : The page won't be shown in next/previous navigation, but if the page is shown using event trigger or touch navigation (buttons, touch areas ..) the page will be left shown by SimHub.
If no options is choosen simhub won't allow to show the page.
Virtual pages allow to duplicate a real page in order to show different data without copying the real page in the nextion template. The typical use case would be a message page, duplicated for each type of message (best lap/new lap/TC ...) You can only create virtual pages based on a real one. To create a virtual page right click on a real page. It will act just like a real page.
To delete a virtual page simply right click on the page and hit delete :
You can reorganize virtual pages using right click menu, however virtual pages will always be placed after real pages. Real pages order must be changed in nextion editor.
The mappings allows you to set which data will be shown on the component, only the properties which can be controlled on the nextion are shown.
The mappings offers 4 levels of mappings taken by priority for each property :
- This page mappings: formulas set for a specific property on this page
- This page role : Roles allows to set a content in a few seconds by choosing a role in the list on a component on this page
- All pages mappings : formulas set for a specific property for components with the same name on all pages
- All pages roles : Roles allows to set a content in a few seconds by choosing a role in the list for components with the same name on all pages
Roles and bindings can be combined, the priority evaluation will be evaluated per property (text, background color ...) so it's possible to set a text on all pages, and color on a single page for instance.
It's highly suggested to use as much possible the "all pages" mappings and roles, it will avoid you the repetitive task to map the same things on all similar pages. That's why it's very important to name similar things with the same name on all pages.
The formulas are written using NCALC or JavaScript (see wiki https://github.com/zegreatclan/SimHub/wiki/NCalc-scripting---Introduction)
Click action is available on any component where send component Id is enabled on touch release event in the nextion editor
Virtual touch areas allows you to create virtual touch areas on the screen and associate an action (ie nextpage ...). Virtual touch areas definitions are shared across all pages and can be enabled and disabled per page. By default it will only be enabled on the page where it has been created.
The position is defined in screen percentages to avoid any issue if the template is resized or if the mapping is reused on another screen model.
Event triggers allows you to show the page temporary after an event occurred, the page shown can be dismissed using next/previous/back actions.
Condition trigger allows you to show the page as long as the formula result is "true". This kind of page switch can't be cancelled like event mappings and will last as long as the condition is true, when the condition will return to false, Simhub will switch back to the last page shown.
See here : https://www.youtube.com/watch?v=OjImrsHalLY