ESP8266 Arduboy

2019 Aug 17 cheungbx

Many people have discussed and shared videos running Arduboy games on ESP8266. However, I have not seen any source codes shared by anyone for games running on a ESP8266 with working Aruboy2 library that support push buttons. Hence I try to make one myself and share it.
Here is my youtube video that demonstrate the games that are working so far.

ESP8266 has pros and cons as a portable game console compared to the original Arduboy using ATmega32U4 (Pro Micro).


  • heavy power consumption, will only run for 1-2 hours max on a tiny LIPO battery.
  • limited GPIO pins hence cannot support other features in the original Arduboy, e.g. RGB LED, two audio output pins.
  • due to the above, restricted to using I2C for OLED display which may slow down some complex games
  • sound support is minimal, only through the beeping function.
  • support on background music and other sound related library that require timer interrupts is a challenge. I have not see a working library that support this yet.


  • faster CPU 80Mh/160Mhz may compensate for some of the slowless mentioned above except for the limitation of I2C speed.
  • A big memory. Comes with 4MB, and can be upgraded to 16MB using the same memory chip that @Mr.Blinky used for the flash cart. This allow for more complex games, and also storing of games on the memory (there is a file system for ESP called SPIFFS that is a simplified version of SD CARD file system with only one flat directory, no subdirectory)
  • WIFI capable, opens up possibility for online games, posting of top scores from individual players to the web dashboard for competition, download and refresh of games directly from a web site, like that of an Android playstore.
  • Simpler wiring if you use the Node MCU D1 mini to make the board.
  • Cheaper overall cost.

Arduboy2 library for ESP8266 with push button supports I2C OLED and single pin sound

Thanks to hartmann1301 who created the Arduboy2 library based on the Arduboy2 library for the Slim boy version of Arduboy that runs on the Adruino Nano and I2C OLED dipslay. This ARduboy2 library for ESP8266 allow Arduboy games to be run on ESP8266 with a slower I2C SSD1306 OLED and an external button function for PS2 joysticks. refer to

However, I found that library not supporting push buttons for ESP8266 directly. The game need to be programmed with extra external functions to read the push buttons. This add extra efforts to port Arduboy games over to an ESP8266 Arduboy.

I modified that a bit to define the mapping of GPIO push buttons for ESP8266, and codes to read these buttons.
As ESP8266 has limited pins, so I have to use both the GPIO 0 and RX for A and B buttons.
Hence make sure you do not accidentally push these two buttons when you are flashing the firmware.
Otherwise, the flash may fail and you may need to redo the flash again.

Here is th elink to my github

As the ESP8266 already have 4MB memory, it should be able to hold many games on the go and self-flash it using a boot loader like what @Mr.Blinky did for the original Arduboy flash cartridge.
I know ESP8266 can be partitioned into two parts and self-flash over the air (OTA) to the second partition that is not actively running a program. Then switch over to boot and run from the second partition.
But my programming skill is not at that level yet. So, do not know how to do that.

Appreciate help from anyone who’s doing something similar.

Here are the list of the original Arduboy games that have been successfully ported to ESP8266 Arduboy/ The source code files modified for ESP8266_Arduboy can be found in the examples folder of this library with original licensing comments are kept in the modified source codes. Credits to the original creators of these Arduboy games.

TESTED on ESP8266 Arduboy

  • evade - no background music
  • ArduBOYING
  • ArduBreakout
  • breakout-v
  • Sirene
  • Mystic Balloon
  • PicoVaders (space invader)
  • Shadow Runner

Here are the pins used and wiring diagram. I am using a Node MCI D1 Mini on a bread board and then created a perf board version. Next, I I will try to build a tiny one using a mini-joystick (as small as button) and the bare ESP12E module. Programming will be done through a ESP_USB programmer.


