ESPboy Library

This library provides a driver for the ESPboy handheld designed by Roman Sokolov.

It relies on the following dependencies:

I noticed that most of the developments around the ESPboy have embraced Bodmer’s TFT_eSPI library, but I prefer the LovyanGFX library which has better optimizations. Its author, lovyan03, has kindly agreed to add support for ESP8266 to make our life with ESPboy easier. You can thank him by starring :star: his library.

GitHub repository: ESPboy Library

Getting Started

To help you get to grips with this ESPboy library and make it easier for you to develop your projects on ESPboy, we will go through the different steps to help you get started.

Most of you are probably used to Arduino IDE, but I propose here to discover another environment, easy to learn, and better designed for programming on microcontrollers: PlatformIO IDE. It’s built on top of Microsoft’s Visual Studio Code, it’s free and open source.

So here is the process we will follow:

  1. Installing Visual Studio Code
  2. Adding plugins to Visual Studio Code
  3. Installing PlatformIO IDE
  4. Creating a new project for ESPboy
  5. Embedding the ESPboy library
  6. Testing an example of the library
  7. Compiling and uploading code to the ESPboy

Installing Visual Studio Code

First of all, you need to install Visual Studio Code, which is an excellent editor for programming, and is recommended to use PlatformIO IDE. To do this, go to the download page:

Download Visual Studio Code

You should land on this page:

VS Code Home Page

Download the version that corresponds to your OS (macOS, Linux or Windows), then launch the installation. Once the application is installed, simply open it:

Open Visual Studio Code

A customization tab is offered to you right away. You can come back to it later. For now, you can close it.

Adding plugins to Visual Studio Code

Visual Studio Code comes with a set of features that you can extend by adding plugins. There are all kinds of plugins, but let’s take a look at two of them that will improve the visual appearance of the editor:

Let’s see how with a short video:

Installing PlatformIO IDE

The PlatformIO IDE is also a plugin that you can install to turn your new editor into a complete integrated development environment for microcontroller programming. Be patient, the installation may take a few minutes depending on your connection speed:

To open the PlatformIO welcome page, you will notice the :house: icon in the bottom bar of the editor window:

Welcome Page of PlatformIO

Well, now that the development environment is installed, we can get down to business.  :wink:

Creating a new project for ESPboy

For the moment, PlatformIO does not yet include a development platform for a particular family of microcontrollers. When creating a new project, we have to specify the type of board we want to use. From there, PlatformIO will automatically download all the necessary tools for programming, compiling and uploading the code to the selected board.

The ESPboy embeds an ESP8266 on a WeMos D1 mini board.
So let’s see how to create a new project by setting the right board:

You can see that after creating the project, a new Espressif 8266 development platform has appeared in the Platforms section of PlatformIO. Installing the tools for a new platform may take a few minutes the first time, but it won’t be necessary for a future project based on the same microcontroller family.

At the end of the creation process, the editor displays the contents of a file named platformio.ini. Every PlatformIO project has a platformio.ini configuration file in the root directory of the project. It is precisely in this file that we will define a set of properties specific to the project.

Each project may have multiple configuration environments defining the available project tasks for building, programming, debugging, unit testing, device monitoring, library dependencies, etc. The configuration environments are declared using [env] sections in platformio.ini.

A section with an env: prefix defines a working environment. Multiple [env:name] environments with different name are allowed. Every project must define at least one working environment. By default, the predefined working environment has the name of the board selected during the project setup. But we can name it whatever we want. We’ll see about that later.

You will notice that we also find the specifications of:

…that we had defined when we created the project:

platform  = espressif8266
board     = d1_mini
framework = arduino

To this we have added the following properties to specify the operating frequency of the microcontroller, as well as the communication speed of the serial monitor and the upload speed used to flash the program:

platform          = espressif8266
board             = d1_mini
framework         = arduino
board_build.f_cpu = 80000000L
monitor_speed     = 115200
upload_speed      = 1500000

Now we just need to add a dependency to the ESPboy library to start coding.

Embedding the ESPboy library

First of all, we rename the working environment by replacing d1_mini with espboy. Then we add a dependency to the ESPboy library:

lib_deps =

Simply saving the platformio.ini file then triggers the automatic download of the ESPboy library from its GitHub repository, along with all its own dependencies! Isn’t that magic? I told you PlatformIO would make things easier.  :wink:

You can see that the libraries needed for the project appear progressively in the file explorer, under the .pio/libdeps/espboy folder:

├── Adafruit BusIO
├── Adafruit MCP23017 Arduino Library
├── Adafruit MCP4725
├── ESPboy
└── LovyanGFX

You can also notice that as long as the download of the dependencies is not finished, a file named espboy.lock is present in the receiving folder. The download of all the dependencies may take some time depending on your connection speed, especially for the LovyanGFX library. But once the download is finished, the espboy.lock file disappears.

From this point on, we can finally start coding using the definitions in the ESPboy library. The source file that is the entry point for your program is named main.cpp by default and is located in the src folder.

The bare minimum to start coding with the ESPboy library is the following code:

#include <ESPboy.h>

void setup() {

void loop() {

The espboy object is predefined by the library and corresponds to the programming interface to interact with the ESPboy driver. Beyond this simplistic source code that doesn’t do anything very exciting, let’s pick a more interesting one among the examples provided with the library.

Testing an example of the library

The examples folder contains some source code that will help you get to grips with the ESPboy library by covering its main features:

├── 1-bootstrap.cpp
├── 2-start-logo.cpp
├── 3-buttons.cpp
├── 4-neopixel.cpp
├── 5-game-of-life.cpp
├── 6-snake.cpp
└── 7-spaceship.cpp

You can test them easily by copying their contents into the main.cpp file of your project:

Compiling and uploading code to the ESPboy

To compile your project and upload the program to your ESPboy, use the buttons shown below:

Build and Upload

Don’t forget to connect your ESPboy to your PC with a USB cable and turn it on before uploading.