A full Linux-like interactive shell for the ESP32 Family — with WiFi, real persistent filesystem, DAC, touch, PWM, scripting, and a clean Python terminal.
KernelESP turns your ESP32 into a live interactive environment. A Python terminal on your PC talks to the ESP32 over Serial, giving you a shell to control GPIO, read sensors, manage a real SPIFFS filesystem, run scripts, scan WiFi, start a web server — all without recompiling.
Demo
- ESP32 development board (any variant — WROOM-32, S3, C3, etc.)
- Python 3.10+
- USB cable (data-capable)
- Arduino IDE 2.x with ESP32 board package installed
git clone https://github.com/chirrenthen/KernelESP.git
cd KernelESPmacOS / Linux:
python3 -m venv .venv
source .venv/bin/activate
pip install pyserialWindows:
python -m venv .venv
.venv\Scripts\activate.bat
pip install pyserial pyreadline3- Open
esp32.inoin Arduino IDE - Board:
ESP32 Dev Module(or your variant) - Partition Scheme:
Default 4MB with spiffs← important - Upload Speed:
115200or921600 - Select the correct Port and click Upload
Alternatively
- Visit FlashESP
- Login with an account
- Click on 'Flash to Device' upload the firmware directly from the web, no hassle
macOS / Linux:
source .venv/bin/activate
python terminal.pyWindows:
.venv\Scripts\activate.bat
python terminal.pyThe terminal auto-detects your ESP32's port and connects. If multiple ports are found you'll be prompted to choose.
!help Show terminal help
!clear Clear screen and redraw banner
!exit !q Quit
!ports List available serial ports
!connect [port] Connect (auto-detect if no port)
!disconnect Disconnect
!reconnect Reconnect
!ls List local workspace files
!edit <file> Create / edit a script in workspace
!upload <file> Upload file to ESP32 SPIFFS
!download <file> Download file from ESP32
!sync Upload all workspace files to ESP32
!macro List all macros
!macro <name> Run macro
!macro <name> = <cmd> Save macro
!macro <name> del Delete macro
!anim Matrix rain animation
All commands are sent live over Serial — no recompiling.
# GPIO
pinmode 2 output # Set pin mode: input / output / pullup / pulldown
write 2 HIGH # Digital write: HIGH LOW 1 0 on off
read # Read all digital pins
read 5 # Read specific pin
gpio 2 on # Quick GPIO control
gpio 2 toggle # Toggle pin state
# ADC (12-bit, 3.3V reference)
aread # Read all ADC channels with bar graph
aread A2 # Read specific ADC pin (A0=GPIO36 … A5=GPIO33)
# PWM (LEDC — any output pin)
pwm 16 128 # 50% duty on GPIO16, 5kHz default
pwm 16 200 1000 # 78% duty, 1kHz
pwm 16 200 1000 1 # Channel 1 explicitly
# DAC (GPIO25, GPIO26 only)
dac 25 128 # ~1.65V on GPIO25
dac 26 255 # 3.3V on GPIO26
# Touch sensing
touch # Read all 10 touch pins
touch 4 # Read GPIO4 (T0)
# Tone
tone 16 440 1000 # 440Hz square wave for 1000ms
notone 16 # Stopsensor # All ADC channels with bar graph
scope A0 100 # Oscilloscope — 100 samples from A0 (GPIO36)
scope 32 80 10 # GPIO32, 80 samples, 10ms between
monitor A0 500 10 # Live monitor every 500ms for 10swifi # Show current WiFi status
wifi scan # Scan for nearby networks
wifi connect MySSID mypass # Connect to WiFi
wifi disconnect # Disconnect
wifi ap MyAP mypassword # Create Soft Access Point
wifi ping 192.168.1.1 # TCP connectivity check
wifi http start # Start HTTP server on port 80
wifi http start 8080 # Start on custom port
wifi http stop # Stop HTTP server
wifi hostname myesp # Set mDNS hostname
wifi mac # Print MAC addressesls # List current directory
ls /home # List specific path
pwd # Print working directory
cd home # Change directory
cd .. # Go up
mkdir scripts # Create directory
touch notes.txt # Create empty file
writefile notes.txt hello # Write (overwrite) content
append notes.txt world # Append line to file
cat notes.txt # Read file
rm notes.txt # Delete file
rm scripts -r # Delete directory recursively
mv a.txt b.txt # Move / rename
cp a.txt backup.txt # Copy
df # Show SPIFFS usageSPIFFS on a 4MB flash gives you ~1.4 MB of usable storage. Files survive reboots.
# Inline multi-command scripts (semicolon-separated)
eval "gpio 2 on; delay 500; gpio 2 off"
# Loop a command N times (up to 1000)
for 10 "gpio 2 toggle; delay 200"
# Write a script to SPIFFS and run it
writefile /home/blink.sh "gpio 2 on;delay 300;gpio 2 off;delay 300"
run /home/blink.sh
# Delay
delay 1000 # Wait 1000msdisco 5 30 # LED light show on all output pins
morse 2 SOS # Morse code on GPIO2
wave # ASCII wave arthelp # Full command reference
sysinfo / neofetch # System info with ASCII art
uptime # Time since boot
dmesg # Kernel message log (last 12)
free # RAM and SPIFFS usage
df # Filesystem usage
reboot # Restart ESP32
whoami # Prints: root
uname # OS and platform info
clear # Clear screen and show logo
echo <text> # Print text# Save a macro
!macro blink = eval "for 10 \"gpio 2 toggle; delay 200\""
# Run it
!macro blink
# List all
!macro
# Delete
!macro blink delMacros are saved to ~/.kernelesp_macros.json and persist across sessions.
KernelESP creates a local workspace at ~/kernelesp_workspace/. Write scripts there and sync to ESP32:
# In the terminal
!edit blink.sh # Write your script
!upload blink.sh # Upload to ESP32 SPIFFS
# On the ESP32
run /blink.sh # Execute itNo port found
Ensure the USB cable supports data. On Linux: sudo usermod -aG dialout $USER then re-login.
Garbled / no output
Check baud rate is 115200 on both sides. Try !reconnect.
SPIFFS mount failed
Set Partition Scheme to Default 4MB with spiffs in Arduino IDE → Tools → Partition Scheme.
WiFi won't connect
ESP32 only supports 2.4GHz networks. Check SSID/password. Use wifi scan to verify the network is visible.
readline error on Windows
pip install pyreadline3Touch pins reading wrong
Do not use INPUT_PULLUP on touch pins. Leave them floating. Values below ~30 typically indicate a touch.
Pull requests welcome. Open an issue for bugs or feature requests.
I sincerely thank @PPPDUD and @Arc1011 — some of the command implementations in this project are based on their work in KernelUNO.
Built for the ESP32 community — KernelESP v1.0