Skip to main content

Work with PlatformIO

This page is the PlatformIO configuration reference for Seeed ePaper products. It focuses on the parts that are different from the Arduino IDE workflow:

  1. Installing PlatformIO in Visual Studio Code.
  2. Understanding the project structure created by PlatformIO.
  3. Editing platformio.ini, the main configuration file for board selection, framework selection, library dependencies, serial monitor speed, upload options, and build flags.
  4. Choosing the correct PlatformIO environment for each Seeed ePaper product.
  5. Adding Seeed_GFX and generating the matching driver.h with the Seeed GFX Configuration Tool.

If you are looking for display drawing APIs, example sketches, or hardware-specific demo code, start from Work with Arduino and the product cookbooks linked at the end of this page. The C/C++ code used in PlatformIO is usually the same as the Arduino code. The main difference is how the project is configured.

Compatible Hardware​

PlatformIO can be used with the code-based workflow for Seeed ePaper products that expose an Arduino-compatible firmware path. Use this page to prepare the PlatformIO project, then select the correct driver.h for your board and screen.

Product lineTypical MCU / board targetConfiguration notes
reTerminal E1001 / E1002 / E1003 / E1004ESP32-S3 based reTerminal E SeriesUse an ESP32-S3 PlatformIO environment, then generate driver.h for the exact reTerminal model.
EE02 / EE03 / EE04 / EE05 driver boardsXIAO ESP32-S3 familyUse the same PlatformIO structure across the EE0x family. The BOARD_SCREEN_COMBO value changes with the selected board and screen.
TRMNL 7.5" (OG) DIY KitXIAO ESP32-S3 familyUse the ESP32-S3 environment when writing custom Arduino-style firmware instead of using the TRMNL cloud firmware.
XIAO 7.5" ePaper PanelXIAO ESP32-C3Use the XIAO ESP32-C3 PlatformIO environment, then use the product cookbook for the screen-specific driver.h configuration.
EN04 / EN05 and nRF52840-based ePaper boardsXIAO nRF52840 familyUse the nRF52840 PlatformIO environment for firmware development. If an ePaper-specific cookbook is not published yet, use this page as the environment reference and the product schematic/cookbook for pins.
note

The PlatformIO project is only the build and upload environment. The display still depends on the correct driver.h. If platformio.ini is correct but driver.h targets the wrong board or panel, the firmware may compile and upload while the screen stays blank.

Why PlatformIO for ePaper Development?​

PlatformIO is useful when your ePaper project grows beyond a single sketch:

  • It keeps board, framework, libraries, upload speed, serial monitor speed, and build flags in one version-controlled platformio.ini file.
  • It can define multiple build environments in one project, so the same codebase can target several Seeed ePaper products.
  • It downloads libraries through lib_deps, which makes the project easier to reproduce on another computer.
  • It provides build, upload, clean, and serial monitor tasks inside VS Code.

For display drawing and hardware APIs, continue using the same Arduino-style C/C++ code used in the Arduino cookbook. PlatformIO mainly changes the project layout and configuration method.

Step 1: Install VS Code and PlatformIO​

Step 1. Download and install Visual Studio Code.

Step 2. Open Extensions in VS Code, search for PlatformIO IDE, and install it.

Step 3. Restart VS Code after the extension finishes installing.

Step 4. Open PlatformIO Home from the PlatformIO icon in the VS Code activity bar.

tip

If you use PlatformIO IDE in VS Code, PlatformIO Core is included with the extension. You only need to install PlatformIO Core separately if you want to use the pio command outside VS Code.

Step 2: Create a PlatformIO Project​

Step 1. In PlatformIO Home, select New Project.

Step 2. Enter a project name.

Step 3. Select any temporary Arduino-compatible board that lets PlatformIO create the project. This first selection is only used to generate the project folder.

Step 4. Select Arduino as the framework.

Step 5. Click Finish and wait until PlatformIO creates the project.

Step 6. Open platformio.ini and replace the generated configuration with the Seeed configuration shown in the next sections.

caution

Most Seeed Studio development boards used by this ePaper product line are maintained through Seeed's PlatformIO platform package, not only through PlatformIO's default board list. If you cannot find the exact Seeed board in the PlatformIO New Project window, that is expected. Create a temporary project first, then set platform = https://github.com/Seeed-Studio/platform-seeedboards.git and the correct board ID in platformio.ini.

