Working with Arduino

This chapter contains the following sections. Please read as needed:

• Arduino Getting Started
• Setting Up the Development Environment
• Example

Arduino Getting Started

New to Arduino ESP32 development and looking for a quick start? We have prepared a comprehensive Getting Started Tutorial for you.

• Section 0: Getting to Know ESP32
• Section 1: Installing and Configuring Arduino IDE
• Section 2: Arduino Basics
• Section 3: Digital Output/Input
• Section 4: Analog Input
• Section 5: Pulse Width Modulation (PWM)
• Section 6: Serial Communication (UART)
• Section 7: I2C Communication
• Section 8: SPI Communication
• Section 9: Wi-Fi Basics
• Section 10: Web Server
• Section 11: Bluetooth
• Section 12: LVGL GUI Development
• Section 13: Comprehensive Project

Note: This tutorial uses the ESP32-S3-Zero as a reference example, and all hardware code is based on its pinout. Before you start, we recommend checking the pinout of your development board to ensure the pin configuration is correct.

Setting Up the Development Environment

1. Installing and Configuring the Arduino IDE

Please refer to the tutorial Installing and Configuring Arduino IDE to download and install the Arduino IDE and add ESP32 support.

2. Installing Libraries

• When installing Arduino libraries, there are typically two methods: online installation and offline installation. If the library installation requires offline installation, you must use the provided library files.
• For most libraries, users can easily search for and install them via the Arduino IDE's online Library Manager. However, some open-source or custom libraries are not synchronized to the Arduino Library Manager and therefore cannot be found through online search. In this case, users can only install these libraries manually via offline methods. =

Library or File Name	Description	Version	Installation Method
LVGL	Graphics library	v8.4.0	"Online Installation"
JPEGDEC	JPEG decoder library	v1.8.4	"Online Installation"
GFX_Library_for_Arduino	LCD driver library	v1.5.9	"Online Installation"

Version Compatibility Notes

There are strong dependencies between versions of LVGL and its driver libraries. For example, a driver written for LVGL v8 may not be compatible with LVGL v9. To ensure that the examples can be reproduced reliably, it is recommended to use the specific versions listed in the table above. Mixing different versions of libraries may lead to compilation failures or runtime errors.

3. Arduino Project Parameter Settings

Example

The Arduino examples are located in the Arduino/examples directory of the example package.

Example	Basic Description	Dependent Libraries	Version
01_gfx_helloworld	Display HelloWorld on the screen	GFX_Library_for_Arduino
02_sd_card_test	Test TF card	JPEGDEC	-
03_Brightness	Control backlight using buttons	LVGL	8.4.0
04_LVGL	Run LVGL benchmark example	LVGL	8.4.0

01_gfx_helloworld

Example Description

• This example demonstrates the ESP32-C3-LCD-1.47 using the GFX_Library_for_Arduino library to drive the screen and display "HelloWorld".

Hardware Connection

• Connect the board to the computer using a USB cable.

Code Analysis

• loop(): Continuously refreshes the displayed content, printing a line of text at random positions, colors, and font sizes each time.
• gfx->setCursor(): Sets the starting coordinates for this text output.
• gfx->setTextColor(): Sets the foreground/background color (random values are used here to make the refresh effect observable).
• gfx->setTextSize(): Sets the font size scaling factor (randomly varied).
• gfx->println("Hello World!") / delay(1000): Outputs the text and delays for 1 second, creating a dynamic animated demonstration.

  void loop(void)
  {
    gfx->setCursor(random(gfx->width()), random(gfx->height()));
    gfx->setTextColor(random(0xffff), random(0xffff));
    gfx->setTextSize(random(6), random(6), random(2));
    gfx->println("Hello World!");
    delay(1000);
  }

Operation Result

• HelloWorld is displayed on the screen.

  

02_SD

Example Description

• This example demonstrates the ESP32-C3-LCD-1.47 reading a JPG image from the TF card and displaying it on the screen.

Hardware Connection

• Connect the board to the computer.
• Insert the TF card into the card slot (the TF card needs to be formatted as FAT32).
• Place the image image_01.jpg in the root directory of the TF card.

Code Analysis

• jpgPath: The path to the JPG file to be displayed (found in the TF card root directory).

• Serial.printf("draw: %s\r\n", jpgPath): Outputs the filename to be drawn to the serial port, making it easy to confirm the correct image is read.

• gfx->fillScreen(RGB565_BLACK): Clears the screen before drawing to avoid residual images or frame stacking.

  Serial.printf("draw: %s\r\n", jpgPath);
  gfx->fillScreen(RGB565_BLACK);

Operation Result

• After flashing, the image is displayed on the screen.

03_Brightness

Example Description

• This example demonstrates controlling the screen brightness using the BOOT button. Double‑clicking the BOOT button switches the control logic.

Hardware Connection

• Connect the board to the computer.

Code Analysis

• gfx->fillScreen(RGB565_WHITE): Clears the screen and sets the UI background color.
• gfx->printf("Brightness %u%%", backlight): Outputs the current backlight percentage to the screen.
• drawBarFrame() / drawBarValue(): Draws the brightness bar border and the current brightness fill, providing an intuitive visualization of brightness changes.
• increase ? ... : ...: Displays the current mode ("Increase/Decrease") based on the control logic, using red/green for distinction.

  gfx->fillScreen(RGB565_WHITE);
  gfx->setTextColor(RGB565_BLACK, RGB565_WHITE);
  gfx->setTextSize(2);
  gfx->setCursor(18, 30);
  gfx->println("BOOT Control");

  gfx->setCursor(18, 90);
  gfx->printf("Brightness %u%%", backlight);

  drawBarFrame(18, 125, 144, 20);
  drawBarValue(18, 125, 144, 20, backlight);

  gfx->setCursor(18, 175);
  gfx->setTextColor(increase ? RGB565_RED : RGB565_GREEN, RGB565_WHITE);
  gfx->println(increase ? "Mode: Increase" : "Mode: Decrease");

  gfx->setCursor(18, 260);
  gfx->setTextColor(RGB565_BLACK, RGB565_WHITE);
  gfx->println("Double Click Switch");

Operation Result

04_LVGL

Example Description

• This example demonstrates the ESP32-C3-LCD-1.47 running the LVGL benchmark example.

  Serial.begin(115200);
  delay(50);
  Serial.println("ESP32_C3_LCD_1in47 LVGL example");

  if (!lcd.begin()) {
    Serial.printf("lcd.begin failed: %s\r\n", esp_err_to_name(lcd.lastError()));
    while (true) {
      delay(1000);
    }
  }

  gfx = lcd.gfx();
  gfx->fillScreen(RGB565_BLACK);

  if (!initLvgl()) {
    Serial.println("LVGL init failed");
    gfx->setCursor(8, 8);
    gfx->setTextColor(RGB565_RED);
    gfx->println("LVGL init failed");
    while (true) {
      delay(1000);
    }
  }

Code Analysis

• Serial.begin(115200): Initializes the serial port for outputting runtime logs and error messages.
• lcd.begin(): Initializes the LCD driver and low‑level bus; on failure, prints an error and halts in a while (true) loop to prevent further abnormal execution.
• gfx = lcd.gfx() / gfx->fillScreen(RGB565_BLACK): Obtains the graphics library handle and clears the screen to prepare an initial canvas for subsequent UI drawing.
• initLvgl(): Initializes LVGL (display buffer/driver registration, etc.); on failure, displays a prompt on the screen and enters a while (true) loop to preserve the state for troubleshooting.

Operation Result