Saltar al contenido principal

Trabajar con PlatformIO

Esta página es la referencia de configuración de PlatformIO para los productos ePaper de Seeed. Se centra en las partes que son diferentes del flujo de trabajo con Arduino IDE:

  1. Instalar PlatformIO en Visual Studio Code.
  2. Entender la estructura del proyecto creada por PlatformIO.
  3. Editar platformio.ini, el archivo de configuración principal para la selección de placa, selección de framework, dependencias de librerías, velocidad del monitor serie, opciones de carga y flags de compilación.
  4. Elegir el entorno de PlatformIO correcto para cada producto ePaper de Seeed.
  5. Añadir Seeed_GFX y generar el driver.h correspondiente con la Seeed GFX Configuration Tool.

Si buscas APIs de dibujo para la pantalla, ejemplos de sketches o código de demostración específico de hardware, comienza por Work with Arduino y los recetarios de producto enlazados al final de esta página. El código C/C++ usado en PlatformIO suele ser el mismo que el código de Arduino. La principal diferencia es cómo se configura el proyecto.

Hardware compatible​

PlatformIO puede utilizarse con el flujo de trabajo basado en código para productos ePaper de Seeed que exponen una ruta de firmware compatible con Arduino. Usa esta página para preparar el proyecto de PlatformIO y luego selecciona el driver.h correcto para tu placa y pantalla.

Línea de productoMCU / placa objetivo típicaNotas de configuración
reTerminal E1001 / E1002 / E1003 / E1004reTerminal E Serie basado en ESP32-S3Usa un entorno PlatformIO para ESP32-S3 y luego genera driver.h para el modelo exacto de reTerminal.
Placas driver EE02 / EE03 / EE04 / EE05Familia XIAO ESP32-S3Usa la misma estructura de PlatformIO en toda la familia EE0x. El valor de BOARD_SCREEN_COMBO cambia con la placa y la pantalla seleccionadas.
Kit DIY TRMNL 7.5" (OG)Familia XIAO ESP32-S3Usa el entorno ESP32-S3 cuando escribas firmware personalizado de estilo Arduino en lugar de usar el firmware en la nube de TRMNL.
Panel ePaper XIAO 7.5"XIAO ESP32-C3Usa el entorno PlatformIO XIAO ESP32-C3 y luego usa el recetario del producto para la configuración específica de pantalla de driver.h.
EN04 / EN05 y placas ePaper basadas en nRF52840Familia XIAO nRF52840Usa el entorno PlatformIO nRF52840 para el desarrollo de firmware. Si aún no se ha publicado un recetario específico para ePaper, usa esta página como referencia de entorno y el esquema/recetario del producto para los pines.
nota

El proyecto de PlatformIO es solo el entorno de compilación y carga. La pantalla sigue dependiendo del driver.h correcto. Si platformio.ini es correcto pero driver.h apunta a la placa o al panel equivocados, el firmware puede compilarse y cargarse mientras la pantalla permanece en blanco.

¿Por qué PlatformIO para el desarrollo con ePaper?​

PlatformIO es útil cuando tu proyecto ePaper crece más allá de un único sketch:

  • Mantiene la placa, el framework, las librerías, la velocidad de carga, la velocidad del monitor serie y los flags de compilación en un único archivo platformio.ini bajo control de versiones.
  • Puede definir múltiples entornos de compilación en un solo proyecto, de modo que la misma base de código pueda dirigirse a varios productos ePaper de Seeed.
  • Descarga las librerías mediante lib_deps, lo que hace que el proyecto sea más fácil de reproducir en otro ordenador.
  • Proporciona tareas de compilación, carga, limpieza y monitor serie dentro de VS Code.

Para el dibujo en pantalla y las APIs de hardware, sigue usando el mismo código C/C++ de estilo Arduino utilizado en el recetario de Arduino. PlatformIO principalmente cambia la disposición del proyecto y el método de configuración.

Paso 1: Instalar VS Code y PlatformIO​

Paso 1. Descarga e instala Visual Studio Code.

Paso 2. Abre Extensions en VS Code, busca PlatformIO IDE e instálalo.

Paso 3. Reinicia VS Code después de que la extensión termine de instalarse.

Paso 4. Abre PlatformIO Home desde el icono de PlatformIO en la barra de actividad de VS Code.

tip

Si usas PlatformIO IDE en VS Code, PlatformIO Core viene incluido con la extensión. Solo necesitas instalar PlatformIO Core por separado si quieres usar el comando pio fuera de VS Code.

Paso 2: Crear un proyecto de PlatformIO​

Paso 1. En PlatformIO Home, selecciona New Project.

Paso 2. Introduce un nombre de proyecto.

Paso 3. Selecciona cualquier placa temporal compatible con Arduino que permita a PlatformIO crear el proyecto. Esta primera selección solo se usa para generar la carpeta del proyecto.

Paso 4. Selecciona Arduino como framework.

