docs

.github/scripts/sketch_utils.sh

@@ -54,6 +54,8 @@ function check_requirements { # check_requirements <sketchdir> <sdkconfig_path>
 }
 
 function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [extra-options]
+    local first_only=false
+
     while [ -n "$1" ]; do
         case "$1" in
         -ai )
@@ -92,6 +94,36 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
             shift
             debug_level="DebugLevel=$1"
             ;;
+        -b )
+            shift
+            custom_build_dir=$1
+            ;;
+        --first-only )
+            first_only=true
+            ;;
+        -h )
+            echo "Usage: build_sketch [options]"
+            echo ""
+            echo "Build an Arduino sketch for ESP32 targets."
+            echo ""
+            echo "Required options:"
+            echo "  -ai <path>          Arduino IDE path"
+            echo "  -au <path>          Arduino user path"
+            echo "  -s <path>           Sketch directory containing .ino file and ci.yml"
+            echo "  -t <target>         Target chip (esp32, esp32s2, esp32c3, esp32s3, esp32c6, esp32h2, esp32p4, esp32c5)"
+            echo "                      Required unless -fqbn is specified"
+            echo ""
+            echo "Optional options:"
+            echo "  -fqbn <fqbn>        Fully qualified board name (alternative to -t)"
+            echo "  -o <options>        Board options (PSRAM, USBMode, etc.) [default: chip-specific]"
+            echo "  -i <index>          Chunk index for parallel builds [default: none]"
+            echo "  -l <file>           Log compilation output to JSON file [default: none]"
+            echo "  -d <level>          Debug level (DebugLevel=...) [default: none]"
+            echo "  -b <path>           Custom build directory [default: \$ARDUINO_BUILD_DIR or \$HOME/.arduino/tests/\$target/\$sketchname/build.tmp]"
+            echo "  --first-only        Build only the first FQBN from ci.yml configurations [default: false]"
+            echo "  -h                  Show this help message"
+            exit 0
+            ;;
         * )
             break
             ;;
@@ -128,7 +160,15 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
 
             len=$(yq eval ".fqbn.${target} | length" "$sketchdir"/ci.yml 2>/dev/null || echo 0)
             if [ "$len" -gt 0 ]; then
-                fqbn=$(yq eval ".fqbn.${target} | sort | @json" "$sketchdir"/ci.yml)
+                if [ "$first_only" = true ]; then
+                    # Get only the first FQBN from the array (original order)
+                    fqbn=$(yq eval ".fqbn.${target} | .[0]" "$sketchdir"/ci.yml 2>/dev/null)
+                    fqbn="[\"$fqbn\"]"
+                    len=1
+                else
+                    # Build all FQBNs
+                    fqbn=$(yq eval ".fqbn.${target} | sort | @json" "$sketchdir"/ci.yml)
+                fi
             fi
         fi
 
@@ -219,12 +259,14 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
     fi
 
     # The directory that will hold all the artifacts (the build directory) is
-    # provided through:
-    #  1. An env variable called ARDUINO_BUILD_DIR.
-    #  2. Created at the sketch level as "build" in the case of a single
-    #     configuration test.
-    #  3. Created at the sketch level as "buildX" where X is the number
-    #     of configuration built in case of a multiconfiguration test.
+    # determined by the following priority:
+    #  1. Custom build directory via -b flag:
+    #     - If path contains "docs/_static/binaries", use as exact path (for docs builds)
+    #     - Otherwise, append target name to custom directory
+    #  2. ARDUINO_BUILD_DIR environment variable (if set)
+    #  3. Default: $HOME/.arduino/tests/$target/$sketchname/build.tmp
+    #
+    # For multiple configurations, subsequent builds use .1, .2, etc. suffixes
 
     sketchname=$(basename "$sketchdir")
     local has_requirements