After creation, the important files and folders are:

PathPurpose
platformio.iniMain PlatformIO configuration file. This is the most important file in this guide.
src/main.cppMain firmware source file. Arduino-style code goes here.
lib/Optional local libraries. This is also a convenient place for a local driver.h helper folder.
.pio/PlatformIO build output and downloaded dependencies. Do not edit this folder manually.

Step 3: Understand platformio.ini​

platformio.ini is the center of a PlatformIO project. Each [env:name] section defines one build environment. The environment tells PlatformIO which board to compile for, which framework to use, which libraries to download, and how to upload or monitor the firmware.

For beginners, the easiest workflow is to copy the complete configuration for your device from Step 4, paste it into platformio.ini, and then create the matching driver.h file. You do not need to combine a shared base section with another device section by yourself.

The most important fields are:

FieldWhat it controlsExample
platformThe PlatformIO platform package. For Seeed boards in this guide, use Seeed's platform package URL so PlatformIO can download the board definitions.platform = https://github.com/Seeed-Studio/platform-seeedboards.git
boardThe PlatformIO board ID. This decides the MCU, flash layout, upload tool, and default build settings.board = seeed-xiao-esp32-s3-sense
frameworkThe software framework used by the firmware. For Arduino-style examples, use arduino.framework = arduino
monitor_speedThe serial monitor baud rate. It should match Serial.begin(...) in the firmware.monitor_speed = 115200
upload_speedThe upload baud rate used when PlatformIO flashes the firmware through USB serial.upload_speed = 115200
lib_depsLibraries that PlatformIO downloads automatically for this environment.https://github.com/Seeed-Studio/Seeed_GFX
build_flagsExtra compiler definitions. Use this only when your product cookbook or library requires it.-DBOARD_HAS_PSRAM
upload_portOptional fixed serial port. Leave it unset if you prefer PlatformIO auto-detection.upload_port = /dev/ttyACM0
caution

Do not copy platformio.ini blindly between unrelated products. The same C/C++ source may be portable, but board, PSRAM settings, and driver.h must match the actual hardware.

Step 4: Copy the Configuration for Your Device​

Pick your device tab, copy the whole platformio.ini block, and paste it into the platformio.ini file in your PlatformIO project. The configuration is intentionally repeated in each tab so you do not need to merge a shared base section with a device section.

tip

The first build can take longer because PlatformIO downloads Seeed's platform package, the toolchain, the Arduino framework, and the Seeed_GFX library.

Use this configuration for reTerminal E1001:

[env:reterminal_e1001]
platform = https://github.com/Seeed-Studio/platform-seeedboards.git
board = seeed-xiao-esp32-s3-sense
framework = arduino
upload_speed = 115200
monitor_speed = 115200
board_build.arduino.memory_type = qio_opi
build_flags =
    -D BOARD_HAS_PSRAM
    -I src
lib_deps = https://github.com/Seeed-Studio/Seeed_GFX

Use driver.h generated for reTerminal E1001. In existing Seeed_GFX examples, E1001 uses:

#define BOARD_SCREEN_COMBO 520

Step 5: Add driver.h​

platformio.ini selects the MCU and build environment. driver.h selects the ePaper board and screen combination used by Seeed_GFX.

Step 1. Open the Seeed GFX Configuration Tool.

Step 2. Select your board and screen.

Step 3. Copy the generated configuration.

Step 4. Add the configuration to a driver.h file that can be included by your firmware.

A typical generated file looks like this:

#define BOARD_SCREEN_COMBO 502
#define USE_XIAO_EPAPER_DISPLAY_BOARD_EE04

Common BOARD_SCREEN_COMBO values used in existing ePaper documentation include:

HardwareExample generated settingSource of truth
reTerminal E1001#define BOARD_SCREEN_COMBO 520Seeed GFX Configuration Tool
reTerminal E1002#define BOARD_SCREEN_COMBO 521Seeed GFX Configuration Tool
reTerminal E1003#define BOARD_SCREEN_COMBO 522Seeed GFX Configuration Tool
reTerminal E1004#define BOARD_SCREEN_COMBO 523Seeed GFX Configuration Tool
EE04 + 7.5" monochrome ePaper#define BOARD_SCREEN_COMBO 502
#define USE_XIAO_EPAPER_DISPLAY_BOARD_EE04		Seeed GFX Configuration Tool
Other EE0x / screen combinationsGenerated per board and screenSeeed GFX Configuration Tool
caution

Always regenerate driver.h when you change the ePaper board, display size, display color type, or driver board. A mismatched BOARD_SCREEN_COMBO is one of the most common reasons for a blank screen.

Ultimately, the code and project framework for a complete screen product using PlatformIO should be as follows:

Step 6: Build, Upload, and Monitor​

After platformio.ini and driver.h are ready, use the PlatformIO toolbar in VS Code:

ActionWhat it does
BuildCompiles the selected environment and checks whether the board, framework, libraries, and code are compatible.
UploadUploads the firmware to the connected device through the selected upload protocol.
MonitorOpens the serial monitor using the baud rate from monitor_speed.
CleanRemoves previous build outputs. Use this after changing board packages, PSRAM settings, or major build flags.

If the project has multiple environments, select the target environment from the PlatformIO project tasks before building or uploading.

Optional: Use the Seeed_GxEPD2 Library​

The default examples on this page use Seeed_GFX. For projects that are based on the GxEPD2 display workflow, you can replace the display library dependency with Seeed's GxEPD2 fork.

Use this option only when the project code is written for Seeed_GxEPD2 / GxEPD2 APIs. If your code follows the standard Seeed_GFX examples, keep Seeed_GFX in lib_deps.

For example, a reTerminal E1001 configuration can be changed as follows:

[env:reterminal_e1001]
platform = https://github.com/Seeed-Studio/platform-seeedboards.git
board = seeed-xiao-esp32-s3-sense
framework = arduino
upload_speed = 115200
monitor_speed = 115200
board_build.arduino.memory_type = qio_opi
build_flags =
    -D BOARD_HAS_PSRAM
    -I src
lib_deps = https://github.com/Seeed-Projects/Seeed_GxEPD2

Only one display library is shown here to keep the configuration clear. If your project needs additional libraries, add them under lib_deps as separate lines.

Where to Go Next​

This page intentionally focuses on PlatformIO environment configuration. Continue with the product-specific pages for wiring, screen selection, and firmware behavior:

Common Issues​

Q1: Why does PlatformIO not show my Seeed board in the board list?​

This is expected for many Seeed development boards. The board definitions used in this guide come from Seeed's PlatformIO platform package, so they may not appear in PlatformIO's default New Project board search before the package is installed.

Use the Seeed package URL directly in platformio.ini:

platform = https://github.com/Seeed-Studio/platform-seeedboards.git

Then set board to the Seeed board ID used by your product, such as:

board = seeed-xiao-esp32-s3-sense

When you build for the first time, PlatformIO downloads the platform package and then recognizes the board ID.

Q2: Why does the firmware upload successfully but the ePaper display stays blank?​

The most common cause is a wrong or missing driver.h.

  • Regenerate driver.h with the Seeed GFX Configuration Tool.
  • Confirm the selected board and display match the real hardware.
  • Confirm the generated BOARD_SCREEN_COMBO is available to the source file that includes Seeed_GFX.
  • For ESP32-S3 products with large buffers, confirm whether the product cookbook requires PSRAM settings.

Q3: Why does PlatformIO fail to upload to the board?​

For reTerminal E1003, a common cause is an upload baud rate that is too high. Set upload_speed to 115200 in the same environment block before checking other causes.

upload_speed = 115200

If the upload still fails, continue with the following checks:

  • Use a USB-C cable that supports data transfer.
  • Disconnect other serial devices and try again.
  • Set upload_port only if auto-detection chooses the wrong port.
  • For ESP32-based boards, hold the boot button while connecting USB if the board does not enter download mode automatically.

Resources​

Tech Support & Product Discussion​

Thank you for choosing our products! We are here to provide you with different support to ensure that your experience with our products is as smooth as possible. We offer several communication channels to cater to different preferences and needs.

Loading Comments...