Paso 5. Haz clic en Finish y espera a que PlatformIO cree el proyecto.

Paso 6. Abre platformio.ini y reemplaza la configuración generada con la configuración de Seeed que se muestra en las siguientes secciones.

precaución

La mayoría de las placas de desarrollo de Seeed Studio utilizadas por esta línea de productos ePaper se mantienen a través del paquete de plataforma de PlatformIO de Seeed, no solo a través de la lista de placas predeterminada de PlatformIO. Si no puedes encontrar la placa exacta de Seeed en la ventana New Project de PlatformIO, es lo esperado. Primero crea un proyecto temporal y luego establece platform = https://github.com/Seeed-Studio/platform-seeedboards.git y el ID de board correcto en platformio.ini.

Tras la creación, los archivos y carpetas importantes son:

RutaPropósito
platformio.iniArchivo de configuración principal de PlatformIO. Este es el archivo más importante en esta guía.
src/main.cppArchivo fuente principal del firmware. Aquí va el código de estilo Arduino.
lib/Librerías locales opcionales. Este también es un lugar conveniente para una carpeta auxiliar local de driver.h.
.pio/Salida de compilación de PlatformIO y dependencias descargadas. No edites esta carpeta manualmente.

Paso 3: Entender platformio.ini​

platformio.ini es el centro de un proyecto PlatformIO. Cada sección [env:name] define un entorno de compilación. El entorno le indica a PlatformIO para qué placa compilar, qué framework usar, qué librerías descargar y cómo cargar o monitorizar el firmware.

Para principiantes, el flujo de trabajo más sencillo es copiar la configuración completa para tu dispositivo desde el Paso 4, pegarla en platformio.ini y luego crear el archivo driver.h correspondiente. No necesitas combinar por tu cuenta una sección base compartida con otra sección de dispositivo.

Los campos más importantes son:

CampoQué controlaEjemplo
platformEl paquete de plataforma de PlatformIO. Para las placas de Seeed en esta guía, usa la URL del paquete de plataforma de Seeed para que PlatformIO pueda descargar las definiciones de placas.platform = https://github.com/Seeed-Studio/platform-seeedboards.git
boardEl ID de placa de PlatformIO. Esto decide el MCU, la distribución de la memoria flash, la herramienta de carga y los ajustes de compilación predeterminados.board = seeed-xiao-esp32-s3-sense
frameworkEl framework de software utilizado por el firmware. Para ejemplos de estilo Arduino, usa arduino.framework = arduino
monitor_speedLa velocidad en baudios del monitor serie. Debe coincidir con Serial.begin(...) en el firmware.monitor_speed = 115200
upload_speedLa velocidad en baudios utilizada cuando PlatformIO flashea el firmware a través de USB serie.upload_speed = 115200
lib_depsLibrerías que PlatformIO descarga automáticamente para este entorno.https://github.com/Seeed-Studio/Seeed_GFX
build_flagsDefiniciones extra para el compilador. Úsalo solo cuando el recetario de tu producto o la librería lo requieran.-DBOARD_HAS_PSRAM
upload_portPuerto serie fijo opcional. Déjalo sin definir si prefieres la autodetección de PlatformIO.upload_port = /dev/ttyACM0
precaución

No copies platformio.ini a ciegas entre productos no relacionados. El mismo código fuente C/C++ puede ser portátil, pero board, los ajustes de PSRAM y driver.h deben coincidir con el hardware real.

Paso 4: Copiar la configuración para tu dispositivo​

Elige la pestaña de tu dispositivo, copia todo el bloque de platformio.ini y pégalo en el archivo platformio.ini de tu proyecto PlatformIO. La configuración se repite intencionadamente en cada pestaña para que no tengas que combinar una sección base compartida con una sección de dispositivo.

tip

La primera compilación puede tardar más porque PlatformIO descarga el paquete de plataforma de Seeed, la toolchain, el framework de Arduino y la biblioteca Seeed_GFX.

Utiliza esta configuración para 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

Utiliza driver.h generado para reTerminal E1001. En los ejemplos existentes de Seeed_GFX, E1001 utiliza:

#define BOARD_SCREEN_COMBO 520

Paso 5: Añadir driver.h​

platformio.ini selecciona el MCU y el entorno de compilación. driver.h selecciona la combinación de placa ePaper y pantalla utilizada por Seeed_GFX.

Paso 1. Abre la Seeed GFX Configuration Tool.

Paso 2. Selecciona tu placa y pantalla.

Paso 3. Copia la configuración generada.

Paso 4. Añade la configuración a un archivo driver.h que pueda ser incluido por tu firmware.

Un archivo generado típico se ve así:

#define BOARD_SCREEN_COMBO 502
#define USE_XIAO_EPAPER_DISPLAY_BOARD_EE04

Los valores comunes de BOARD_SCREEN_COMBO utilizados en la documentación ePaper existente incluyen:

