Skip to content
Copyright © 2024 4D Systems

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.

application-overview

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:

  1. Navigate to the Project menu.
  2. Click the current display dropdown as shown.

project-Display

A Display Window will pop up as shown:

change-display

  1. Select the target display from the dropdown. In this case, we are using gen4-ESP32-32CT-CLB as a target display.
  2. You can also change the orientation of the display. In this case, we will leave it as it is.
  3. Then click the OK button

You will notice that the display will now change to your target display.

target-display

Create the Project

Open Workshop4 and from the File menu, navigate as shown:

Create New Project

  1. Select New to select a new target display module.
  2. Set the dropdown to Arduino Embedded to filter the displays.
  3. Select your display module. For this application note, gen4-ESP32-32CT-CLB is used.
  4. Find the orientation that is best for your application. For this project, Portrait (or Portrait Rotated) is most suitable.
  5. 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:

Touch Initial Code

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:

  1. Go to Widgets menu.
  2. Navigat to Buttons pane.

  3. Select Button01 widget.

    button01-widget

Click on the WYSIWYG area to place the widget

4dbutton1-wysiwyg

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.

4dbutton1-properties

The 4Dbutton1 on the WYSIWYG will update to the current set position.

4dbutton1_position

Add 3 more 4D Button widgets with the following properties.

4dbutton2-properties

4dbutton2-properties

4dbutton2-properties

The final position of the four (4) 4Dbuttons is shown:

final-4dbuttons-position

Adding the Userled Widget

To add the Userled widget:

  1. Go to Widgets menu.
  2. Navigate to Digits tab.
  3. Click on Userled widget.

userled-widget

Click on the WYSIWYG area to place the widget.

userled_wysiwyg

Change the Userled properties through the Object Inspector's Properties Table as shown.

userled1-properties

The Userled will now position as shown.

userled1_position

Add 3 more Userled widget with the following properties.

userled2-peoperties

userled3-peoperties

userled4-peoperties

The final position of all widgets as shown.

complete-widgets

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.

paste-4dbutton1

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:

static int iUserled1Val = 0;
static int iUserled2Val = 1;

Inside the case statement i4Dbutton1, insert the line of code:

iUserled1Val = (iUserled1Val != 0) ? 0 : 1;

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.

gfx.UserImages(iUserled1, on) ;      // Userled1 where numx is 0 (Off) or 1 (On)

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

iUserled2Val = (iUserled2Val != 0) ? 0 : 1;

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.

gfx.UserImages(iUserled2, on) ;      // Userled2 where numx is 0 (Off) or 1 (On)

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.

gfx.UserImages(iUserled3, on) ;      // Userled3 where numx is 0 (Off) or 1 (On)            

gfx.UserImages(iUserled4, on) ;      // Userled4 where numx is 0 (Off) or 1 (On)

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.

gfx.UserImages(iUserled4,1) ;                   // init_Userled4 show initialy, if required

Compile the Project

After completing the project, it can be compiled by navigating to Home menu and clicking Compile.

Compile Project

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.

Select uSD Drive

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:

Compile Messages

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.

Select Port

Afterwards, navigate to the Home menu and click Download.

Load Project

If the project hasn't been compiled prior to this or requires a recompile, the button with be Comp'nLoad instead.

Compile and Load Project

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:

Upload Messages