ESP32 S3 Linux - Docker builder

The initial version was a Dockerfile ported by Adafruit from the work of @jcmvbkbc. The current version uses the last version of the build scripts like a git submodule and it has some improvements on the DockerFile to support USB flashing.

Don't forget to star ⭐ this repository

Build

Please follow the next steps:

Download or clone this repo

git clone --recursive https://github.com/hpsaturn/esp32s3-linux.git && cd esp32s3-linux

Then build the docker image:

docker build --build-arg DOCKER_USER=$USER --build-arg DOCKER_USERID=$UID -t esp32linuxbase .

Copy settings sample:

cp settings.cfg.default settings.cfg

(Note: For the first build and install, leave the same settings than the default, without parameters)

Run the build script of your preference, for example:

docker run --rm -it --name esp32s3linux --user="$(id -u):$(id -g)" -v ./esp32-linux-build:/app --env-file settings.cfg --device=/dev/ttyACM0 esp32linuxbase ./rebuild-esp32s3-linux-wifi.sh

Keep in mind that you should change the --device to your USB device where is connected the ESP32S3. For a different script please check the directory esp32-linux-build. This step takes around ~35 minutes and needs ~20Gb.

After that you should have this message:

Flashing

Open a different terminal and enter to the running container:

docker exec -it -u root esp32s3linux bash

Change the docker USB device permissions:

chmod 666 /dev/ttyACM0

Return to the main terminal and perform the flashing. And that's it!

Please check the output, you should have the flashed of /etc partition at the end (only that in the first install), with a final message like this:

Written contents of file 'build-buildroot-esp32s3/images/etc.jffs2' at offset 0xb0000

Linux boot

For run it in a TTGO T7 S3 (LilyGO board), you should have a FTDI connection to the UART like is showed in the photos below. Some dev boards have a second USB-C for this, then you could omit that.

esp32s3linux.mp4

For the complete details of features and current restrictions, please review the official wiki.

WiFi settings

Only add your credentials on /etc/wpa_supplicant.conf using vi editor or from the command line, like this:

cat > /etc/wpa_supplicant.conf <<EOF
network={
        ssid="YOUR-SSID-HERE"
        psk="YOUR-SSID-PASSWORD-HERE"
}
EOF

then, reboot it and your able to connect to it via SSH.

Misc

Turning USB serial into the default console

echo -n 'earlycon=esp32s3acm,mmio32,0x60038000 console=ttyACM1 debug rw root=mtd:rootfs no_hash_pointers' > /etc/cmdline

Provisional GPIO handling

devmem 0x60004020 32 2 # (output enable for gpio1)
devmem 0x60004004 32 2 # (drive gpio1 high)

For other GPIO be careful the syntax and the addressing, for instance for the LilyGO TTGO T7S3 board and its LED, the GPIO is the IO17, then you should be pass the number in hexadecimal, like this:

devmem 0x60004020 32 0x20000 # (ouput enable for GPIO 17)
devmem 0x60004004 32 0x20000 # (set GPIO 17 high)

Also you can enable the LED on the startup in a simple inet.d service:

Complete guide of GPIO implementation here
More info in the technical document of the ESP32S3.

Updates

After the first build and flashing, you can keep the sources and working directories changing the settings.cfg file and repeating the steps from the step 4. Also don't forget update before, the git submodules like this:

git submodule update --init --recursive

Possible settings

Put y to enable some one or nothing to disable, like this:

# keep_toolchain=y	-- don't rebuild the toolchain, but rebuild everything else
# keep_rootfs=y		-- don't reconfigure or rebuild rootfs from scratch. Would still apply overlay changes
# keep_buildroot=y	-- don't redownload the buildroot, only git pull any updates into it
# keep_bootloader=y	-- don't redownload the bootloader, only rebuild it
# keep_etc=y		-- don't overwrite the /etc partition

For fast re-builds, fast updates and also keep your etc and its config files, for instance configure it like this:

keep_toolchain=y
keep_rootfs=y
keep_buildroot=y
keep_bootloader=y
keep_etc=y

Clean

For clean the working directories, please enter to esp32-linux-build and remove the build directory and rebuild with the settings with empty parameters.

TODO

Migrate to the last script version with build parameters
Freezing repositories to specific commit
Add provisioning stuff (etc partition)
Improve the flashing step. Fix issue #10

Credits

Main script and initial idea: @jcmvbkbc
Official Wiki
English/Spanish ESP32 Telegram group