@@ -253,22 +295,34 @@ function build_sketch { # build_sketch <ide_path> <user_path> <path-to-ino> [ext
     fi
 
     ARDUINO_CACHE_DIR="$HOME/.arduino/cache.tmp"
-    if [ -n "$ARDUINO_BUILD_DIR" ]; then
-        build_dir="$ARDUINO_BUILD_DIR"
-    elif [ "$len" -eq 1 ]; then
-        # build_dir="$sketchdir/build"
-        build_dir="$HOME/.arduino/tests/$target/$sketchname/build.tmp"
+
+    # Determine base build directory
+    if [ -n "$custom_build_dir" ]; then
+        # If custom_build_dir contains docs/_static/binaries, use it as exact path
+        if [[ "$custom_build_dir" == *"docs/_static/binaries"* ]]; then
+            build_dir_base="$custom_build_dir"
+        else
+            build_dir_base="$custom_build_dir/$target"
+        fi
+    elif [ -n "$ARDUINO_BUILD_DIR" ]; then
+        build_dir_base="$ARDUINO_BUILD_DIR"
+    else
+        build_dir_base="$HOME/.arduino/tests/$target/$sketchname/build.tmp"
     fi
 
     output_file="$HOME/.arduino/cli_compile_output.txt"
     sizes_file="$GITHUB_WORKSPACE/cli_compile_$chunk_index.json"
 
     mkdir -p "$ARDUINO_CACHE_DIR"
     for i in $(seq 0 $((len - 1))); do
-        if [ "$len" -ne 1 ]; then
-            # build_dir="$sketchdir/build$i"
-            build_dir="$HOME/.arduino/tests/$target/$sketchname/build$i.tmp"
+        # Calculate build directory for this configuration
+        if [ "$i" -eq 0 ]; then
+            build_dir="$build_dir_base"
+        else
+            build_dir="${build_dir_base}.${i}"
         fi
+
+        # Prepare build directory
         rm -rf "$build_dir"
         mkdir -p "$build_dir"
 

.github/workflows/docs_build.yml

@@ -5,6 +5,7 @@ on:
     branches:
       - master
       - release/v2.x
+      - docs-embed
     paths:
       - "docs/**"
       - ".github/workflows/docs_build.yml"
@@ -34,18 +35,55 @@ jobs:
           cache: "pip"
           python-version: "3.10"
 
-      - name: Build
+          # Install Arduino CLI and set environment variables
+      - name: Install Arduino CLI
+        run: |
+          source .github/scripts/install-arduino-cli.sh
+          echo "ARDUINO_IDE_PATH=$ARDUINO_IDE_PATH" >> $GITHUB_ENV
+          echo "ARDUINO_USR_PATH=$ARDUINO_USR_PATH" >> $GITHUB_ENV
+
+      # Install ESP32 Arduino Core
+      - name: Install ESP32 Arduino Core
+        run: |
+          source .github/scripts/install-arduino-core-esp32.sh
+
+      # Install Python dependencies needed for docs_build_examples.py
+      - name: Install Python Dependencies
         run: |
           sudo apt update
           sudo apt install python3-pip python3-setuptools
-          # GitHub CI installs pip3 and setuptools outside the path.
-          # Update the path to include them and run.
           cd ./docs
           PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary
+
+      # Set documentation embedding environment variables
+      - name: Set Documentation Environment Variables
+        run: |
+          # configure env vars for docs_build_examples.py and docs build
+          echo "DOCS_EMBED_GITHUB_BASE_URL=https://github.com/${{ github.repository }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_GITHUB_BRANCH=${{ github.ref_name }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_PUBLIC_ROOT=https://${{ secrets.DOCS_SERVER }}/${{ secrets.DOCS_PATH }}/en/${{ github.ref_name == 'master' && 'latest' || github.ref_name }}/" >> $GITHUB_ENV
+          echo "DOCS_EMBED_BINARIES_DIR=${{ vars.DOCS_EMBED_BINARIES_DIR }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_LAUNCHPAD_URL=${{ vars.DOCS_EMBED_LAUNCHPAD_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_WOKWI_VIEWER_URL=${{ vars.DOCS_EMBED_WOKWI_VIEWER_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_ABOUT_WOKWI_URL=${{ vars.DOCS_EMBED_ABOUT_WOKWI_URL }}" >> $GITHUB_ENV
+
+      # Build examples using environment variables from install script
+      - name: Build Examples
+        run: |
+          PATH=/home/runner/.local/bin:$PATH python3 .github/scripts/docs_build_examples.py --build --diagram --launchpad
+
+      - name: Cleanup Binaries
+        run: |
+          PATH=/home/runner/.local/bin:$PATH python3 .github/scripts/docs_build_examples.py -c
+
+
+      - name: Build
+        run: |
+          cd ./docs
           PATH=/home/runner/.local/bin:$PATH SPHINXOPTS="-W" build-docs -l en
 
       - name: Archive Docs
         uses: actions/upload-artifact@ea165f8d65b6e75b540449e92b4886f43607fa02 # v4.6.2
         with:
           name: docs
-          path: docs
+          path: docs

.github/workflows/docs_deploy.yml

@@ -1,6 +1,7 @@
 name: Documentation Build and Production Deploy CI
 
 on:
+  workflow_dispatch:
   workflow_run:
     workflows: ["ESP32 Arduino Release"]
     types:
@@ -9,6 +10,7 @@ on:
     branches:
       - release/v2.x
       - master
+      - docs-embed
     paths:
       - "docs/**"
       - ".github/workflows/docs_deploy.yml"
@@ -19,7 +21,7 @@ permissions:
 jobs:
   deploy-prod-docs:
     name: Deploy Documentation on Production
-    if: github.repository == 'espressif/arduino-esp32'
+    # if: github.repository == 'espressif/arduino-esp32'
     runs-on: ubuntu-22.04
     defaults:
       run:
@@ -41,6 +43,47 @@ jobs:
           cache: "pip"
           python-version: "3.10"
 
+          # Install Arduino CLI and set environment variables
+      - name: Install Arduino CLI
+        run: |
+          source .github/scripts/install-arduino-cli.sh
+          echo "ARDUINO_IDE_PATH=$ARDUINO_IDE_PATH" >> $GITHUB_ENV
+          echo "ARDUINO_USR_PATH=$ARDUINO_USR_PATH" >> $GITHUB_ENV
+
+      # Install ESP32 Arduino Core
+      - name: Install ESP32 Arduino Core
+        run: |
+          source .github/scripts/install-arduino-core-esp32.sh
+
+      # Install Python dependencies needed for docs_build_examples.py
+      - name: Install Python Dependencies
+        run: |
+          sudo apt update
+          sudo apt install python3-pip python3-setuptools
+          cd ./docs
+          PATH=/home/runner/.local/bin:$PATH pip3 install -r requirements.txt --prefer-binary
+
+      # Set documentation embedding environment variables
+      - name: Set Documentation Environment Variables
+        run: |
+          # configure env vars for docs_build_examples.py and docs deployment
+          echo "DOCS_EMBED_GITHUB_BASE_URL=https://github.com/${{ github.repository }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_GITHUB_BRANCH=${{ github.ref_name }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_PUBLIC_ROOT=https://${{ secrets.DOCS_SERVER }}/${{ secrets.DOCS_PATH }}/en/${{ github.ref_name == 'master' && 'latest' || github.ref_name }}/" >> $GITHUB_ENV
+          echo "DOCS_EMBED_BINARIES_DIR=${{ vars.DOCS_EMBED_BINARIES_DIR }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_LAUNCHPAD_URL=${{ vars.DOCS_EMBED_LAUNCHPAD_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_WOKWI_VIEWER_URL=${{ vars.DOCS_EMBED_WOKWI_VIEWER_URL }}" >> $GITHUB_ENV
+          echo "DOCS_EMBED_ABOUT_WOKWI_URL=${{ vars.DOCS_EMBED_ABOUT_WOKWI_URL }}" >> $GITHUB_ENV
+
+      # Build examples using environment variables from install script
+      - name: Build Examples
+        run: |
+          PATH=/home/runner/.local/bin:$PATH python3 .github/scripts/docs_build_examples.py --build --diagram --launchpad
+
+      - name: Cleanup Binaries
+        run: |
+          PATH=/home/runner/.local/bin:$PATH python3 .github/scripts/docs_build_examples.py -c
+
       - name: Deploy Documentation
         env:
           # Deploy to production server

.gitignore

@@ -62,3 +62,7 @@ libraries/Insights/examples/*/*.ino.zip
 /affected_sketches.txt
 /affected_examples.txt
 /ctags_*
+
+# Disallow Wokwi diagram files except for diagram in tests folder
+**/diagram.*.json
+!tests/**/diagram.*.json

docs/conf_common.py

@@ -38,6 +38,7 @@
     "sphinx_tabs.tabs",
     "sphinx_substitution_extensions",  # For allowing substitutions inside code blocks
     "esp_docs.esp_extensions.dummy_build_system",
+    "esp_docs.esp_extensions.docs_embed",
 ]
 
 # ESP32_DOCS = [

