Skip to content

GFX4dESP32: Random Values Using Spectrum


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


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.


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.

Spectrum Demo Project

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:


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.


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.


A Display Window will pop up as shown:


  1. Select the target display from the dropdown. For example, you can change it to touch display like gen4-ESP32-32CT-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.


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:

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

Non-Touch Initial Code


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.

Select Spectrum Widget

Click on the WYSIWYG to place the widget.

Add Spectrum 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.

Modified Spectrum Widget

The property values used are shown below:

Modify Spectrum Widget

Writing the Code

Workshop4 provides a useful utility allowing code generation for each of the widget in their project greatly reducing development time.


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.

Select Cursor Position

For this example, the cursor is placed inside the loop function.

In your Object inspector, ensure that Spectrum1 in Form1 is selected:

Select Form1-Spectrum1

Click Paste Static Code as shown above to generate the code.

Form1-Spectrum1 Code Generated

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.


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:

Form1-Spectrum1 Code Modified

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