esp-vim

Real Vim, running as the firmware of an ESP32 microcontroller. There is no Linux and no computer behind it: the chip boots straight into Vim 9.2, and Vim is the whole system. On a board with a screen and a keyboard it makes a pocket computer for writing, scripting and tinkering with hardware; on a bare board it runs over a serial terminal. See Hardware for the boards it targets.

Features

• Real Vim 9.2: windows, buffers, registers, macros, Vim script, :vimgrep, diff, syntax highlighting and indenting for 30 file types, spell checking
• Its own screen and keyboard: runs on the board's display with a built-in, USB or Bluetooth (BLE) keyboard and touch, or on any serial terminal
• Files everywhere: flash, SD card, and remote machines over SCP and SFTP, in :EspFiles, a two-pane file manager in the style of Midnight Commander
• File transfer: SCP, SFTP, HTTP(S) downloads, and USB mass storage
• Web interface: a password-protected browser page for files and settings, with a live view of what's being edited
• MicroPython: run scripts from the editor and script Vim itself in Python
• Git: init, commit, diff, log, clone, fetch and push, from inside Vim
• Hardware from the editor: WiFi, Bluetooth, GPIO, ADC, I²C, sensors, serial ports, persistent settings, memory and tasks, as :Esp commands and functions
• Built to be the whole system: :q restarts Vim in place, a spinner shows when it's busy, and :help covers the device
• ESP32-P4 and ESP32-S3 builds

Development status: see the phase table in docs/PLAN.md.

Editing a Python script on the device, with :EspInfo open below.

How you use it

Seeing it. On a board with a display, Vim draws directly on it, through a terminal emulator that runs on the chip. On any board it can also draw on a serial terminal: the chip's console UART carries Vim's screen, and a terminal program on your computer displays it, like logging in to a remote machine.

Typing. Use the board's own keyboard if it has one, a USB keyboard, a Bluetooth keyboard paired with :EspBtKeyboard (BLE keyboards only: neither chip has Bluetooth Classic), or touch (tap to move the cursor, drag to scroll). On a touch screen with no keyboard attached, a pairing screen appears by itself, so a Bluetooth keyboard can be paired with taps alone. Every function-key command also has a letter, for keyboards without F-keys. Over serial, keys typed in your terminal go down the line to Vim, mouse included. Everything works as in desktop Vim, including arrows, Backspace and CTRL-C.

Files. Your files live in flash at /fat and on the SD card at /sd, and survive reboots. :e, :w and <Tab> completion work as usual, and scp:// and sftp:// paths reach other machines. :EspFiles puts two directories side by side, local or remote, for copying, moving and deleting:

To move files without the editor, plug the board into a computer over USB (it appears as a drive), or start the web interface with :EspWebStart and use a browser.

Programming it. There are two languages. Vim script, with the hardware reachable through esp_*() functions:

:EspWifiScan                   " nearby networks, in a window
:EspGpio 21 on                 " drive GPIO 21 high
:EspNvs app greeting hello     " store a setting that survives reboots
:echo esp_info().chip          " ESP32-P4

" blink GPIO 21 five times
for i in range(10)
  call esp_gpio_write(21, i % 2)
  sleep 500m
endfor

and MicroPython, which runs scripts (:EspPyRun runs the current buffer) and can drive the editor through a vim module and the hardware through an esp module:

# Light an LED while the current buffer has TODOs in it
import esp, vim

todos = [n for n, line in enumerate(vim.current.buffer, 1) if "TODO" in line]
esp.gpio_write(21, 1 if todos else 0)
vim.command(f"echo '{len(todos)} TODOs'")

There is no operating-system shell, so :!cmd and :terminal don't exist. The :Esp commands and MicroPython take their place.

Version control. :EspGitInit, :EspGitCommit, :EspGitDiff, :EspGitPush, :EspGitClone and friends keep a real git repository in /fat or /sd. It's compatible with git on your computer, and pushes and fetches over HTTPS or SSH.

Help. :help opens a guide to the device: what's different from desktop Vim, the :Esp commands, keys, storage and settings. :q doesn't leave you at a dead device: Vim restarts in place.

What it needs

Flash is laid out for 16 MB: 7 MB for the firmware (2.2 MB today, with room for the networking, MicroPython and git parts), 3 MB for Vim's runtime files (2.2 MB used: syntax, help, plugins), about 5.5 MB for your files at /fat, and 64 KB for settings. An SD card adds storage at /sd.

PSRAM is required. Vim's memory lives there, because the chip's internal RAM (a few hundred KB at most) isn't enough. Vim uses about 0.5 MB editing a typical file and peaked near 2.7 MB in the test suite with help and syntax highlighting loaded. It's allowed up to half of the free PSRAM (at most 16 MB), leaving the rest for everything else.

Hardware

Targeted boards:

• CYD boards: only the ESP32-S3 variants with 16 MB flash and 8 MB PSRAM (the module is marked N16R8) can run this. The original CYD, the ESP32-2432S028, uses a classic ESP32 with 4 MB flash and no PSRAM, which isn't enough. S3 CYDs differ in panel (SPI or parallel RGB, various sizes) and touch controller, so each one needs a small board definition.
• ESP32-S3 PSRAM: N16R8 modules have octal PSRAM, which is the default here. For quad PSRAM, set CONFIG_SPIRAM_MODE_QUAD in esp-vim/sdkconfig.defaults.esp32s3.

