GFX4dESP32: Random Values Using Spectrum
Details
| Number | 4D-AN-00290 |
| Difficulty | Easy |
| Supported Processors | ESP32-S3 |
| Supported Environments | ESP32-S3 Development Environment |
Description
This application note demonstrates how to use a Spectrum widget in a ESP32-S3 4D Systems' display module such as a gen4-ESP32-32 or gen4-ESP32-32CT-CLB.
A spectrum widget is composed of a base image and one or more bars that are displayed in columns.
The project will generate simple pseudo-random values to update each bar of the spectrum widget from its minimum to its maximum value.
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.
The project is created for gen4-ESP32-32 display module and is applicable for all ESP32-S3 displays from 4D Systems. The project consists of a single Form which contains a single Spectrum widget.
The Spectrum widget includes 10 columns covering the whole gen4-ESP32-32 screen.
Setup Procedure
ESP32 Development in Workshop4 requires that both Arduino IDE and Workshop4 IDE are installed in your Windows system. For detailed instructions of the complete development setup, please refer to the Workshop4: ESP32 Development Manual
The project used in this application can be found in the GFX4dESP32 library examples titled SpectrumDemo.
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/SpectrumDemo
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. For example, you can change it to touch display like gen4-ESP32-32CT-CLB as shown.
- 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
This section discusses how the project can be created from a fresh Workshop4 project.
Start a New 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-32 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 touch-capable display modules differs from non-touch displays which is what is shown above.
Designing a Graphical Interface
For this project, we need a single Spectrum widget.
To add the Spectrum widget to the project, navigate to Widgets -> Gauges and click the Spectrum button as shown.
Click on the WYSIWYG to place the widget.
The position of the widget can be changed by simply performing a drag-n-drop. Colour and size properties can also be edited through the Object Inspector's Property Table.
The project used in this application note contains 10 columns covering the whole screen.
The property values used are shown below:
Writing the 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 this example, the cursor is placed inside the loop function.
In your Object inspector, ensure that Spectrum1 in Form1 is selected:
Click Paste Static Code as shown above to generate the code.
As shown in the paste code, there are variables frame and bar which corresponds to the value and the column of the spectrum. These variables need to be declared or replaced as necessary.
Note
Notice that there is also a line of code added in the setup function.
gfx.UserImage(iSpectrum1) ; // init_Spectrum1 show initial spectrum
This is required to display the spectrum widget initially.
When working with multiple forms, the widgets need to be grouped manually and displayed according to the current active form. It is up to the user to implement this after generating code for the widgets.
In this application note, a simple for-loop is used using the variable bar while the frame value is a pseudo-random number that is generated each iteration of the loop.
The complete code used in this project is as shown:
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 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:
