DEV Community

Germán Alberto Gimenez Silva
Germán Alberto Gimenez Silva

Posted on • Originally published at rubystacknews.com on

A Definitive Guide to Running PicoRuby on ESP32 (ESP-IDF 5.x)

#esp32 #picoruby #programming #ruby

December 18, 2025

Running PicoRuby on an ESP32 is absolutely possible — but today it is not straightforward , and most guides omit critical details. This article consolidates everything that actually matters, based on real-world setup, debugging, and integration with ESP-IDF 5.5.

Article content

If you follow this guide exactly , you will end with:

  • PicoRuby running on an ESP32
  • A working serial shell
  • An interactive Ruby REPL (irb)
  • A correct partition layout
  • A reproducible, clean build

No guesswork. No hacks.


Advertise on RubyStackNews


RubyStackNews is a niche publication read by Ruby and Rails developers worldwide.
Our audience includes senior engineers, tech leads, and decision-makers from
the US, Europe, and Asia.

<h3>
  Sponsorship Options
</h3>


  <strong><img src="https://s0.wp.com/wp-content/mu-plugins/wpcom-smileys/twemoji/2/72x72/1f4dd.png" alt="📝"> Article Sponsorship</strong><br>
  Your brand featured inside a technical article (clearly marked as sponsored).<br>
  <span>USD 250 per article</span>



  <strong><img src="https://s0.wp.com/wp-content/mu-plugins/wpcom-smileys/twemoji/2/72x72/1f4cc.png" alt="📌"> Inline Sponsored Block</strong><br>
  Highlighted sponsor section embedded within an article.<br>
  <span>USD 100 per week</span>



  <strong><img src="https://s0.wp.com/wp-content/mu-plugins/wpcom-smileys/twemoji/2/72x72/1f4ce.png" alt="📎"> Sidebar Sponsor</strong><br>
  Logo + link displayed site-wide in the sidebar.<br>
  <span>USD 150 per month</span>
Enter fullscreen mode Exit fullscreen mode
  • Highly targeted Ruby / Rails audience
  • Organic traffic from search and developer communities
  • No ad networks — direct sponsorships only
<p>
  Interested in sponsoring RubyStackNews?
</p>
<a href="https://wa.me/5493434192620">
  Contact via WhatsApp
</a>
Enter fullscreen mode Exit fullscreen mode

1. Hardware and assumptions

This guide assumes:

  • ESP32 classic (ESP32-D0WD / ESP32-WROOM-32)
  • 4 MB flash (most common)
  • Linux (Debian/Ubuntu-based)
  • ESP-IDF v5.5.x

To confirm your chip:


esptool.py --port /dev/ttyUSB0 chip_id
Enter fullscreen mode Exit fullscreen mode

Expected output:


Chip is ESP32-D0WD (revision v0.0)
Enter fullscreen mode Exit fullscreen mode

2. Install ESP-IDF dependencies (Linux) 


sudo apt-get install -y \
  git wget flex bison gperf \
  python3 python3-pip python3-venv \
  cmake ninja-build ccache \
  libffi-dev libssl-dev \
  dfu-util libusb-1.0-0
Enter fullscreen mode Exit fullscreen mode

3. Clone and install ESP-IDF 


mkdir -p ~/esp32
cd ~/esp32

git clone -b v5.5.1 --recursive https://github.com/espressif/esp-idf.git
cd esp-idf
./install.sh esp32
Enter fullscreen mode Exit fullscreen mode

Article content

Export the environment (required in every new shell) 


. $HOME/esp32/esp-idf/export.sh
Enter fullscreen mode Exit fullscreen mode

Article content

4. Create a project 


cd ~/esp32
idf.py create-project hello_world
cd hello_world
Enter fullscreen mode Exit fullscreen mode

5. Add PicoRuby correctly (critical)

❌ What not to do

Do not add PicoRuby inside esp-idf/components. ESP-IDF is the SDK, not your application.

✅ Correct approach (canonical)

From the project root :


cd ~/esp32/hello_world
git init # if the project is not already a git repo

git submodule add https://github.com/picoruby/picoruby-esp32.git components/picoruby-esp32
git submodule update --init --recursive
Enter fullscreen mode Exit fullscreen mode

Mandatory verification 


ls components/picoruby-esp32/picoruby/include
Enter fullscreen mode Exit fullscreen mode

If this directory does not exist , the build will fail. This directory must exist — it is not optional.

6. Configure main/

Project structure 


hello_world/
├── main/
│ ├── CMakeLists.txt
│ └── hello_world_main.c
└── components/
    └── picoruby-esp32/
Enter fullscreen mode Exit fullscreen mode

main/CMakeLists.txt 


idf_component_register(
  SRCS "hello_world_main.c"
  REQUIRES picoruby-esp32
  PRIV_REQUIRES spi_flash
)
Enter fullscreen mode Exit fullscreen mode

hello_world_main.c 


#include "picoruby-esp32.h"

void app_main(void)
{
    picoruby_esp32();
}
Enter fullscreen mode Exit fullscreen mode

7. Set the correct target 


idf.py set-target esp32
Enter fullscreen mode Exit fullscreen mode

Important : set-target is always the chip , never the framework or library.

8. Fix the partition table (absolutely required)

PicoRuby + mruby does not fit in the default 1 MB app partition.

Open menuconfig:


idf.py menuconfig
Enter fullscreen mode Exit fullscreen mode

Navigate to:


Partition Table →
  Partition Table →
    Single factory app (large), no OTA
Enter fullscreen mode Exit fullscreen mode

This option is the ESP-IDF 5.x equivalent of “Huge App”.

Why this matters

  • App partition ≈ 2–3 MB
  • OTA disabled
  • Required for PicoRuby / MicroPython
  • Works perfectly on 4 MB flash ESP32

Save and exit.

9. Build 


rm -rf build
idf.py build
Enter fullscreen mode Exit fullscreen mode

If you see errors mentioning rake, install Ruby build tools:


sudo apt install -y ruby ruby-dev rake
Enter fullscreen mode Exit fullscreen mode

Then rebuild.

10. Flash and monitor

Article content


idf.py -p /dev/ttyUSB0 flash
idf.py -p /dev/ttyUSB0 monitor
Enter fullscreen mode Exit fullscreen mode

11. Understanding what you see (very important)

You will see a prompt like:


$>
Enter fullscreen mode Exit fullscreen mode

This is NOT Ruby.

This is the PicoRuby shell.

Enter the Ruby REPL 


$> irb
Enter fullscreen mode Exit fullscreen mode

Now you are in Ruby.

Example:


irb> puts "Hello from ESP32"
Hello from ESP32
=> nil

irb> 1 + 2
=> 3
Enter fullscreen mode Exit fullscreen mode

12. Mental model (this avoids confusion) 


ESP32 boot
   ↓
PicoRuby shell ($>)
   ↓
irb
   ↓
Ruby interactive REPL
Enter fullscreen mode Exit fullscreen mode

This is intentional design , not a bug.

13. What you have achieved

At this point you have:

  • ✅ ESP-IDF 5.5 running
  • ✅ PicoRuby integrated correctly
  • ✅ mruby built for Xtensa
  • ✅ Correct partition layout
  • ✅ Working serial shell
  • ✅ Interactive Ruby REPL on ESP32

This is not trivial , and most guides stop far earlier.

14. Where to go next

From here you can:

  • Embed Ruby scripts in mrblib/
  • Control GPIO, I2C, SPI from Ruby
  • Build a Ruby-driven firmware
  • Ship PicoRuby as a scripting layer
  • Document or productize your setup

Final notes

PicoRuby on ESP32 works well , but today it requires:

  • correct Git submodule handling
  • correct partition sizing
  • understanding that $> ≠ Ruby
  • explicit entry into irb

Once those are understood, the system is stable, powerful, and elegant.

Article content

Top comments (0)