{"id":13808323,"url":"https://github.com/hpsaturn/esp32s3-linux","last_synced_at":"2025-10-07T06:43:56.392Z","repository":{"id":190890821,"uuid":"683532627","full_name":"hpsaturn/esp32s3-linux","owner":"hpsaturn","description":"ESP32 S3 Linux - Docker builder ","archived":false,"fork":false,"pushed_at":"2025-04-05T08:38:16.000Z","size":723,"stargazers_count":59,"open_issues_count":0,"forks_count":7,"subscribers_count":6,"default_branch":"master","last_synced_at":"2025-06-06T09:39:28.827Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Dockerfile","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/hpsaturn.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":".github/FUNDING.yml","license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null},"funding":{"github":"hpsaturn","liberapay":"Hpsaturn","buy_me_a_coffee":"hpsaturn","patreon":"hpsaturn"}},"created_at":"2023-08-26T21:49:22.000Z","updated_at":"2025-05-22T20:52:23.000Z","dependencies_parsed_at":"2025-04-05T09:33:31.287Z","dependency_job_id":null,"html_url":"https://github.com/hpsaturn/esp32s3-linux","commit_stats":null,"previous_names":["hpsaturn/esp32s3-linux"],"tags_count":4,"template":false,"template_full_name":null,"purl":"pkg:github/hpsaturn/esp32s3-linux","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpsaturn%2Fesp32s3-linux","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpsaturn%2Fesp32s3-linux/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpsaturn%2Fesp32s3-linux/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpsaturn%2Fesp32s3-linux/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/hpsaturn","download_url":"https://codeload.github.com/hpsaturn/esp32s3-linux/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/hpsaturn%2Fesp32s3-linux/sbom","scorecard":null,"host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":278734434,"owners_count":26036404,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","status":"online","status_checked_at":"2025-10-07T02:00:06.786Z","response_time":59,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":[],"created_at":"2024-08-04T01:01:40.042Z","updated_at":"2025-10-07T06:43:56.376Z","avatar_url":"https://github.com/hpsaturn.png","language":"Dockerfile","readme":"\n# ESP32 S3 Linux - Docker builder\n\nThe initial version was a Dockerfile ported by Adafruit from the work of [@jcmvbkbc](http://wiki.osll.ru/doku.php/etc:users:jcmvbkbc:linux-xtensa:esp32s3). 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.\n\n\u003ctable\u003e\n\t\u003ctr\u003e\n\t\t\u003ctd\u003e\n\t\t\tDon't forget to star ⭐ this repository\n\t\t\u003c/td\u003e\n\t\u003c/tr\u003e\n\u003c/table\u003e\n\n## Build\n\nPlease follow the next steps:\n\n1. Download or clone this repo\n\n```bash\ngit clone --recursive https://github.com/hpsaturn/esp32s3-linux.git \u0026\u0026 cd esp32s3-linux\n```\n\n2. Then build the docker image:\n\n```bash\ndocker build --build-arg DOCKER_USER=$USER --build-arg DOCKER_USERID=$UID -t esp32linuxbase .\n```\n\n3. Copy settings sample:\n\n```bash\ncp settings.cfg.default settings.cfg\n```\n\n(**Note**: For the first build and install, leave the same settings than the default, without parameters)\n\n4. Run the build script of your preference, for example:\n\n```bash\ndocker 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\n```\n\nKeep 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.\n\nAfter that you should have this message:\n\n![ESP32S3 Linux finish build](screenshots/docker_build_before_flash.jpg)\n\n## Flashing\n\nPress the enter keys for upload the different partitions **And that's it!**\n\n![ESP32S3 Linux final flashing](screenshots/docker_flashing.jpg)\n\nPlease check the output, you should have the flashed of **/etc** partition at the end (only in the first install), with a final message like this:\n\n```bash\nWritten contents of file 'build-buildroot-esp32s3/images/etc.jffs2' at offset 0xb0000\n```\n\n---\n\n### Troubleshotting\n\nIf you have problems after step 4, with permissions on the serial device, please repeat this step and before to press the enter key, do the next steps:\n\n1. Open a different terminal and enter to the running container:\n\n```bash\ndocker exec -it -u root esp32s3linux bash\n```\n\n2. Change the docker USB device permissions:\n\n```bash\nchmod 666 /dev/ttyACM0 \n```\n\n3. Return to the main terminal and perform the flashing. \n\n# Linux boot\n\nFor 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.\n\n![ESP32 S3 TTGO T7](https://user-images.githubusercontent.com/423856/249864617-08cf71ac-8773-4c3b-b5a3-d8912b5b9c05.jpg)  \n\n\u003cvideo src=\"https://user-images.githubusercontent.com/423856/249861308-74ca4fc8-d0ab-4cc3-9166-cf66c65c70d8.mp4\" controls=\"controls\" style=\"max-width: 730px;\"\u003e\n\u003c/video\u003e\n\nFor the complete details of features and current restrictions, please review the official [wiki](http://wiki.osll.ru/doku.php/etc:users:jcmvbkbc:linux-xtensa:esp32s3).\n\n## WiFi settings\n\nOnly add your credentials on `/etc/wpa_supplicant.conf` using `vi` editor or from the command line, like this:\n\n```bash\ncat \u003e /etc/wpa_supplicant.conf \u003c\u003cEOF\nnetwork={\n        ssid=\"YOUR-SSID-HERE\"\n        psk=\"YOUR-SSID-PASSWORD-HERE\"\n}\nEOF\n```\n\nthen, reboot it and your able to connect to it via SSH.\n\n## Misc\n\n### Turning USB serial into the default console\n\n```bash\necho -n 'earlycon=esp32s3acm,mmio32,0x60038000 console=ttyACM1 debug rw root=mtd:rootfs no_hash_pointers' \u003e /etc/cmdline\n```\n\n### Provisional GPIO handling\n\n```bash\ndevmem 0x60004020 32 2 # (output enable for gpio1)\ndevmem 0x60004004 32 2 # (drive gpio1 high)\n```\n\nFor 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:\n\n```bash\ndevmem 0x60004020 32 0x20000 # (ouput enable for GPIO 17)\ndevmem 0x60004004 32 0x20000 # (set GPIO 17 high)\n```\n\nAlso you can enable the LED on the startup in a simple `inet.d` service:\n\n![GPIO working via devmem](screenshots/gpio_via_devmem.jpg)\n\nComplete guide of GPIO implementation [here](http://wiki.osll.ru/doku.php/etc:users:jcmvbkbc:linux-xtensa:esp32s3:gpio)  \nMore info in the [technical document](https://www.espressif.com/sites/default/files/documentation/esp32-s3_technical_reference_manual_en.pdf) of the ESP32S3.\n\n# Updates\n\nAfter 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:\n\n```bash\ngit submodule update --init --recursive\n```\n\n## Possible settings\n\nPut `y` to enable some one or nothing to disable, like this:\n\n```bash\n# keep_toolchain=y\t-- don't rebuild the toolchain, but rebuild everything else\n# keep_rootfs=y\t\t-- don't reconfigure or rebuild rootfs from scratch. Would still apply overlay changes\n# keep_buildroot=y\t-- don't redownload the buildroot, only git pull any updates into it\n# keep_bootloader=y\t-- don't redownload the bootloader, only rebuild it\n# keep_etc=y\t\t-- don't overwrite the /etc partition\n```\n\nFor fast re-builds, fast updates and also keep your **etc** and its config files, for instance configure it like this:\n\n```bash\nkeep_toolchain=y\nkeep_rootfs=y\nkeep_buildroot=y\nkeep_bootloader=y\nkeep_etc=y\n```\n\n## Clean\n\nFor clean the working directories, please enter to `esp32-linux-build` and remove the build directory and rebuild with the settings with empty parameters.\n\n# TODO\n\n- [x] Migrate to the last script version with build parameters\n- [x] Freezing repositories to specific commit\n- [x] Add provisioning stuff (etc partition)\n- [x] Improve the flashing step. Fix issue #10\n\n# Credits\n\nMain script and initial idea: [@jcmvbkbc](https://gist.github.com/jcmvbkbc/316e6da728021c8ff670a24e674a35e6)  \n[Official Wiki](http://wiki.osll.ru/doku.php/etc:users:jcmvbkbc:linux-xtensa:esp32s3)  \n[Build process explained](https://gojimmypi.github.io/ESP32-S3-Linux/)  \nEnglish/Spanish [ESP32 Telegram group](https://t.me/esp_es)  \n","funding_links":["https://github.com/sponsors/hpsaturn","https://liberapay.com/Hpsaturn","https://buymeacoffee.com/hpsaturn","https://patreon.com/hpsaturn"],"categories":["Development with Docker"],"sub_categories":["Development Environment"],"project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpsaturn%2Fesp32s3-linux","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fhpsaturn%2Fesp32s3-linux","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fhpsaturn%2Fesp32s3-linux/lists"}