HardwareEjemplo de ajuste generadoFuente de referencia
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" ePaper monocromo#define BOARD_SCREEN_COMBO 502
#define USE_XIAO_EPAPER_DISPLAY_BOARD_EE04		Seeed GFX Configuration Tool
Otras combinaciones EE0x / pantallaGenerado por placa y pantallaSeeed GFX Configuration Tool
precaución

Vuelve a generar siempre driver.h cuando cambies la placa ePaper, el tamaño de la pantalla, el tipo de color de la pantalla o la placa controladora. Un BOARD_SCREEN_COMBO que no coincide es una de las razones más comunes de una pantalla en blanco.

En última instancia, el código y el framework de proyecto para un producto de pantalla completo usando PlatformIO deberían ser los siguientes:

Paso 6: Compilar, subir y monitorizar​

Cuando platformio.ini y driver.h estén listos, utiliza la barra de herramientas de PlatformIO en VS Code:

AcciónQué hace
BuildCompila el entorno seleccionado y comprueba si la placa, el framework, las bibliotecas y el código son compatibles.
UploadSube el firmware al dispositivo conectado mediante el protocolo de subida seleccionado.
MonitorAbre el monitor serie utilizando la velocidad en baudios de monitor_speed.
CleanElimina las salidas de compilaciones anteriores. Úsalo después de cambiar paquetes de placa, ajustes de PSRAM o flags de compilación importantes.

Si el proyecto tiene múltiples entornos, selecciona el entorno de destino desde las tareas del proyecto PlatformIO antes de compilar o subir.

Opcional: usar la biblioteca Seeed_GxEPD2​

Los ejemplos predeterminados de esta página utilizan Seeed_GFX. Para proyectos que se basan en el flujo de trabajo de pantalla GxEPD2, puedes reemplazar la dependencia de la biblioteca de pantalla con el fork GxEPD2 de Seeed.

Utiliza esta opción solo cuando el código del proyecto esté escrito para las APIs Seeed_GxEPD2 / GxEPD2. Si tu código sigue los ejemplos estándar de Seeed_GFX, mantén Seeed_GFX en lib_deps.

Por ejemplo, una configuración de reTerminal E1001 se puede cambiar de la siguiente manera:

[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

Aquí solo se muestra una biblioteca de pantalla para mantener la configuración clara. Si tu proyecto necesita bibliotecas adicionales, añádelas en lib_deps como líneas separadas.

Dónde ir a continuación​

Esta página se centra intencionadamente en la configuración del entorno PlatformIO. Continúa con las páginas específicas del producto para el cableado, la selección de pantalla y el comportamiento del firmware:

Problemas comunes​

P1: ¿Por qué PlatformIO no muestra mi placa Seeed en la lista de placas?​

Esto es lo esperado para muchas placas de desarrollo de Seeed. Las definiciones de placa utilizadas en esta guía provienen del paquete de plataforma de Seeed para PlatformIO, por lo que puede que no aparezcan en la búsqueda de placas del Nuevo proyecto predeterminado de PlatformIO antes de que se instale el paquete.

Utiliza la URL del paquete de Seeed directamente en platformio.ini:

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

Luego establece board en el ID de placa de Seeed utilizado por tu producto, por ejemplo:

board = seeed-xiao-esp32-s3-sense

Cuando compiles por primera vez, PlatformIO descargará el paquete de plataforma y luego reconocerá el ID de la placa.

P2: ¿Por qué la carga del firmware se completa correctamente pero la pantalla de tinta electrónica permanece en blanco?​

La causa más común es un driver.h incorrecto o ausente.

  • Regenera driver.h con la herramienta de configuración Seeed GFX.
  • Confirma que la placa y la pantalla seleccionadas coinciden con el hardware real.
  • Confirma que el BOARD_SCREEN_COMBO generado está disponible para el archivo fuente que incluye Seeed_GFX.
  • Para productos ESP32-S3 con búferes grandes, confirma si el recetario del producto requiere configuraciones de PSRAM.

P3: ¿Por qué PlatformIO no puede cargar en la placa?​

Para reTerminal E1003, una causa común es una velocidad en baudios de carga demasiado alta. Establece upload_speed en 115200 en el mismo bloque de entorno antes de comprobar otras causas.

upload_speed = 115200

Si la carga sigue fallando, continúa con las siguientes comprobaciones:

  • Utiliza un cable USB-C que admita transferencia de datos.
  • Desconecta otros dispositivos serie e inténtalo de nuevo.
  • Establece upload_port solo si la detección automática elige el puerto incorrecto.
  • Para placas basadas en ESP32, mantén pulsado el botón de arranque mientras conectas el USB si la placa no entra automáticamente en modo de descarga.

Recursos​

Soporte técnico y debate sobre productos​

Gracias por elegir nuestros productos. Estamos aquí para ofrecerte diferentes tipos de soporte para garantizar que tu experiencia con nuestros productos sea lo más fluida posible. Ofrecemos varios canales de comunicación para adaptarnos a diferentes preferencias y necesidades.

Loading Comments...