Tested so far: the ESP32-P4 and ESP32-S3 chips in Espressif's emulator, over a serial terminal. No physical board yet. Progress is in the plan.

Try it in the emulator

You need Linux x86-64, pixi and Git LFS.

git clone https://github.com/omwah/esp-vim.git && cd esp-vim
git lfs pull              # the vendored Vim source and emulator archives
pixi install              # host tools
pixi run deps             # extract and patch upstream into build-deps/

Then install ESP-IDF v5.5.5 outside the repo, from inside the pixi environment so ESP-IDF builds its own Python environment against pixi's Python:

git clone -b v5.5.5 --depth 1 --recurse-submodules --shallow-submodules \
    https://github.com/espressif/esp-idf.git ~/esp/esp-idf
pixi run -- bash -c 'cd ~/esp/esp-idf && ./install.sh esp32p4'
pixi run -- bash -c 'cd ~/esp/esp-idf && \
    python tools/idf_tools.py install cmake ninja'   # not installed by default on Linux
pixi run env-check        # should report ESP-IDF v5.5.5 and riscv32-esp-elf 14.2.0

Build the firmware, start it in the emulator, and attach a terminal:

pixi run vim-build
pixi run emu esp-vim -- --uart-tcp 127.0.0.1:5555   # terminal 1: the "device"
pixi run emu-tty                                    # terminal 2: your screen and keyboard

Detach with Ctrl-]. pixi run vim-test runs the full regression suite in the emulator: edits across reboots, the interactive console, :help, the :Esp commands and the file manager.

Put it on a board

Build as above, connect the board over USB, and flash it with ESP-IDF (the port may differ):

pixi run vim-build-tab5       # M5Stack Tab5;  pixi run vim-build-s3 for ESP32-S3
pixi run -- bash -c '. scripts/env.sh && idf.py -C esp-vim -B esp-vim/build-tab5 -p /dev/ttyACM0 flash'

For an ESP32-S3 board, use build-esp32s3; for the Hosyond ES3C28P, whose only USB port is the S3's own, pixi run vim-build-es3c28p and build-es3c28p, which put the console on that port; for the Freenove FNK0115Q, pixi run vim-build-fnk0115 and build-fnk0115 (its console is UART0, through the board's USB-serial bridge). Attach a terminal to the board's serial port with, for example, pixi run -- socat -,raw,echo=0,escape=0x1d /dev/ttyACM0,raw,echo=0 (detach with Ctrl-]). The Tab5's WiFi comes from its ESP32-C6 running Espressif's esp-hosted firmware; pixi run c6-build builds that firmware at the version this build speaks, for when the C6 needs updating. (Plain vim-build is the P4 with Ethernet, which is what the emulator models.)

For developers

Tasks

Everything runs through pixi, so the incantations live in the repo rather than in someone's shell history. pixi task list shows them all.

Extra arguments pass through after --:

pixi run emu esp-vim/test/spike -- --gdb 1234 --gdb-halt

emu-tty uses socat, not nc — nc cannot put the terminal in raw mode, so arrow keys arrive as literal escape sequences and echo doubles. Detach with Ctrl-].

Help on the device

:help on the device opens a device-specific guide: an amended version of Vim's help.txt covering storage, filetypes, keys, settings and what isn't available. Edit it in esp-vim/runtime-image/doc/help.txt.in. The build generates the tags and rejects broken links.

Choosing which filetypes the device supports

Edit esp-vim/filetypes.conf: one line per filetype, followed by its file patterns. It generates the device's filetype.vim and decides which syntax, ftplugin and indent files are shipped. Then run pixi run vim-build. Types not listed there aren't detected at all. To add one on a running device without reflashing, use a standard Vim ftdetect/ script in /fat/.vim/ftdetect/.

Why the host tools are pinned

pixi.toml pins four host tools, each for a specific reason:

• ncurses — Vim's ./configure refuses to finish without a terminal library, even though the ESP build deliberately runs with HAVE_TGETENT undefined and uses Vim's builtin termcaps. We only need configure to complete so it emits a config.h to curate.
• socat — raw-mode terminal for interactive sessions over the emulated UART.
• openssh — a local sshd and bare repo to test SCP/SFTP and git push (Phase 8).
• python 3.13 — ESP-IDF builds its own venv with python -m venv, which needs ensurepip. The system Python has none, so IDF's bootstrap fails against it.

Pinning them here keeps a fresh clone reproducible and needs no root, which apt would.

How third-party source is handled

Upstream source is never committed as files. Each dependency is a Git LFS archive in third_party/ plus a patch series in patches/<dep>/, extracted and applied into the git-ignored build-deps/ at build time. This keeps the repository reviewable, makes our changes to upstream explicit, and makes re-syncing to a newer Vim a bounded job.

third_party/manifest.txt records each archive's provenance and sha256. Note the sha256 attests the blob we vendored, not an upstream-published digest — see the manifest header for why that distinction is necessary.

To change upstream source: see Patch authoring in docs/DECISIONS.md.

Layout

Documentation

• docs/PLAN.md: the living plan, phase by phase, with status
• docs/DECISIONS.md: why things are the way they are
• Phase write-ups: 1 capability spike · 2 Vim compiles · 3 Vim runs · 4 curated runtime and memory · 5 interactive over UART, restart, S3 · 6 :Esp commands and file manager

License

This project's own code, scripts and documentation are licensed under the Apache License 2.0.

Third-party components keep their own licenses: