GFX4dESP32: Buttons and User LED Widgets
Details
Number | 4D-AN-00291 |
Difficulty | Easy |
Supported Processors | ESP32-S3 |
Supported Environments | ESP32-S3 Development Environment |
Description
This application note demonstrates how to use Buttons and LED widgets in a touch-enabled ESP32-S3 4D Systems' display module such as a gen4-ESP32-32CT-CLB.
The project will detect touch inputs from the user and evaluate if a button is pressed. If a button is pressed, this project will update the LED widgets as programmed.
Prerequisites
To effectively use this application note, it is recommended to have prior Arduino programming experience. Experience in Workshop4 development for any 4D Systems' display module is also recommended but is not required since this application note will briefly discuss each step.
Application Overview
This application note will demonstrate how to use an ESP32-S3 display on Workshop4 IDE. Workshop4 is a comprehensive software that can provide code and graphics editor for ESP32-S3-based modules. It utilises the Arduino IDE 2.x CLI to handle the compiling, linking and downloading of ESP32-S3-based projects using the ESP32 Arduino Core and associated libraries.
Workshop4 is used to design graphical interfaces and then paste the code into the editor to aid manual editing before compiling and uploading it to the ESP32 display.
This project will be using Buttons and LED Widgets. Buttons will be programmed to detect and respond to touch inputs (press and release) and can be configured as momentary or toggle. The Userleds will indicate the status of the buttons.
Setup Procedure
ESP32 Development in Workshop4 requires that both Arduino 2.x CLI and Workshop4 IDE are installed in your Windows system. For detailed instructions on the complete development setup, please refer to the Workshop4: ESP32 Development Manual
The project used in this application note can be found in the GFX4dESP32 library examples titled ButtonsAndLedsDemo.
Navigate to the libraries folder of your Arduino installation. By default, it should be in:.
C:\Users\%USERNAME%\Documents\Arduino\libraries
For more information in locating the library folder, please refer to Arduino documentation.
You can find the example in: GFX4dESP32/examples/ButtonsAndLedsDemo
Simply double click the .4dArdUsd
file to open the project in Workshop4.
Note
The library and the project can also be downloaded directly from the GitHub repository.
Changing the Target Display
To change the target display of the project to your display:
- Navigate to the Project menu.
- Click the current display dropdown as shown.
A Display Window will pop up as shown:
- Select the target display from the dropdown. In this case, we are using gen4-ESP32-32CT-CLB as a target display.
- You can also change the orientation of the display. In this case, we will leave it as it is.
- Then click the OK button
You will notice that the display will now change to your target display.
Create the Project
Open Workshop4 and from the File menu, navigate as shown:
- Select New to select a new target display module.
- Set the dropdown to Arduino Embedded to filter the displays.
- Select your display module. For this application note, gen4-ESP32-32CT-CLB is used.
- Find the orientation that is best for your application. For this project, Portrait (or Portrait Rotated) is most suitable.
- Finally, click Next to create a fresh project.
Please refer to the section Creating a New Project of the Workshop4: ESP32 Development Manual for visual guide and more information.
The project will start with an empty WYSIWYG and the initial code as shown:
Note
The initial code generated for non-touch display modules differs from touch-enabled displays which is what is shown above.
Designing a Graphical Interface
For this project, we need 4 pairs of button and LED. Each pair will be used to demonstrate each of the available modes.
Adding the 4D Button Widget
In this project, we will be using four (4) 4D Button widgets and configure some of its properties like size, position and mode.
Button widgets have 4 modes referring to how it should respond to touch. This can be set using the Momentary property to the following.
- Yes - this is the default mode. In this mode, the button should be considered ON when a press/hold is triggered and OFF otherwise.
- No - In this mode, the button behaves in Toggle mode. The button holds its own value as either ON or OFF. The button value changes with each press and can be evaluated.
- On - This is the same as Momentary No (Toggle mode) except the button starts turned ON.
- Both - For ESP32-S3 development, this behaves completely similar to Momentary Yes
Note
Momentary Both mode behaves differently in ViSi Genie projects which requires a displays with DIABLO-16, PIXXI-28, PIXXI-44 or PICASO processor.
To add a 4Dbutton widget to the project:
- Go to Widgets menu.
- Navigat to Buttons pane.
-
Select Button01 widget.
Click on the WYSIWYG area to place the widget
The position of the widget can be changed by simply performing a drag-and-drop. Widget properties can also be edited through the Object Inspector's Property Table. Set the values of the 4Dbutton properties as shown.
The 4Dbutton1 on the WYSIWYG will update to the current set position.
Add 3 more 4D Button widgets with the following properties.
The final position of the four (4) 4Dbuttons is shown:
Adding the Userled Widget
To add the Userled widget:
- Go to Widgets menu.
- Navigate to Digits tab.
- Click on Userled widget.
Click on the WYSIWYG area to place the widget.
Change the Userled properties through the Object Inspector's Properties Table as shown.
The Userled will now position as shown.
Add 3 more Userled widget with the following properties.
The final position of all widgets as shown.
Writing the Code
Workshop4 provides new projects with initial code based on the target display. This includes setup code required for the screen and touch handling code for touch enabled display modules.
For discussion of the preliminary code, please refer to the section Preliminary Code of the Workshop4: ESP32 Development Manual
Generating Widget Code
Workshop4 provides a useful utility allowing code generation for each of the widget in their project greatly reducing development time.
Note
It is highly recommended that the graphics design / user interface is finalized before doing writing code. This is because some widgets require additional information to be in the generated code which can change when the user interface is altered.
In the event that the user interface is altered, the uSD card files should be re-uploaded and the generated code should be regenerated and updated in the appropriate parts of the code.
To use this feature, select a part of your code and put the blinking cursor in the desired position. This is where Workshop4 will generate the update code for the widget selected.
For information on generating a widget code, please refer to the section Generating Widget Code of the Workshop4: ESP32 Development Manual
Add 4Dbutton Code
On the Object Inspector, select the Form as Form1, select 4Dbutton1 from the Object and click the Paste Static Code button as shown below.
The generated code will be paste in two parts, one inside the setup and the other is in loop.
From the last line in setup, you will notice the additional generated code.
gfx.imageTouchEnable(i4Dbutton1, true, MOMENTARY) ;
// init_4Dbutton1 enable touch of widget (on Form1)
gfx.UserImages(i4Dbutton1,0) ; // init_4Dbutton1 show initially, if required (on Form1)
On the loop, you will notice that the generated code is paste inside the switch statement.
case i4Dbutton1 : // process_4Dbutton1 process Button (on Form1)
// process 4dbutton, for toggle val will be 1 for down and 0 for up
break ;
To generate the static code for 4Dbutton2, 4Dbutton3 and 4Dbutton4 widgets. On the Object Inspector Object, select the widgets and click on the Paste Static Code button to generate the code for each.
This will complete the generated code for 4dbutton01.
gfx.imageTouchEnable(i4Dbutton1, true, MOMENTARY) ;
// init_4Dbutton1 enable touch of widget (on Form1)
gfx.UserImages(i4Dbutton1,0) ; // init_4Dbutton1 show initially, if required (on Form1)
gfx.imageTouchEnable(i4Dbutton2, true, MOMENTARY) ;
// init_4Dbutton2 enable touch of widget (on Form1)
gfx.UserImages(i4Dbutton2,0) ; // init_4Dbutton2 show initially, if required (on Form1)
gfx.imageTouchEnable(i4Dbutton3, true, TOGGLE4STATES) ;
// init_4Dbutton3 enable touch of widget (on Form1)
gfx.UserImages(i4Dbutton3,0) ; // init_4Dbutton3 show initially, if required (on Form1)
gfx.imageTouchEnable(i4Dbutton4, true, TOGGLE4STATES) ;
// init_4Dbutton4 enable touch of widget (on Form1)
gfx.UserImages(i4Dbutton4,2) ;
// init_4Dbutton4 show initially in on state, if required (on Form1)
switch (button)
{ // start button selection **do not alter, remove or duplicate this line**
case i4Dbutton1 : // process_4Dbutton1 process Button (on Form1)
// process 4dbutton, for momentary val can be ignored
break ;
case i4Dbutton2 : // process_4Dbutton2 process Button (on Form1)
// process 4dbutton, for momentary val can be ignored
break ;
case i4Dbutton3 : // process_4Dbutton3 process Button (on Form1)
// process 4dbutton, for toggle val will be 1 for down and 0 for up
break ;
case i4Dbutton4 : // process_4Dbutton4 process Button (on Form1)
// process 4dbutton, for toggle val will be 1 for down and 0 for up
break ;
} // end button selection **do not alter, remove or duplicate this line**
Add Userled Code
For buttons that configured as momentary Yes, we need to declare additional variables and statements. Inside the loop, add the following variables:
Inside the case statement i4Dbutton1
, insert the line of code:
This toggles the variable from 0 (OFF) and 1 (ON) which we can use to update the LED widget. Afterwards, Place the cursor below this line.
On the Object Inspector, select the Form as Form1 and Object as Userled1 before clicking the Paste Static Code button.
Now, change the parameter on
to iUserled1Val
.
The final case statement for case i4Dbutton1:
will now shown.
case i4Dbutton1 : // process_4Dbutton1 process Button (on Form1)
// process 4dbutton, for momentary val can be ignored
iUserled1Val = (iUserled1Val != 0) ? 0 : 1;
gfx.UserImages(iUserled1, iUserled1Val) ; // Userled1 where val is 0 (Off) or 1 (On)
break ;
Inside the case statement i4Dbutton2
, insert the line of code
Afterwards, place the cursor below this line.
On the Object Inspector, select the Form as Form1 and Object as Userled2 before clicking the Paste Static Code button.
Then, change the parameter on
to iUserled2Val
.
The final case statement for i4Dbutton2
is shown.
case i4Dbutton2 : // process_4Dbutton2 process Button (on Form1)
// process 4dbutton, for momentary val can be ignored
iUserled2Val = (iUserled2Val != 0) ? 0 : 1;
gfx.UserImages(iUserled2, iUserled2Val) ; // Userled2 where val is 0 (Off) or 1 (On)
break ;
For Userled3 and Userled4 move the cursor inside the i4Dbutton3
and i4Dbutton4
case statements respectively before clicking the the Paste Static Code button.
Then use val
as the value for both iUserled3 and iUserled4. The variable val
is the current value of the image touched.
The final case statement for i4Dbutton3
and i4Dbutton4
is shown.
case i4Dbutton3 : // process_4Dbutton3 process Button (on Form1)
// process 4dbutton, for toggle val will be 1 for down and 0 for up
gfx.UserImages(iUserled3, val) ; // Userled3 where val is 0 (Off) or 1 (On)
break ;
case i4Dbutton4 : // process_4Dbutton4 process Button (on Form1)
// process 4dbutton, for toggle val will be 1 for down and 0 for up
gfx.UserImages(iUserled4, val) ; // Userled4 where val is 0 (Off) or 1 (On)
break ;
You will also notice that the line of codes below are added to setup.
gfx.UserImages(iUserled1,0) ; // init_Userled1 show initialy, if required
gfx.UserImages(iUserled2,0) ; // init_Userled2 show initialy, if required
gfx.UserImages(iUserled3,0) ; // init_Userled3 show initialy, if required
gfx.UserImages(iUserled4,0) ; // init_Userled4 show initialy, if required
Since we are pairing iUserled4 with i4Dbutton4, we'd want it to start ON. To do this, simply change the value to 1.
Compile the Project
After completing the project, it can be compiled by navigating to Home menu and clicking Compile.
When compiling a fresh project, you will be prompted to save the project before the compilation proceeds. Save the project to your desired location and with an appropriate filename to continue.
Workshop4 will prepare the necessary graphics files and will prompt you to copy the necessary files to a uSD. Insert a FAT16/FAT32 formatted card and select it from the dropdown menu.
Click uSD Copy to proceed with the copy. After completing the copy, eject the uSD from your computer and insert it to your display module.
Workshop4 will compile the code afterwards and will display similar log messages as shown:
Load the Project
To load the project to your display module, connect the display to your computer using a USB-C cable or using a 4D-UPA (rev 1.4 or higher).
In the Comms menu, select the port designated for the display.
Afterwards, navigate to the Home menu and click Download.
If the project hasn't been compiled prior to this or requires a recompile, the button with be Comp'nLoad instead.
If it requires a compile process, it will follow the same process as discussed in Compile the Project section.
After a successful compilation, Workshop4 will proceed with the upload and display log as shown: