Skip to content
Copyright © 2024 4D Systems

GFX4dESP32: Slider and Gauge

Details
Number 4D-AN-00292
Difficulty Easy
Supported Processors ESP32-S3
Supported Environments ESP32-S3 Development Environment

Description

This application note demonstrates how to use Input and Gauge widgets in a touch-enabled ESP32-S3 4D Systems' display module such as a gen4-ESP32-32CT-CLB.

This project will detect how to use input widgets like a slider and display the values to a Gauge widgets using ESP32-S3-based display.

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.

It is also recommended to check the following application notes:

Application Overview

This application note will demontrate how to use a slider and coolgauge widgets on ESP32-S3-based display using Workshop4 IDE. Workshop 4 IDE 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.

Slider widget is used to accept touch detection and convert the values as useful data. In this application note, the slider values are used to update the value of a coolgauge. We will also explore the properties of a coolgauge.

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 SliderAndGaugeDemo.

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/SliderAndGaugeDemo

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. For example, you can change it to touch display like gen4-ESP32-28CT-CLB as shown.
  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 will use a Slider Widget as the input and Cool Gauge widget as the output.

Adding the Slider Widget

To add the Slider widget to the project:

  1. Go to Widgets menu.
  2. Navigate to Inputs pane.
  3. Select the Slider widget.

add-slider1

Click on the WYSIWYG area to place the widget.

wysiwyg-slider1

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 properties of the Slider as shown below.

slider1-properties

The final position of the Slider widget is shown below.

slider-final

Adding the Coolgauge Widget

To add the Coolgauge widget to the project:

  1. Go to Widgets menu.
  2. Navigate to Gauges pane.
  3. Select the Coolgauge widget.

add-coolgauge1

Click on the WYSIWYG area to place the widget.

wysiwyg-coolgauge1

Set the properties of the coolgauge as shown below.

coolgauge1-properties

For additional customization of the widgets, we will expand properties like Digit, Innercirle, Needle, and ValueFont. Click the + sign before the name of the property to expand as shown.

expand-digit

expanded-digit-properties

Digit

expanded-innercircle

InnerCircle

expanded-needle

Needle

expended-valuefont

ValueFont

The Digit option was expanded for setting the gauge digit color and background color.

The InnerCircle option was expanded for changing the inner circle color.

The Needle option was expanded for setting Colors, Inner, Outer and Shine colors.

The ValueFont option was expanded for change the font color and font name.

The final coolgauge and Form1 objects will now look as shown.

form1-final

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 Slider1 Code

Since we are using a touch enabled display, you can go to loop and place the blinking cursor inside the switch statement below the line // case statements for Knobs and Sliders go here. On the object Inspector, select the Form as Form1, select Object as Slider1 and click the Paste Static Code button as shown below.

slider-paste-code-btn

The generated code for slider is now pasted on setup and loop section.

gfx.imageTouchEnable(iSlider1, true) ;               // init_Slider1 enable touch of widget (on Form1)
gfx.UserImages(iSlider1,0) ;                         // init_Slider1 show initially, if required (on Form1)

case iSlider1 :                                      // process_Slider1 process (on Form1)
    val = gfx.imageAutoSlider(iSlider1, HORIZONTAL_SLIDER, gfx.touch_GetX(), 8, 8);
    // process Slider based on val
    break ;

Add Coolgauge1 Code

Paste the generated code for the Coolgauge object inside the case iSlider1 statement below the line // process Slider based on val. 

gfx.UserImages(iCoolgauge1,0) ;                     // init_Coolgauge1 show initialy, if required

// process Slider based on val
gfx.UserImages(iCoolgauge1, frame) ; // where val is 0 to 100 (for a displayed 0 to 100)

Change the parameter frame to val which will update the Coolgauge value to the current Slider value.

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 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