This repository contains everything you need to compile, flash, and run a fully functional NOMMU Linux kernel on the ESP32-S3 microcontroller. It is based on the amazing port by jcmvbkbc.
- Linux Kernel 6.11 (NOMMU) running on Xtensa architecture
- Buildroot Environment: Extremely lightweight root filesystem
- Wi-Fi Connectivity: Full WPA2 support via
wpa_supplicantand the ESP-Hosted network adapter - Hardware Control: Includes full suite of I2C utilities (
i2cdetect,i2cget,i2cset) to interact directly with sensors - Scripting Ready: Includes
vi,awk,sed,wget,ping, and more - Persistent Storage: Configured with a dedicated JFFS2 partition for
/etc, meaning Wi-Fi passwords and startup scripts survive reboots
If you do not want to compile the kernel from scratch, you can download the latest pre-compiled binaries from the Releases tab of this repository. The release contains all necessary files:
bootloader.binpartition-table.binnetwork_adapter.binxipImagerootfs.cramfsetc.jffs2
To flash the downloaded binaries to your ESP32-S3, you will need the official esptool.py utility. Ensure your board is connected via USB.
pip install esptool
# Flash the binaries (Ensure you are in the directory containing the files)
esptool.py -p /dev/ttyACM0 -b 460800 --before default_reset --after hard_reset --chip esp32s3 write_flash \
0x0 bootloader.bin \
0x8000 partition-table.bin \
0x10000 network_adapter.bin \
0xb0000 etc.jffs2 \
0x120000 xipImage \
0x480000 rootfs.cramfs(Replace /dev/ttyACM0 with your actual serial port if on Windows or macOS, e.g., COM3)
Once flashed, the ESP32-S3 will immediately boot Linux. Connect to the serial console to access the terminal:
picocom -b 115200 /dev/ttyACM0Note: The terminal might appear blank upon connection. Press Enter to prompt the login screen. You can log in by typing root (no password required).
To connect to an open network:
echo 'network={' > /etc/wpa.conf
echo ' ssid="YOUR_NETWORK_NAME"' >> /etc/wpa.conf
echo ' key_mgmt=NONE' >> /etc/wpa.conf
echo '}' >> /etc/wpa.conf
killall wpa_supplicant
wpa_supplicant -B -i espsta0 -c /etc/wpa.conf
udhcpc -i espsta0(For WPA2 protected networks, replace key_mgmt=NONE with psk="YOUR_PASSWORD")
This repository includes a highly optimized GitHub Actions workflow (.github/workflows/build.yml) that automatically compiles the Linux kernel in the cloud, completely bypassing the massive disk space requirements needed on a local machine.
- Go to the Actions tab of this repository.
- Select Build ESP32-S3 Linux on the left.
- Click Run workflow.
The workflow uses a Docker container based on Ubuntu to securely compile the cross-compilation toolchain, Buildroot environment, ESP-Hosted firmware, and the kernel itself. The entire process takes approximately 45-60 minutes, after which a ZIP file containing the binaries will be available for download in the Artifacts section.
This project relies on the open-source Linux kernel and Buildroot environments and is licensed under the GNU General Public License v3.0. See the LICENSE file for details.