*NODE MCU Mini D1 (ESP8266)

  • if you want to build a custom design board that is super small, you can use the ESP8266 12E module directly, and get a USB_to_ESP programmer board to program it.

  • The ESP8266 12E is a bare board and you need to tie certain pins to ground and other pins to VCC to make it run firmware, or put it in the a programming mode. Make the following permanent connections to put the ESP8266 12E at the normal firmware running mode. Then leave the rest to the USB_to_ESP programmer to flip the EN, Reset and GPIO 0 pins to the right level to put it at a firmware programming mode.

  • Connect the following pins to their own 1K resistors then to VCC (3.3V) :

  • D3 (GPIO 0)

  • Reset

  • EN (chip enable)

  • Connect the following pins to their own 1K resistors then to GND :

  • D8 (GPIO15)

*I2C SSD1306 OLED 128x64

*six push buttons

*extra push button for rest (for perf board version only)

*power on/off switch (or perf board version only)

*3.7V LIPO Battery

*Perf Board or breadboard


*Pins for buttons

*GPIO13 D7—— Rightbutton----- .GND

*GPIO12 D6—— Left button----- .GND

*GPIO14 D5—— UP button----- .GND

*GPIO2 D4—— Down button----- .GND

*GPIO0 D3—— A button----- .GND // ** WARNING ** DO NOT press this button when flashing firmware.

*GPIO3 RX—— B button----- .GND // ** WARNING ** DO NOT press this button when flashing firmware.

*A0 Paddle — connect to middle pin of 10K VR, connect left pin to VCC, right pin to Ground

*GPIO15 D8——Piezo Speaker/headphone–GND

*ESP8266 i2c SSD1306 Oled


*3.3V ------------VCC

*GND -------------GND

*GPIO5 D1 --------SCL

*GPIO4 D2—--------SDA

Simple Steps to convert Arduboy games to run on ESP8266 Arduboy.

  • change “#include arduboy.h” to “#include arduboy2.h”

  • add “BeepPin1 beep;”

  • add “sound() function”

  • comment to remove // #include <ArduboyTones.h>

  • comment to remove // ArduboyTones sound(;

  • change all “sound.tone” to “playTone”

  • some games use a function pointer arrary instead of a switch function to pass control to different part of the codes as the game state changes. In ATMEGA32U4 the memory address are 2 bytes (single word) long, in ESP8266, the memory addresses are 4 bytyes ( doube word) long, So you need to
    change all “pgm_read_word” to “pgm_read_dword”

  • add beep.begin() after arduboy.begin();

  • if EEPROM is used by the game to keep configs/high scores,

  • refer to the notes in my github on how to add the eeprom.update function to your eeprom library in the ESP8266 library for your adruino ide.

  • add EEPROM.begin(100) at setup() // 100 is just a rough max no. need to check the size

  • add EEPROM.commit() after the last EEPROM.put(), EEPORM.write() and EEPROM.update() of each blocks of code.


** remove any reference to the Arduboy audio library that require timers to play back ground musics.


So you’re recompiling the games completely? Can you juse run the CPU at a most slower clock rate to save power? Or just sleep. If you’re running that ast you should be able to sleep like most of the time.

Thanks for the suggestion.
Yes, I have to recompile the source code as I need to adjust each game to work with the ESP8266 Arduboy2 library.
The ESP8266 can either operate in 80Mhz or 160Mhz. I arleady choose the lower clock of 80Mhz.

1 Like

Looks like it has deep sleep, just need to find some of the less deep sleep modes and try them. Should be a way to get somewhat better battery life. I think that’s one reason the Arduboy lasts so long is we build sleep right into the core library that every one uses to write games.

Thanks. Just took some measurement. When a game is running it consumes around 90mA.

Here is some references I found in manufacturer’s specifications.

1 Like

You’d have to do calculations or measurements but I think you’d find that the amount the Arduboy saves by built in library sleeping, as an overall percentage, is minimal. It doesn’t affect the display power, which is a major draw. The Arduboy lasts so long simply because of the low power it uses in general.


Sharing my demo video of the smallest Adruboy I have made so far = 15x30x40mm. This is done using the ESP12E module, 1" OLED I2C, and a tiny directional switch. Powered by a 200maH LIPO battery. Will upgrade to a 400maH battery 3mm x 30x40mm so the game console can be run for 4 hours.

An external programmer and charger is required to reduce the footprint of the game board. The programmer is USB_ESP01 (those used to program a small ESP01S module). The charger is the one for LIPO Battery. Installed as daughter board plug into the programmer board.


Perhaps, but it certainly doesn’t hurt. :wink: Vs just wasting the juice. Whether 5 minutes or 50, extra battery power is nice.

Added paddle to the ESP8266 Arduboy to play games like Pong, breakout and Picovader.


switching wifi off will save battery power

I got an idea to save PINS for directional buttons by using the ADC on the ESP8266, so that these pins can be used for the SPI interface for the OLED SSD1306 to improve the display speed for games.
With a combination of resistors and buttons as voltage dividers, we can get different values from the ADC0 of ESP8266 that can be used to different which button or combination of two buttons have been pressed. That’s useful e.g. when you pressed the UP + Right button for playing Pacman type games.

I have done a proof of concept test and it works well. The minimum gap is 40+ so we can accurately determine the button pressed.
When no buttons are pressed and ADC is hanging in the air, it’s a value fluctuating between 8 to 14.
Hence we can also tell when no buttons are pressed.
Here is the circuit diagram and my testing results using a ESP8266 Node MCU D1 Mini and some resistors.

Anyone know of ways/sample codes to install a boot menu for ESP8266 to load different game firmware stored on the onboard SPI memory to the ESP8266 to run? i.e. similar to @Mr.Blinky’s flashcart bootloader ?

A proof of concept to use the A0 (Analog to Digital conversion pin) of the ESP8266 to sense all 6 buttons, and multiplex the A0 to sense the variable resistor of the paddle.
Multiplex is possible by connecting a diode from the voltage dividers from each buttons to A0 , Also, raising another pin (GPIO 5) to high voltage to supply the needed high VCC for the voltage divider.
At the same time the paddle (variable resistor 10K) is also connected in a similar way through a diode to A0. And another GPIO 4 will be raised to high , while GPIO5 is lowered to ground to allow the paddle value to be read.

See the demo video here

and the pin layout here


1 Like

Video unavailable
This video has been removed by the user

Thx. Fixed the video link above

1 Like

I created a perf board version of this ESP8266 game console with SPI display, and six buttons plus 1 paddle (sharing the same A0 port) sensed by the analog to digital input using multiplex method.
I ported some games to micropython to test the concept.
The I2C interface is 10 times slower than the SPI interface for the SSD1306 display when running in micropython with a menu and launcher.
I am going to fork the Arduboy2 library for this type of console.

See the demo video:

1 Like

Hi Cheungbx,
I’m building one of your esp8266 arduboy but I can’t compile. I get an error.

I’m just trying to compile the esp8266_Ardubreakout example. I installed the esp8266_ssd1306 and the brzo.

I get this and I have no idea what it means and what to do:

C:\XXXX\Arduino\libraries\Brzo_I2C\src\brzo_i2c.c: In function ‘brzo_i2c_write’:
C:\XXXX\Arduino\libraries\Brzo_I2C\src\brzo_i2c.c:72:2: error: cannot find a register in class ‘RL_REGS’ while reloading ‘asm’
72 | asm volatile (
| ^~~
C:\XXXX\Arduino\libraries\Brzo_I2C\src\brzo_i2c.c:72:2: error: ‘asm’ operand has impossible constraints
exit status 1

My only idea is that the different libraries may have get updated with time and ended up incompatible?


It seems I was already answering myself. The related libraries have changed.

I tried with matching “older” libraries and it works for the most part.

Now I guess I am sorry for unearthing this old post but maybe my auto-answer can help somebody.

1 Like

This is a very nice and cheap system:

Still could be cheaper with the Wemos D1 mini.

I noticed the compiling and flashing is annoyingly slower than the arduino. Anyone knows if it is normal?

1 Like