docs/en/api/adc.rst

@@ -274,8 +274,7 @@ Example Applications
 
 Here is an example of how to use the ADC in OneShot mode or you can run Arduino example 01.Basics -> AnalogReadSerial.
 
-.. literalinclude:: ../../../libraries/ESP32/examples/AnalogRead/AnalogRead.ino
-    :language: arduino
+.. wokwi-example:: libraries/ESP32/examples/AnalogRead
 
 Here is an example of how to use the ADC in Continuous mode.
 

docs/en/api/gpio.rst

@@ -141,30 +141,12 @@ Example Code
 GPIO Input and Output Modes
 ***************************
 
-.. code-block:: arduino
-
-  #define LED    12
-  #define BUTTON 2
-
-  uint8_t stateLED = 0;
-
-    void setup() {
-        pinMode(LED, OUTPUT);
-        pinMode(BUTTON,INPUT_PULLUP);
-    }
-
-    void loop() {
-
-       if(!digitalRead(BUTTON)){
-         stateLED = stateLED^1;
-        digitalWrite(LED,stateLED);
-      }
-    }
+.. wokwi-example:: libraries/ESP32/examples/GPIO/Blink
 
 GPIO Interrupt
 **************
 
-.. literalinclude:: ../../../libraries/ESP32/examples/GPIO/GPIOInterrupt/GPIOInterrupt.ino
-    :language: arduino
+.. wokwi-example:: libraries/ESP32/examples/GPIO/GPIOInterrupt
+
 
 .. _datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf

docs/en/api/i2c.rst

@@ -509,3 +509,15 @@ Here is an example of how to use the I2C in Slave Mode.
     :language: arduino
 
 .. _Arduino Wire Library: https://www.arduino.cc/en/reference/wire
+
+
+External libraries - examples
+*****************************
+
+
+LiquidCrystal_I2C
+^^^^^^^^^^^^^^^^^
+
+This example demonstrates how to use the `LiquidCrystal_I2C`_ library to control an LCD display via I2C.
+
+.. wokwi-example:: libraries/Wire/examples/LiquidCrystal_I2C

docs/en/api/timer.rst

@@ -215,10 +215,8 @@ There are 2 examples uses of Timer:
 
 Repeat timer example:
 
-.. literalinclude:: ../../../libraries/ESP32/examples/Timer/RepeatTimer/RepeatTimer.ino
-    :language: arduino
+.. wokwi-example:: libraries/ESP32/examples/Timer/RepeatTimer
 
 Watchdog timer example:
 
-.. literalinclude:: ../../../libraries/ESP32/examples/Timer/WatchdogTimer/WatchdogTimer.ino
-    :language: arduino
+.. wokwi-example:: libraries/ESP32/examples/Timer/WatchdogTimer

docs/en/conf.py

@@ -31,3 +31,10 @@
 
 # Tracking ID for Google Analytics
 google_analytics_id = "G-F58JM78930"
+
+# Documentation embedding settings
+# docs_embed_public_root = "https://docs.espressif.com/projects/arduino-esp32-wokwi-test"
+# docs_embed_esp32_relative_root = "../.."
+# docs_embed_launchpad_url = "https://espressif.github.io/esp-launchpad/"
+# docs_embed_github_base_url = "https://github.com/JakubAndrysek/arduino-esp32"
+# docs_embed_github_branch = "docs-embed"

docs/en/contributing.rst

@@ -424,6 +424,9 @@ The ``ci.yml`` file is used to specify how the test suite and sketches will hand
   Libraries are installed using the ``arduino-cli lib install`` command, so you can specify libraries by name + version (e.g., ``[email protected]``)
   or by URL (e.g., ``https://github.com/arduino-libraries/WiFi101.git``).
   More information can be found in the `Arduino CLI documentation <https://arduino.github.io/arduino-cli/1.3/commands/arduino-cli_lib_install/>`_.
+* ``upload-binary``: This directive is used ESP-DOCS - Docs Embed to integrate Wokwi simulations into the documentation.
+  Together with custom Sphinx plugin and its directives, it allows embedding Wokwi simulator into the documentation pages with pre-compiled binaries.
+  For more information, please refer to the `ESP-DOCS - Docs Embed contributing guide <https://docs.espressif.com/projects/esp-docs/en/latest/writing-documentation/docs-embed.html>`_.
 
 The ``wifi`` test suite is a good example of how to use the ``ci.yml`` file:
 

docs/requirements.txt

@@ -1,7 +1,9 @@
-sphinx==4.5.0
-esp-docs>=1.4.0
+sphinx~=7.1.2
+
+esp-docs @ git+https://github.com/JakubAndrysek/esp-docs.git@extensions/wokwi_embed
+
 sphinx-copybutton==0.5.0
-sphinx-tabs==3.2.0
+sphinx-tabs==3.4.7
 numpydoc==1.5.0
 standard-imghdr==3.13.0
 Sphinx-Substitution-Extensions==2022.2.16