From 857935c31442fa0d37a790edd09241e3d076d790 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Fri, 29 Nov 2024 19:10:56 -0300 Subject: [PATCH 1/7] feat(support): toll and ci changes --- .github/ISSUE_TEMPLATE/Issue-report.yml | 2 +- .github/scripts/install-platformio-esp32.sh | 170 ------------- .github/scripts/on-push.sh | 81 +++---- .github/scripts/on-release.sh | 1 - .github/scripts/set_push_chunks.sh | 1 - .github/workflows/push.yml | 30 --- platform.txt | 1 - tools/platformio-build.py | 251 -------------------- 8 files changed, 30 insertions(+), 507 deletions(-) delete mode 100755 .github/scripts/install-platformio-esp32.sh delete mode 100644 tools/platformio-build.py diff --git a/.github/ISSUE_TEMPLATE/Issue-report.yml b/.github/ISSUE_TEMPLATE/Issue-report.yml index d5b756085c7..acbd9a3c29a 100644 --- a/.github/ISSUE_TEMPLATE/Issue-report.yml +++ b/.github/ISSUE_TEMPLATE/Issue-report.yml @@ -75,7 +75,7 @@ body: attributes: label: IDE Name description: What IDE are you using? - placeholder: eg. Arduino IDE, PlatformIO, Sloeber... + placeholder: eg. Arduino IDE, VSCode, Sloeber... validations: required: true - type: input diff --git a/.github/scripts/install-platformio-esp32.sh b/.github/scripts/install-platformio-esp32.sh deleted file mode 100755 index 80c668bdc0e..00000000000 --- a/.github/scripts/install-platformio-esp32.sh +++ /dev/null @@ -1,170 +0,0 @@ -#!/bin/bash - -export PLATFORMIO_ESP32_PATH="$HOME/.platformio/packages/framework-arduinoespressif32" -PLATFORMIO_ESP32_URL="https://github.com/platformio/platform-espressif32.git" - -TOOLCHAIN_VERSION="12.2.0+20230208" -ESPTOOLPY_VERSION="~1.40501.0" -ESPRESSIF_ORGANIZATION_NAME="espressif" -SDKCONFIG_DIR="$PLATFORMIO_ESP32_PATH/tools/esp32-arduino-libs" -SCRIPTS_DIR="./.github/scripts" -COUNT_SKETCHES="${SCRIPTS_DIR}/sketch_utils.sh count" -CHECK_REQUIREMENTS="${SCRIPTS_DIR}/sketch_utils.sh check_requirements" - -echo "Installing Python Wheel ..." -pip install wheel > /dev/null 2>&1 - -echo "Installing PlatformIO ..." -pip install -U https://github.com/platformio/platformio/archive/master.zip > /dev/null 2>&1 - -echo "Installing Platform ESP32 ..." -python -m platformio platform install $PLATFORMIO_ESP32_URL > /dev/null 2>&1 - -echo "Replacing the package versions ..." -replace_script="import json; import os;" -replace_script+="fp=open(os.path.expanduser('~/.platformio/platforms/espressif32/platform.json'), 'r+');" -replace_script+="data=json.load(fp);" -# Use framework sources from the repository -replace_script+="data['packages']['framework-arduinoespressif32']['version'] = '*';" -replace_script+="del data['packages']['framework-arduinoespressif32']['owner'];" -# Use toolchain packages from the "espressif" organization -replace_script+="data['packages']['toolchain-xtensa-esp32']['owner']='$ESPRESSIF_ORGANIZATION_NAME';" -replace_script+="data['packages']['toolchain-xtensa-esp32s2']['owner']='$ESPRESSIF_ORGANIZATION_NAME';" -replace_script+="data['packages']['toolchain-riscv32-esp']['owner']='$ESPRESSIF_ORGANIZATION_NAME';" -# Update versions to use the upstream -replace_script+="data['packages']['toolchain-xtensa-esp32']['version']='$TOOLCHAIN_VERSION';" -replace_script+="data['packages']['toolchain-xtensa-esp32s2']['version']='$TOOLCHAIN_VERSION';" -replace_script+="data['packages']['toolchain-xtensa-esp32s3']['version']='$TOOLCHAIN_VERSION';" -replace_script+="data['packages']['toolchain-riscv32-esp']['version']='$TOOLCHAIN_VERSION';" -# Add new "framework-arduinoespressif32-libs" package -# Read "package_esp32_index.template.json" to extract a url to a zip package for "esp32-arduino-libs" -replace_script+="fpackage=open(os.path.join('package', 'package_esp32_index.template.json'), 'r+');" -replace_script+="package_data=json.load(fpackage);" -replace_script+="fpackage.close();" -replace_script+="libs_package_archive_url=next(next(system['url'] for system in tool['systems'] if system['host'] == 'x86_64-pc-linux-gnu') for tool in package_data['packages'][0]['tools'] if tool['name'] == 'esp32-arduino-libs');" -replace_script+="data['packages'].update({'framework-arduinoespressif32-libs':{'type':'framework','optional':False,'version':libs_package_archive_url}});" -replace_script+="data['packages']['toolchain-xtensa-esp32'].update({'optional':False});" -# esptool.py may require an upstream version (for now platformio is the owner) -replace_script+="data['packages']['tool-esptoolpy']['version']='$ESPTOOLPY_VERSION';" -# Save results -replace_script+="fp.seek(0);fp.truncate();json.dump(data, fp, indent=2);fp.close()" -python -c "$replace_script" - -if [ "$GITHUB_REPOSITORY" == "espressif/arduino-esp32" ]; then - echo "Linking Core..." - ln -s $GITHUB_WORKSPACE "$PLATFORMIO_ESP32_PATH" -else - echo "Cloning Core Repository ..." - git clone --recursive https://github.com/espressif/arduino-esp32.git "$PLATFORMIO_ESP32_PATH" > /dev/null 2>&1 -fi - -echo "PlatformIO for ESP32 has been installed" -echo "" - -function build_pio_sketch(){ # build_pio_sketch - if [ "$#" -lt 3 ]; then - echo "ERROR: Illegal number of parameters" - echo "USAGE: build_pio_sketch " - return 1 - fi - - local board="$1" - local options="$2" - local sketch="$3" - local sketch_dir=$(dirname "$sketch") - echo "" - echo "Compiling '"$(basename "$sketch")"' ..." - python -m platformio ci --board "$board" "$sketch_dir" --project-option="$options" -} - -function build_pio_sketches(){ # build_pio_sketches - if [ "$#" -lt 3 ]; then - echo "ERROR: Illegal number of parameters" - echo "USAGE: build_pio_sketches [ ]" - return 1 - fi - - local board=$1 - local options="$2" - local examples=$3 - local chunk_idex=$4 - local chunks_num=$5 - - if [ "$#" -lt 5 ]; then - chunk_idex="0" - chunks_num="1" - fi - - if [ "$chunks_num" -le 0 ]; then - echo "ERROR: Chunks count must be positive number" - return 1 - fi - if [ "$chunk_idex" -ge "$chunks_num" ]; then - echo "ERROR: Chunk index must be less than chunks count" - return 1 - fi - - set +e - ${COUNT_SKETCHES} "$examples" "esp32" - local sketchcount=$? - set -e - local sketches=$(cat sketches.txt) - rm -rf sketches.txt - - local chunk_size=$(( $sketchcount / $chunks_num )) - local all_chunks=$(( $chunks_num * $chunk_size )) - if [ "$all_chunks" -lt "$sketchcount" ]; then - chunk_size=$(( $chunk_size + 1 )) - fi - - local start_index=$(( $chunk_idex * $chunk_size )) - if [ "$sketchcount" -le "$start_index" ]; then - echo "Skipping job" - return 0 - fi - - local end_index=$(( $(( $chunk_idex + 1 )) * $chunk_size )) - if [ "$end_index" -gt "$sketchcount" ]; then - end_index=$sketchcount - fi - - local start_num=$(( $start_index + 1 )) - echo "Found $sketchcount Sketches"; - echo "Chunk Count : $chunks_num" - echo "Chunk Size : $chunk_size" - echo "Start Sketch: $start_num" - echo "End Sketch : $end_index" - - local sketchnum=0 - for sketch in $sketches; do - local sketchdir=$(dirname $sketch) - local sketchdirname=$(basename $sketchdir) - local sketchname=$(basename $sketch) - if [[ "$sketchdirname.ino" != "$sketchname" ]]; then - continue - elif [ -f $sketchdir/ci.json ]; then - # If the target is listed as false, skip the sketch. Otherwise, include it. - is_target=$(jq -r '.targets[esp32]' $sketchdir/ci.json) - if [[ "$is_target" == "false" ]]; then - continue - fi - - local has_requirements=$(${CHECK_REQUIREMENTS} $sketchdir "$SDKCONFIG_DIR/esp32/sdkconfig") - if [ "$has_requirements" == "0" ]; then - continue - fi - fi - - sketchnum=$(($sketchnum + 1)) - if [ "$sketchnum" -le "$start_index" ] \ - || [ "$sketchnum" -gt "$end_index" ]; then - continue - fi - build_pio_sketch "$board" "$options" "$sketch" - local result=$? - if [ $result -ne 0 ]; then - return $result - fi - done - return 0 -} diff --git a/.github/scripts/on-push.sh b/.github/scripts/on-push.sh index 08ff505f1c0..7f436c7b0ee 100755 --- a/.github/scripts/on-push.sh +++ b/.github/scripts/on-push.sh @@ -54,14 +54,11 @@ CHUNK_INDEX=$1 CHUNKS_CNT=$2 BUILD_LOG=$3 SKETCHES_FILE=$4 -BUILD_PIO=0 if [ "$#" -lt 2 ] || [ "$CHUNKS_CNT" -le 0 ]; then CHUNK_INDEX=0 CHUNKS_CNT=1 elif [ "$CHUNK_INDEX" -gt "$CHUNKS_CNT" ] && [ "$CHUNKS_CNT" -ge 2 ]; then CHUNK_INDEX=$CHUNKS_CNT -elif [ "$CHUNK_INDEX" -eq "$CHUNKS_CNT" ]; then - BUILD_PIO=1 fi if [ -z "$BUILD_LOG" ] || [ "$BUILD_LOG" -le 0 ]; then @@ -72,54 +69,34 @@ fi #git -C "$GITHUB_WORKSPACE" submodule update --init --recursive > /dev/null 2>&1 SCRIPTS_DIR="./.github/scripts" -if [ "$BUILD_PIO" -eq 0 ]; then - source ${SCRIPTS_DIR}/install-arduino-cli.sh - source ${SCRIPTS_DIR}/install-arduino-core-esp32.sh - - SKETCHES_ESP32="\ - $ARDUINO_ESP32_PATH/libraries/NetworkClientSecure/examples/WiFiClientSecure/WiFiClientSecure.ino\ - $ARDUINO_ESP32_PATH/libraries/BLE/examples/Server/Server.ino\ - $ARDUINO_ESP32_PATH/libraries/ESP32/examples/Camera/CameraWebServer/CameraWebServer.ino\ - $ARDUINO_ESP32_PATH/libraries/Insights/examples/MinimalDiagnostics/MinimalDiagnostics.ino\ - " - #create sizes_file - sizes_file="$GITHUB_WORKSPACE/cli_compile_$CHUNK_INDEX.json" - - if [ "$BUILD_LOG" -eq 1 ]; then - #create sizes_file and echo start of JSON array with "boards" key - echo "{\"boards\": [" > $sizes_file - fi +source ${SCRIPTS_DIR}/install-arduino-cli.sh +source ${SCRIPTS_DIR}/install-arduino-core-esp32.sh + +SKETCHES_ESP32="\ + $ARDUINO_ESP32_PATH/libraries/NetworkClientSecure/examples/WiFiClientSecure/WiFiClientSecure.ino\ + $ARDUINO_ESP32_PATH/libraries/BLE/examples/Server/Server.ino\ + $ARDUINO_ESP32_PATH/libraries/ESP32/examples/Camera/CameraWebServer/CameraWebServer.ino\ + $ARDUINO_ESP32_PATH/libraries/Insights/examples/MinimalDiagnostics/MinimalDiagnostics.ino\ +" +#create sizes_file +sizes_file="$GITHUB_WORKSPACE/cli_compile_$CHUNK_INDEX.json" + +if [ "$BUILD_LOG" -eq 1 ]; then + #create sizes_file and echo start of JSON array with "boards" key + echo "{\"boards\": [" > $sizes_file +fi - #build sketches for different targets - build "esp32s3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" - build "esp32s2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" - build "esp32c3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" - build "esp32c6" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" - build "esp32h2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" - build "esp32" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" - - if [ "$BUILD_LOG" -eq 1 ]; then - #remove last comma from the last JSON object - sed -i '$ s/,$//' "$sizes_file" - #echo end of JSON array - echo "]}" >> $sizes_file - fi -else - source ${SCRIPTS_DIR}/install-platformio-esp32.sh - # PlatformIO ESP32 Test - BOARD="esp32dev" - OPTIONS="board_build.partitions = huge_app.csv" - build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/WiFi/examples/WiFiClient/WiFiClient.ino" && \ - build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/NetworkClientSecure/examples/WiFiClientSecure/WiFiClientSecure.ino" && \ - build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/BluetoothSerial/examples/SerialToSerialBT/SerialToSerialBT.ino" && \ - build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/BLE/examples/Server/Server.ino" && \ - build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/ESP32/examples/Camera/CameraWebServer/CameraWebServer.ino" - - # Basic sanity testing for other series - for board in "esp32-c3-devkitm-1" "esp32-s2-saola-1" "esp32-s3-devkitc-1" - do - python -m platformio ci --board "$board" "$PLATFORMIO_ESP32_PATH/libraries/WiFi/examples/WiFiClient" --project-option="board_build.partitions = huge_app.csv" - done - - #build_pio_sketches "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries" +#build sketches for different targets +build "esp32s3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" +build "esp32s2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" +build "esp32c3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" +build "esp32c6" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" +build "esp32h2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" +build "esp32" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" + +if [ "$BUILD_LOG" -eq 1 ]; then + #remove last comma from the last JSON object + sed -i '$ s/,$//' "$sizes_file" + #echo end of JSON array + echo "]}" >> $sizes_file fi diff --git a/.github/scripts/on-release.sh b/.github/scripts/on-release.sh index e0dd7b752c5..2308717e9d8 100755 --- a/.github/scripts/on-release.sh +++ b/.github/scripts/on-release.sh @@ -207,7 +207,6 @@ cp -f "$GITHUB_WORKSPACE/tools/gen_insights_package.py" "$PKG_DIR/tools/" cp -f "$GITHUB_WORKSPACE/tools/gen_insights_package.exe" "$PKG_DIR/tools/" cp -Rf "$GITHUB_WORKSPACE/tools/partitions" "$PKG_DIR/tools/" cp -Rf "$GITHUB_WORKSPACE/tools/ide-debug" "$PKG_DIR/tools/" -cp -f "$GITHUB_WORKSPACE/tools/platformio-build.py" "$PKG_DIR/tools/" # Remove unnecessary files in the package folder echo "Cleaning up folders ..." diff --git a/.github/scripts/set_push_chunks.sh b/.github/scripts/set_push_chunks.sh index 11a93a7159d..3e3dd89f3ae 100644 --- a/.github/scripts/set_push_chunks.sh +++ b/.github/scripts/set_push_chunks.sh @@ -78,6 +78,5 @@ echo "build_all=$build_all" >> $GITHUB_OUTPUT echo "build_libraries=$BUILD_LIBRARIES" >> $GITHUB_OUTPUT echo "build_static_sketches=$BUILD_STATIC_SKETCHES" >> $GITHUB_OUTPUT echo "build_idf=$BUILD_IDF" >> $GITHUB_OUTPUT -echo "build_platformio=$BUILD_PLATFORMIO" >> $GITHUB_OUTPUT echo "chunk_count=$chunks_count" >> $GITHUB_OUTPUT echo "chunks=$chunks" >> $GITHUB_OUTPUT diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index 82159e1b8a4..899a0fe7b88 100644 --- a/.github/workflows/push.yml +++ b/.github/workflows/push.yml @@ -61,7 +61,6 @@ jobs: build_libraries: ${{ steps.set-chunks.outputs.build_libraries }} build_static_sketches: ${{ steps.set-chunks.outputs.build_static_sketches }} build_idf: ${{ steps.set-chunks.outputs.build_idf }} - build_platformio: ${{ steps.set-chunks.outputs.build_platformio }} chunk_count: ${{ steps.set-chunks.outputs.chunk_count }} chunks: ${{ steps.set-chunks.outputs.chunks }} steps: @@ -77,11 +76,9 @@ jobs: files_yaml: | core: - '.github/**' - - '!.github/scripts/install-platformio-esp32.sh' - 'cores/**' - 'package/**' - 'tools/**' - - '!tools/platformio-build.py' - 'platform.txt' - 'programmers.txt' - "variants/esp32/**/*" @@ -110,10 +107,6 @@ jobs: - 'Kconfig.projbuild' - 'CMakeLists.txt' - "variants/esp32c2/**/*" - platformio: - - 'package.json' - - '.github/scripts/install-platformio-esp32.sh' - - 'tools/platformio-build.py' - name: Set chunks id: set-chunks @@ -121,7 +114,6 @@ jobs: LIB_FILES: ${{ steps.changed-files.outputs.libraries_all_changed_files }} IS_PR: ${{ github.event_name == 'pull_request' }} MAX_CHUNKS: ${{ env.MAX_CHUNKS }} - BUILD_PLATFORMIO: ${{ steps.changed-files.outputs.platformio_any_changed == 'true' }} BUILD_IDF: ${{ steps.changed-files.outputs.idf_any_changed == 'true' }} BUILD_LIBRARIES: ${{ steps.changed-files.outputs.libraries_any_changed == 'true' }} BUILD_STATIC_SKETCHES: ${{ steps.changed-files.outputs.static_sketeches_any_changed == 'true' }} @@ -212,28 +204,6 @@ jobs: - name: Build Sketches run: bash ./.github/scripts/on-push.sh - # PlatformIO on Windows, Ubuntu and Mac - build-platformio: - name: PlatformIO on ${{ matrix.os }} - needs: gen-chunks - if: | - needs.gen-chunks.outputs.build_all == 'true' || - needs.gen-chunks.outputs.build_static_sketches == 'true' || - needs.gen-chunks.outputs.build_platformio == 'true' - runs-on: ${{ matrix.os }} - strategy: - fail-fast: false - matrix: - os: [ubuntu-latest, windows-latest, macOS-latest] - - steps: - - uses: actions/checkout@v4 - - uses: actions/setup-python@v5 - with: - python-version: '3.x' - - name: Build Sketches - run: bash ./.github/scripts/on-push.sh 1 1 #equal and non-zero to trigger PIO - build-esp-idf-component: name: Build with ESP-IDF ${{ matrix.idf_ver }} for ${{ matrix.idf_target }} needs: gen-chunks diff --git a/platform.txt b/platform.txt index d1c3fb3a3dd..ec1245c9b92 100644 --- a/platform.txt +++ b/platform.txt @@ -47,7 +47,6 @@ compiler.warning_flags.more=-Wall compiler.warning_flags.all=-Wall -Wextra # Additional flags specific to Arduino (not based on IDF flags). -# Update tools/platformio-build.py when changing these flags. compiler.common_werror_flags=-Werror=return-type # Compile Flags diff --git a/tools/platformio-build.py b/tools/platformio-build.py deleted file mode 100644 index 1ece3afddff..00000000000 --- a/tools/platformio-build.py +++ /dev/null @@ -1,251 +0,0 @@ -# Copyright 2014-present PlatformIO -# -# Licensed under the Apache License, Version 2.0 (the "License"); -# you may not use this file except in compliance with the License. -# You may obtain a copy of the License at -# -# http://www.apache.org/licenses/LICENSE-2.0 -# -# Unless required by applicable law or agreed to in writing, software -# distributed under the License is distributed on an "AS IS" BASIS, -# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. -# See the License for the specific language governing permissions and -# limitations under the License. - -""" -Arduino - -Arduino Wiring-based Framework allows writing cross-platform software to -control devices attached to a wide range of Arduino boards to create all -kinds of creative coding, interactive objects, spaces or physical experiences. - -http://arduino.cc/en/Reference/HomePage -""" - -# Extends: https://github.com/platformio/platform-espressif32/blob/develop/builder/main.py - -from os.path import abspath, basename, isdir, isfile, join -from copy import deepcopy -from SCons.Script import DefaultEnvironment, SConscript - -env = DefaultEnvironment() -platform = env.PioPlatform() -board_config = env.BoardConfig() -build_mcu = board_config.get("build.mcu", "").lower() -partitions_name = board_config.get("build.partitions", board_config.get("build.arduino.partitions", "")) - -FRAMEWORK_DIR = platform.get_package_dir("framework-arduinoespressif32") -FRAMEWORK_LIBS_DIR = platform.get_package_dir("framework-arduinoespressif32-libs") -assert isdir(FRAMEWORK_DIR) - - -# -# Helpers -# - - -def get_partition_table_csv(variants_dir): - fwpartitions_dir = join(FRAMEWORK_DIR, "tools", "partitions") - variant_partitions_dir = join(variants_dir, board_config.get("build.variant", "")) - - if partitions_name: - # A custom partitions file is selected - if isfile(env.subst(join(variant_partitions_dir, partitions_name))): - return join(variant_partitions_dir, partitions_name) - - return abspath( - join(fwpartitions_dir, partitions_name) - if isfile(env.subst(join(fwpartitions_dir, partitions_name))) - else partitions_name - ) - - variant_partitions = join(variant_partitions_dir, "partitions.csv") - return variant_partitions if isfile(env.subst(variant_partitions)) else join(fwpartitions_dir, "default.csv") - - -def get_bootloader_image(variants_dir): - bootloader_image_file = "bootloader.bin" - if partitions_name.endswith("tinyuf2.csv"): - bootloader_image_file = "bootloader-tinyuf2.bin" - - variant_bootloader = join( - variants_dir, - board_config.get("build.variant", ""), - board_config.get("build.arduino.custom_bootloader", bootloader_image_file), - ) - - return ( - variant_bootloader - if isfile(env.subst(variant_bootloader)) - else generate_bootloader_image( - join( - FRAMEWORK_LIBS_DIR, - build_mcu, - "bin", - "bootloader_${__get_board_boot_mode(__env__)}_${__get_board_f_boot(__env__)}.elf", - ) - ) - ) - - -def generate_bootloader_image(bootloader_elf): - bootloader_cmd = env.Command( - join("$BUILD_DIR", "bootloader.bin"), - bootloader_elf, - env.VerboseAction( - " ".join( - [ - '"$PYTHONEXE" "$OBJCOPY"', - "--chip", - build_mcu, - "elf2image", - "--flash_mode", - "${__get_board_flash_mode(__env__)}", - "--flash_freq", - "${__get_board_f_image(__env__)}", - "--flash_size", - board_config.get("upload.flash_size", "4MB"), - "-o", - "$TARGET", - "$SOURCES", - ] - ), - "Building $TARGET", - ), - ) - - env.Depends("$BUILD_DIR/$PROGNAME$PROGSUFFIX", bootloader_cmd) - - # Because the Command always returns a NodeList, we have to - # access the first element in the list to get the Node object - # that actually represents the bootloader image. - # Also, this file is later used in generic Python code, so the - # Node object in converted to a generic string - return str(bootloader_cmd[0]) - - -def add_tinyuf2_extra_image(): - tinuf2_image = board_config.get( - "upload.arduino.tinyuf2_image", - join(variants_dir, board_config.get("build.variant", ""), "tinyuf2.bin"), - ) - - # Add the UF2 image only if it exists and it's not already added - if not isfile(env.subst(tinuf2_image)): - print("Warning! The `%s` UF2 bootloader image doesn't exist" % env.subst(tinuf2_image)) - return - - if any("tinyuf2.bin" == basename(extra_image[1]) for extra_image in env.get("FLASH_EXTRA_IMAGES", [])): - print("Warning! An extra UF2 bootloader image is already added!") - return - - env.Append( - FLASH_EXTRA_IMAGES=[ - ( - board_config.get( - "upload.arduino.uf2_bootloader_offset", - ("0x2d0000" if env.subst("$BOARD").startswith("adafruit") else "0x410000"), - ), - tinuf2_image, - ), - ] - ) - - -# -# Run target-specific script to populate the environment with proper build flags -# - -SConscript( - join( - FRAMEWORK_LIBS_DIR, - build_mcu, - "platformio-build.py", - ) -) - -# -# Additional flags specific to Arduino core (not based on IDF) -# - -env.Append( - CFLAGS=["-Werror=return-type"], - CXXFLAGS=["-Werror=return-type"], -) - -# -# Target: Build Core Library -# - -# Set -DARDUINO_CORE_BUILD only for the core library -corelib_env = env.Clone() -corelib_env.Append(CPPDEFINES=["ARDUINO_CORE_BUILD"]) - -libs = [] - -variants_dir = join(FRAMEWORK_DIR, "variants") - -if "build.variants_dir" in board_config: - variants_dir = join("$PROJECT_DIR", board_config.get("build.variants_dir")) - -if "build.variant" in board_config: - env.Append(CPPPATH=[join(variants_dir, board_config.get("build.variant"))]) - corelib_env.Append(CPPPATH=[join(variants_dir, board_config.get("build.variant"))]) - corelib_env.BuildSources( - join("$BUILD_DIR", "FrameworkArduinoVariant"), - join(variants_dir, board_config.get("build.variant")), - ) - -libs.append( - corelib_env.BuildLibrary( - join("$BUILD_DIR", "FrameworkArduino"), - join(FRAMEWORK_DIR, "cores", board_config.get("build.core")), - ) -) - -env.Prepend(LIBS=libs) - -# -# Process framework extra images -# - -env.Append( - LIBSOURCE_DIRS=[join(FRAMEWORK_DIR, "libraries")], - FLASH_EXTRA_IMAGES=[ - ( - "0x1000" if build_mcu in ("esp32", "esp32s2") else "0x0000", - get_bootloader_image(variants_dir), - ), - ("0x8000", join(env.subst("$BUILD_DIR"), "partitions.bin")), - ("0xe000", join(FRAMEWORK_DIR, "tools", "partitions", "boot_app0.bin")), - ] - + [(offset, join(FRAMEWORK_DIR, img)) for offset, img in board_config.get("upload.arduino.flash_extra_images", [])], -) - -# Add an extra UF2 image if the 'TinyUF2' partition is selected -if partitions_name.endswith("tinyuf2.csv") or board_config.get("upload.arduino.tinyuf2_image", ""): - add_tinyuf2_extra_image() - -# -# Generate partition table -# - -env.Replace(PARTITIONS_TABLE_CSV=get_partition_table_csv(variants_dir)) - -partition_table = env.Command( - join("$BUILD_DIR", "partitions.bin"), - "$PARTITIONS_TABLE_CSV", - env.VerboseAction( - '"$PYTHONEXE" "%s" -q $SOURCE $TARGET' % join(FRAMEWORK_DIR, "tools", "gen_esp32part.py"), - "Generating partitions $TARGET", - ), -) -env.Depends("$BUILD_DIR/$PROGNAME$PROGSUFFIX", partition_table) - -# -# Adjust the `esptoolpy` command in the `ElfToBin` builder with firmware checksum offset -# - -action = deepcopy(env["BUILDERS"]["ElfToBin"].action) -action.cmd_list = env["BUILDERS"]["ElfToBin"].action.cmd_list.replace("-o", "--elf-sha256-offset 0xb0 -o") -env["BUILDERS"]["ElfToBin"].action = action From 34f15c0335bb02bc81daf757b0541848bb4ddaef Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Fri, 29 Nov 2024 19:12:01 -0300 Subject: [PATCH 2/7] feat(support): documentation adjustment --- docs/_static/logo_pio.png | Bin 25979 -> 0 bytes docs/en/getting_started.rst | 11 +++-- docs/en/installing.rst | 87 ------------------------------------ docs/en/tutorials/blink.rst | 3 +- 4 files changed, 6 insertions(+), 95 deletions(-) delete mode 100644 docs/_static/logo_pio.png diff --git a/docs/_static/logo_pio.png b/docs/_static/logo_pio.png deleted file mode 100644 index a64c156396481be375fd126891d10c7e9d395488..0000000000000000000000000000000000000000 GIT binary patch literal 0 HcmV?d00001 literal 25979 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 z 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 u-4oHfQ(EkSuz*$f~g|xf?0000`_ for more details on how to install the Arduino ESP32 support. diff --git a/docs/en/installing.rst b/docs/en/installing.rst index ec405b3552c..d5392d4b5ec 100644 --- a/docs/en/installing.rst +++ b/docs/en/installing.rst @@ -63,92 +63,6 @@ To start the installation process using the Boards Manager, follow these steps: - Restart Arduino IDE. -Installing using PlatformIO ---------------------------- - -.. figure:: ../_static/logo_pio.png - :align: center - :width: 200 - :figclass: align-center - -PlatformIO is a professional collaborative platform for embedded development. It has out-of-the-box support for ESP32 SoCs and allows working with Arduino ESP32 as well as ESP-IDF from Espressif without changing your development environment. PlatformIO includes lots of instruments for the most common development tasks such as debugging, unit testing, and static code analysis. - -.. warning:: Integration of the Arduino Core ESP32 project in PlatformIO is maintained by PlatformIO developers. Arduino Core ESP32 Project Team cannot support PlatformIO-specific issues. Please report these issues in official `PlatformIO repositories `_. - -A detailed overview of the PlatformIO ecosystem and its philosophy can be found in `the official documentation `_. - -PlatformIO can be used in two flavors: - -- `PlatformIO IDE `_ is a toolset for embedded C/C++ development available on Windows, macOS and Linux platforms - -- `PlatformIO Core (CLI) `_ is a command-line tool that consists of a multi-platform build system, platform and library managers and other integration components. It can be used with a variety of code development environments and allows integration with cloud platforms and web services - -To install PlatformIO, you can follow this Getting Started, provided at `docs.platformio.org`_. - -Using the stable code -********************* - -.. note:: - A detailed overview of supported development boards, examples and frameworks can be found on `the official Espressif32 dev-platform page `_ in the PlatformIO Registry. - -The most reliable and easiest way to get started is to use the latest stable version of the ESP32 development platform that passed all tests/verifications and can be used in production. - -Create a new project and select one of the available boards. You can change after by changing the `platformio.ini `_ file. - -- For ESP32 - -.. code-block:: bash - - [env:esp32dev] - platform = espressif32 - board = esp32dev - framework = arduino - -- For ESP32-S2 (ESP32-S2-Saola-1 board) - -.. code-block:: bash - - [env:esp32-s2-saola-1] - platform = espressif32 - board = esp32-s2-saola-1 - framework = arduino - -- For ESP32-C3 (ESP32-C3-DevKitM-1 board) - -.. code-block:: bash - - [env:esp32-c3-devkitm-1] - platform = espressif32 - board = esp32-c3-devkitm-1 - framework = arduino - -How to update to the latest code -******************************** - -To test the latest Arduino ESP32, you need to change your project *platformio.ini* accordingly. -The following configuration uses the upstream version of the Espressif development platform and the latest Arduino core directly from the Espressif GitHub repository: - -.. code-block:: bash - - [env:esp32-c3-devkitm-1] - platform = https://github.com/platformio/platform-espressif32.git - board = esp32-c3-devkitm-1 - framework = arduino - platform_packages = - framework-arduinoespressif32 @ https://github.com/espressif/arduino-esp32#master - - -To get more information about PlatformIO, see the following links: - -- `PlatformIO Core (CLI) `_ - -- `PlatformIO Home `_ - -- `Tutorials and Examples `_ - -- `Library Management `_ - - Windows (manual installation) ----------------------------- @@ -360,4 +274,3 @@ Where ``~/Documents/Arduino`` represents your sketch book location as per "Ardui - Restart Arduino IDE. .. _Arduino.cc: https://www.arduino.cc/en/Main/Software -.. _docs.platformio.org: https://docs.platformio.org/en/latest/integration/ide/pioide.html diff --git a/docs/en/tutorials/blink.rst b/docs/en/tutorials/blink.rst index b5f6a767f8d..5d6f13c8d17 100644 --- a/docs/en/tutorials/blink.rst +++ b/docs/en/tutorials/blink.rst @@ -7,7 +7,7 @@ Introduction This is the interactive blink tutorial using `Wokwi`_. For this tutorial, you don't need the ESP32 board or the Arduino toolchain. -.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use it on the `Arduino IDE`_ or `PlatformIO`_. +.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use it on the `Arduino IDE` _. About this Tutorial ------------------- @@ -109,5 +109,4 @@ Resources .. _ESP32 Datasheet: https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf .. _Wokwi: https://wokwi.com/ -.. _PlatformIO: https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#platformio .. _Arduino IDE: https://docs.espressif.com/projects/arduino-esp32/en/latest/installing.html#installing-using-boards-manager From cb672d8daf20ff899c83e2ed90bbeef668bda721 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Fri, 29 Nov 2024 19:13:49 -0300 Subject: [PATCH 3/7] feat(support): readme files, commentaries and examples --- .../FreeRTOS/BasicMultiThreading/README.md | 4 - .../ESP32/examples/FreeRTOS/Mutex/README.md | 238 +++++++-------- .../ESP32/examples/FreeRTOS/Queue/README.md | 146 +++++---- .../examples/FreeRTOS/Semaphore/README.md | 158 +++++----- .../Legacy_RMT_Driver_Compatible.ino | 1 - .../Template/ExampleTemplate/README.md | 242 ++++++++------- .../examples/LITTLEFS_PlatformIO/.gitignore | 4 - .../examples/LITTLEFS_PlatformIO/README.md | 68 ----- .../LITTLEFS_PlatformIO/data/file1.txt | 1 - .../data/testfolder/test2.txt | 1 - .../include/.placeholder.txt | 0 .../LITTLEFS_PlatformIO/lib/.placeholder.txt | 0 .../LITTLEFS_PlatformIO/partitions_custom.csv | 6 - .../LITTLEFS_PlatformIO/platformio.ini | 22 -- .../examples/LITTLEFS_PlatformIO/src/main.cpp | 286 ------------------ libraries/NetworkClientSecure/README.md | 20 +- .../examples/MultiHomedServers/README.md | 4 - .../WiFi/examples/FTM/FTM_Initiator/README.md | 4 - .../WiFi/examples/FTM/FTM_Responder/README.md | 4 - libraries/WiFi/examples/WiFiClient/README.md | 4 - .../WiFi/examples/WiFiClientConnect/README.md | 4 - libraries/WiFi/examples/WiFiScan/README.md | 4 - .../WiFi/examples/WiFiScanAsync/README.md | 4 - .../examples/WiFiScanDualAntenna/README.md | 4 - .../WiFi/examples/WiFiScanTime/README.md | 4 - 25 files changed, 387 insertions(+), 846 deletions(-) delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/.gitignore delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/README.md delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/file1.txt delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/testfolder/test2.txt delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/include/.placeholder.txt delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/lib/.placeholder.txt delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/partitions_custom.csv delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/platformio.ini delete mode 100644 libraries/LittleFS/examples/LITTLEFS_PlatformIO/src/main.cpp diff --git a/libraries/ESP32/examples/FreeRTOS/BasicMultiThreading/README.md b/libraries/ESP32/examples/FreeRTOS/BasicMultiThreading/README.md index 7bd44855adc..f48e352dd45 100644 --- a/libraries/ESP32/examples/FreeRTOS/BasicMultiThreading/README.md +++ b/libraries/ESP32/examples/FreeRTOS/BasicMultiThreading/README.md @@ -62,10 +62,6 @@ To get more information about the Espressif boards see [Espressif Development Ki * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - ## Troubleshooting ***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** diff --git a/libraries/ESP32/examples/FreeRTOS/Mutex/README.md b/libraries/ESP32/examples/FreeRTOS/Mutex/README.md index d1c8c19e3be..32c9f027bff 100644 --- a/libraries/ESP32/examples/FreeRTOS/Mutex/README.md +++ b/libraries/ESP32/examples/FreeRTOS/Mutex/README.md @@ -1,121 +1,117 @@ -# Mutex Example - -This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading. -Please refer to other examples in this folder to better understand the usage of tasks. -It is also advised to read the documentation on FreeRTOS web pages: -https://www.freertos.org/a00106.html - -This example creates 2 tasks with the same implementation - they write into a shared variable and then read it and check if it is the same as what they have written. -In single-thread programming like on Arduino this is of no concern and will be always ok, however when multi-threading is used the execution of the task is switched by the FreeRTOS and the value can be rewritten from another task before reading again. -The tasks print write and read operation - each in their column for better reading. Task 0 is on the left and Task 1 is on the right. -Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them. -Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches! - -### Theory: -Mutex is a specialized version of Semaphore (please see the Semaphore example for more info). -In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked). -When two or more processes access the same resource (variable, peripheral, etc) it might happen, for example, that when one task starts to read a variable and the operating system (FreeRTOS) will schedule the execution of another task -which will write to this variable and when the previous task runs again it will read something different. - -Mutexes and binary semaphores are very similar but have some subtle differences: -Mutexes include a priority inheritance mechanism, whereas binary semaphores do not. -This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better -choice for implementing simple mutual exclusion. -What is priority inheritance? -If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which -then tries to take the Mutex, the low-priority task will temporarily ‘inherit’ the high priority so a middle-priority task can't block the low-priority task, and thus also block the high priority task. -Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them. - -A mutex can also be recursive - if a task that holds the mutex takes it again, it will succeed, and the mutex will be released -for other tasks only when it is given the same number of times that it was taken. - -You can check the danger by commenting on the definition of USE_MUTEX which will disable the mutex and present the danger of concurrent access. - - -# Supported Targets - -This example supports all ESP32 SoCs. - -## How to Use Example - -Flash and observe the serial output. - -Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable. - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - -## Example Log Output - -The expected output of shared variables protected by mutex demonstrates mutually exclusive access from tasks - they do not interrupt each other and do not rewrite the value before the other task has read it back. - -``` - Task 0 | Task 1 - | Starting - | 0 <- 227 - Starting | - | R: 227 - 227 <- 737 | - R: 737 | - | 737 <- 282 - | R: 282 - 282 <- 267 | -``` - -The output of unprotected access to shared variable - it happens often that a task is interrupted after writing and before reading the other task write a different value - a corruption occurred! - -``` - Task 0 | Task 1 - | Starting - | 0 <- 333 - Starting | - 333 <- 620 | - R: 620 | - 620 <- 244 | - | R: 244 - | Mismatch! - | 244 <- 131 - R: 131 | - Mismatch! | - 131 <- 584 | - | R: 584 - | Mismatch! - | 584 <- 134 - | R: 134 - | 134 <- 554 - R: 554 | - Mismatch! | - 554 <- 313 | -``` - -## Troubleshooting - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -## Contribute - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Mutex Example + +This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading. +Please refer to other examples in this folder to better understand the usage of tasks. +It is also advised to read the documentation on FreeRTOS web pages: +https://www.freertos.org/a00106.html + +This example creates 2 tasks with the same implementation - they write into a shared variable and then read it and check if it is the same as what they have written. +In single-thread programming like on Arduino this is of no concern and will be always ok, however when multi-threading is used the execution of the task is switched by the FreeRTOS and the value can be rewritten from another task before reading again. +The tasks print write and read operation - each in their column for better reading. Task 0 is on the left and Task 1 is on the right. +Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them. +Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches! + +### Theory: +Mutex is a specialized version of Semaphore (please see the Semaphore example for more info). +In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked). +When two or more processes access the same resource (variable, peripheral, etc) it might happen, for example, that when one task starts to read a variable and the operating system (FreeRTOS) will schedule the execution of another task +which will write to this variable and when the previous task runs again it will read something different. + +Mutexes and binary semaphores are very similar but have some subtle differences: +Mutexes include a priority inheritance mechanism, whereas binary semaphores do not. +This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better +choice for implementing simple mutual exclusion. +What is priority inheritance? +If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which +then tries to take the Mutex, the low-priority task will temporarily ‘inherit’ the high priority so a middle-priority task can't block the low-priority task, and thus also block the high priority task. +Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them. + +A mutex can also be recursive - if a task that holds the mutex takes it again, it will succeed, and the mutex will be released +for other tasks only when it is given the same number of times that it was taken. + +You can check the danger by commenting on the definition of USE_MUTEX which will disable the mutex and present the danger of concurrent access. + + +# Supported Targets + +This example supports all ESP32 SoCs. + +## How to Use Example + +Flash and observe the serial output. + +Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable. + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example Log Output + +The expected output of shared variables protected by mutex demonstrates mutually exclusive access from tasks - they do not interrupt each other and do not rewrite the value before the other task has read it back. + +``` + Task 0 | Task 1 + | Starting + | 0 <- 227 + Starting | + | R: 227 + 227 <- 737 | + R: 737 | + | 737 <- 282 + | R: 282 + 282 <- 267 | +``` + +The output of unprotected access to shared variable - it happens often that a task is interrupted after writing and before reading the other task write a different value - a corruption occurred! + +``` + Task 0 | Task 1 + | Starting + | 0 <- 333 + Starting | + 333 <- 620 | + R: 620 | + 620 <- 244 | + | R: 244 + | Mismatch! + | 244 <- 131 + R: 131 | + Mismatch! | + 131 <- 584 | + | R: 584 + | Mismatch! + | 584 <- 134 + | R: 134 + | 134 <- 554 + R: 554 | + Mismatch! | + 554 <- 313 | +``` + +## Troubleshooting + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +## Contribute + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) diff --git a/libraries/ESP32/examples/FreeRTOS/Queue/README.md b/libraries/ESP32/examples/FreeRTOS/Queue/README.md index 745ce9e8db6..b1cc3f3e3ac 100644 --- a/libraries/ESP32/examples/FreeRTOS/Queue/README.md +++ b/libraries/ESP32/examples/FreeRTOS/Queue/README.md @@ -1,75 +1,71 @@ -# Queue Example - -This example demonstrates the basic usage of FreeRTOS Queues which enables tasks to pass data between each other in a secure asynchronous way. -Please refer to other examples in this folder to better understand the usage of tasks. -It is also advised to read the documentation on FreeRTOS web pages: -[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) - -This example reads data received on the serial port (sent by the user) pass it via queue to another task which will send it back on Serial Output. - -### Theory: -A queue is a simple-to-use data structure (in the most basic way) controlled by `xQueueSend` and `xQueueReceive` functions. -Usually, one task writes into the queue and the other task reads from it. -Usage of queues enables the reading task to yield the CPU until there are data in the queue and therefore not waste precious computation time. - -# Supported Targets - -This example supports all ESP32 SoCs. - -## How to Use Example - -Flash and write anything to serial input. - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - -## Example Log Output - -``` -Anything you write will return as echo. -Maximum line length is 63 characters (+ terminating '0'). -Anything longer will be sent as a separate line. - -``` -< Input text "Short input" - -``Echo line of size 11: "Short input"`` - -< Input text "An example of very long input which is longer than default 63 characters will be split." - -``` -Echo line of size 63: "An example of very long input which is longer than default 63 c" -Echo line of size 24: "haracters will be split." -``` - -## Troubleshooting - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -## Contribute - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Queue Example + +This example demonstrates the basic usage of FreeRTOS Queues which enables tasks to pass data between each other in a secure asynchronous way. +Please refer to other examples in this folder to better understand the usage of tasks. +It is also advised to read the documentation on FreeRTOS web pages: +[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) + +This example reads data received on the serial port (sent by the user) pass it via queue to another task which will send it back on Serial Output. + +### Theory: +A queue is a simple-to-use data structure (in the most basic way) controlled by `xQueueSend` and `xQueueReceive` functions. +Usually, one task writes into the queue and the other task reads from it. +Usage of queues enables the reading task to yield the CPU until there are data in the queue and therefore not waste precious computation time. + +# Supported Targets + +This example supports all ESP32 SoCs. + +## How to Use Example + +Flash and write anything to serial input. + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example Log Output + +``` +Anything you write will return as echo. +Maximum line length is 63 characters (+ terminating '0'). +Anything longer will be sent as a separate line. + +``` +< Input text "Short input" + +``Echo line of size 11: "Short input"`` + +< Input text "An example of very long input which is longer than default 63 characters will be split." + +``` +Echo line of size 63: "An example of very long input which is longer than default 63 c" +Echo line of size 24: "haracters will be split." +``` + +## Troubleshooting + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +## Contribute + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) diff --git a/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md b/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md index 8f860a52db5..0a076713e14 100644 --- a/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md +++ b/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md @@ -1,81 +1,77 @@ -# Semaphore Example - -This example demonstrates the basic usage of FreeRTOS Semaphores and queue sets for coordination between tasks for multi-threading. -Please refer to other examples in this folder to better understand the usage of tasks. -It is also advised to read the documentation on FreeRTOS web pages: -[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) - -### Theory: -Semaphore is in essence a variable. Tasks can set the value, wait until one or more -semaphores are set and thus communicate between each other their state. -A binary semaphore is a semaphore that has a maximum count of 1, hence the 'binary' name. -A task can only 'take' the semaphore if it is available, and the semaphore is only available if its count is 1. - -Semaphores can be controlled by any number of tasks. If you use semaphore as a one-way -signalization with only one task giving and only one task taking there is a much faster option -called Task Notifications - please see FreeRTOS documentation and read more about them: [https://www.freertos.org/RTOS-task-notifications.html](https://www.freertos.org/RTOS-task-notifications.html) - -This example uses a semaphore to signal when a package is delivered to a warehouse by multiple -delivery trucks, and multiple workers are waiting to receive the package. - -# Supported Targets - -This example supports all ESP32 SoCs. - -## How to Use Example - -Read the code and try to understand it, then flash and observe the Serial output. - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - -## Example Log Output - -``` -Anything you write will return as echo. -Maximum line length is 63 characters (+ terminating '0'). -Anything longer will be sent as a separate line. - -``` -< Input text "Short input" - -``Echo line of size 11: "Short input"`` - -< Input text "An example of very long input which is longer than default 63 characters will be split." - -``` -Echo line of size 63: "An example of very long input which is longer than default 63 c" -Echo line of size 24: "haracters will be split." -``` - -## Troubleshooting - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -## Contribute - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Semaphore Example + +This example demonstrates the basic usage of FreeRTOS Semaphores and queue sets for coordination between tasks for multi-threading. +Please refer to other examples in this folder to better understand the usage of tasks. +It is also advised to read the documentation on FreeRTOS web pages: +[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) + +### Theory: +Semaphore is in essence a variable. Tasks can set the value, wait until one or more +semaphores are set and thus communicate between each other their state. +A binary semaphore is a semaphore that has a maximum count of 1, hence the 'binary' name. +A task can only 'take' the semaphore if it is available, and the semaphore is only available if its count is 1. + +Semaphores can be controlled by any number of tasks. If you use semaphore as a one-way +signalization with only one task giving and only one task taking there is a much faster option +called Task Notifications - please see FreeRTOS documentation and read more about them: [https://www.freertos.org/RTOS-task-notifications.html](https://www.freertos.org/RTOS-task-notifications.html) + +This example uses a semaphore to signal when a package is delivered to a warehouse by multiple +delivery trucks, and multiple workers are waiting to receive the package. + +# Supported Targets + +This example supports all ESP32 SoCs. + +## How to Use Example + +Read the code and try to understand it, then flash and observe the Serial output. + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example Log Output + +``` +Anything you write will return as echo. +Maximum line length is 63 characters (+ terminating '0'). +Anything longer will be sent as a separate line. + +``` +< Input text "Short input" + +``Echo line of size 11: "Short input"`` + +< Input text "An example of very long input which is longer than default 63 characters will be split." + +``` +Echo line of size 63: "An example of very long input which is longer than default 63 c" +Echo line of size 24: "haracters will be split." +``` + +## Troubleshooting + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +## Contribute + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) diff --git a/libraries/ESP32/examples/RMT/Legacy_RMT_Driver_Compatible/Legacy_RMT_Driver_Compatible.ino b/libraries/ESP32/examples/RMT/Legacy_RMT_Driver_Compatible/Legacy_RMT_Driver_Compatible.ino index 5744cf884a7..b42fe15f0cd 100644 --- a/libraries/ESP32/examples/RMT/Legacy_RMT_Driver_Compatible/Legacy_RMT_Driver_Compatible.ino +++ b/libraries/ESP32/examples/RMT/Legacy_RMT_Driver_Compatible/Legacy_RMT_Driver_Compatible.ino @@ -12,7 +12,6 @@ // add the file "build_opt.h" to your Arduino project folder with "-DESP32_ARDUINO_NO_RGB_BUILTIN" to use the RMT Legacy driver #error "ESP32_ARDUINO_NO_RGB_BUILTIN is not defined, this example is intended to demonstrate the RMT Legacy driver." #error "Please add the file 'build_opt.h' with '-DESP32_ARDUINO_NO_RGB_BUILTIN' to your Arduino project folder." -#error "Another way to disable the RGB_BUILTIN is to define it in the platformio.ini file, for instance: '-D ESP32_ARDUINO_NO_RGB_BUILTIN'" #else diff --git a/libraries/ESP32/examples/Template/ExampleTemplate/README.md b/libraries/ESP32/examples/Template/ExampleTemplate/README.md index f5aa7b35e86..4c4f497f43c 100644 --- a/libraries/ESP32/examples/Template/ExampleTemplate/README.md +++ b/libraries/ESP32/examples/Template/ExampleTemplate/README.md @@ -1,123 +1,119 @@ -# Arduino-ESP32 Example/Library Name ==(REQUIRED)== - -==*Add a brief description of this example/library here!*== - -This example/library demonstrates how to create a new example README file. - -# Supported Targets ==(REQUIRED)== - -==*Add the supported devices here!*== - -Currently, this example supports the following targets. - -| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | -| ----------------- | ----- | -------- | -------- | - -## How to Use Example/Library ==(OPTIONAL)== - -==*Add a brief description of how to use this example.*== - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -### Hardware Connection ==(OPTIONAL)== - -==*Add a brief description of wiring or any other hardware-specific connection.*== - -To use this example, you need to connect the LED to the `GPIOx`. - -SDCard GPIO connection scheme: - -| SDCard Pin | Function | GPIO | -| ----------- | -------- | ------ | -| 1 | CS | GPIO5 | -| 2 | DI/MOSI | GPIO23 | -| 3 | VSS/GND | GND | -| 4 | VDD/3V3 | 3V3 | -| 5 | SCLK | GPIO18 | -| 6 | VSS/GND | GND | -| 7 | DO/MISO | GPIO19 | - -To add images, please create a folder `_asset` inside the example folder to add the relevant images. - -### Configure the Project ==(OPTIONAL)== - -==*Add a brief description of this example here!*== - -Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`. - -#### Example for the GPIO4: - -==*Add some code explanation if relevant to the example.*== - -```cpp -// the setup function runs once when you press reset or power the board -void setup() { -// initialize digital pin 4 as an output. -pinMode(4, OUTPUT); -} -``` - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - -## Example/Log Output ==(OPTIONAL)== - -==*Add the log/serial output here!*== - -``` -ets Jul 29 2019 12:21:46 - -rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) -configsip: 0, SPIWP:0xee -clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 -mode:DIO, clock div:1 -load:0x3fff0030,len:1412 -load:0x40078000,len:13400 -load:0x40080400,len:3672 -entry 0x400805f8 -ESP32 Chip model = ESP32-D0WDQ5 Rev 3 -This chip has 2 cores -Chip ID: 3957392 -``` - -## Troubleshooting ==(REQUIRED)== - -==*Add specific issues you may find by using this example here!*== - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -* **LED not blinking:** Check the wiring connection and the IO selection. -* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed. -* **COM port not detected:** Check the USB cable and the USB to Serial driver installation. - -If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). - -## Contribute ==(REQUIRED)== - -==*Do not change! Keep it as is.*== - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources ==(REQUIRED)== - -==*Do not change here! Keep it as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*== - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Arduino-ESP32 Example/Library Name ==(REQUIRED)== + +==*Add a brief description of this example/library here!*== + +This example/library demonstrates how to create a new example README file. + +# Supported Targets ==(REQUIRED)== + +==*Add the supported devices here!*== + +Currently, this example supports the following targets. + +| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | +| ----------------- | ----- | -------- | -------- | + +## How to Use Example/Library ==(OPTIONAL)== + +==*Add a brief description of how to use this example.*== + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +### Hardware Connection ==(OPTIONAL)== + +==*Add a brief description of wiring or any other hardware-specific connection.*== + +To use this example, you need to connect the LED to the `GPIOx`. + +SDCard GPIO connection scheme: + +| SDCard Pin | Function | GPIO | +| ----------- | -------- | ------ | +| 1 | CS | GPIO5 | +| 2 | DI/MOSI | GPIO23 | +| 3 | VSS/GND | GND | +| 4 | VDD/3V3 | 3V3 | +| 5 | SCLK | GPIO18 | +| 6 | VSS/GND | GND | +| 7 | DO/MISO | GPIO19 | + +To add images, please create a folder `_asset` inside the example folder to add the relevant images. + +### Configure the Project ==(OPTIONAL)== + +==*Add a brief description of this example here!*== + +Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`. + +#### Example for the GPIO4: + +==*Add some code explanation if relevant to the example.*== + +```cpp +// the setup function runs once when you press reset or power the board +void setup() { +// initialize digital pin 4 as an output. +pinMode(4, OUTPUT); +} +``` + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example/Log Output ==(OPTIONAL)== + +==*Add the log/serial output here!*== + +``` +ets Jul 29 2019 12:21:46 + +rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) +configsip: 0, SPIWP:0xee +clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 +mode:DIO, clock div:1 +load:0x3fff0030,len:1412 +load:0x40078000,len:13400 +load:0x40080400,len:3672 +entry 0x400805f8 +ESP32 Chip model = ESP32-D0WDQ5 Rev 3 +This chip has 2 cores +Chip ID: 3957392 +``` + +## Troubleshooting ==(REQUIRED)== + +==*Add specific issues you may find by using this example here!*== + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +* **LED not blinking:** Check the wiring connection and the IO selection. +* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed. +* **COM port not detected:** Check the USB cable and the USB to Serial driver installation. + +If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). + +## Contribute ==(REQUIRED)== + +==*Do not change! Keep it as is.*== + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources ==(REQUIRED)== + +==*Do not change here! Keep it as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*== + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/.gitignore b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/.gitignore deleted file mode 100644 index 653e92272d5..00000000000 --- a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/.gitignore +++ /dev/null @@ -1,4 +0,0 @@ -.pio -.vscode -mklittlefs.exe -mklittlefs diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/README.md b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/README.md deleted file mode 100644 index beed34e92f1..00000000000 --- a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/README.md +++ /dev/null @@ -1,68 +0,0 @@ -# How to run on PlatformIO IDE - -- Download and extract to this project root a **mklittlefs** executable for your OS [from a zipped binary here](https://github.com/earlephilhower/mklittlefs/releases) -- Open **LITTLEFS_PlatformIO** folder -- Run PlatformIO project task: **Upload Filesystem Image** -- Run PlatformIO project task: **Upload and Monitor** -- You will see a Serial output like: -``` ---- Miniterm on COM5 115200,8,N,1 --- ---- Quit: Ctrl+C | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H --- -ets Jun 8 2016 00:22:57 - -rst:0x1 (POWERON_RESET),boot:0x13 (Snfigsip: 0, SPIWP:0xee -clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 -mode:DIO, clock div:2 -load:0x3fff0018,len:4 -load:0x3fff001c,len:1044 -load:0x40078000,len:10044 -load:0x40080400,len:5872 -entry 0x400806ac -Listing directory: / - FILE: /file1.txt SIZE: 3 LAST WRITE: 2020-10-06 15:10:33 - DIR : /testfolder LAST WRITE: 2020-10-06 15:10:33 -Creating Dir: /mydir -Dir created -Writing file: /mydir/hello2.txt -- file written -Listing directory: / - FILE: /file1.txt SIZE: 3 LAST WRITE: 2020-10-06 15:10:33 - DIR : /mydir LAST WRITE: 1970-01-01 00:00:00 -Listing directory: /mydir - FILE: /mydir/hello2.txt SIZE: 6 LAST WRITE: 1970-01-01 00:00:00 - DIR : /testfolder LAST WRITE: 2020-10-06 15:10:33 -Listing directory: /testfolder - FILE: /testfolder/test2.txt SIZE: 3 LAST WRITE: 2020-10-06 15:10:33 -Deleting file: /mydir/hello2.txt -- file deleted -Removing Dir: /mydir -Dir removed -Listing directory: / - FILE: /file1.txt SIZE: 3 LAST WRITE: 2020-10-06 15:10:33 - DIR : /testfolder LAST WRITE: 2020-10-06 15:10:33 -Listing directory: /testfolder - FILE: /testfolder/test2.txt SIZE: 3 LAST WRITE: 2020-10-06 15:10:33 -Writing file: /hello.txt -- file written -Appending to file: /hello.txt -- message appended -Reading file: /hello.txt -- read from file: -Hello World! -Renaming file /hello.txt to /foo.txt -- file renamed -Reading file: /foo.txt -- read from file: -Hello World! -Deleting file: /foo.txt -- file deleted -Testing file I/O with /test.txt -- writing................................................................ - - 1048576 bytes written in 12006 ms -- reading................................................................ -- 1048576 bytes read in 547 ms -Deleting file: /test.txt -- file deleted -Test complete -``` -- If you have a module with more than 4 MB flash, you can uncomment **partitions_custom.csv** in **platformio.ini** and modify the csv file accordingly diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/file1.txt b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/file1.txt deleted file mode 100644 index 72943a16fb2..00000000000 --- a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/file1.txt +++ /dev/null @@ -1 +0,0 @@ -aaa diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/testfolder/test2.txt b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/testfolder/test2.txt deleted file mode 100644 index f761ec192d9..00000000000 --- a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/data/testfolder/test2.txt +++ /dev/null @@ -1 +0,0 @@ -bbb diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/include/.placeholder.txt b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/include/.placeholder.txt deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/lib/.placeholder.txt b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/lib/.placeholder.txt deleted file mode 100644 index e69de29bb2d..00000000000 diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/partitions_custom.csv b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/partitions_custom.csv deleted file mode 100644 index 97846fa59bb..00000000000 --- a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/partitions_custom.csv +++ /dev/null @@ -1,6 +0,0 @@ -# Name, Type, SubType, Offset, Size, Flags -ota_0, app, ota_0, 0x10000, 0x1A0000, -ota_1, app, ota_1, , 0x1A0000, -otadata, data, ota, 0x350000, 0x2000, -nvs, data, nvs, , 0x6000, -data, data, spiffs, , 0xA8000, diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/platformio.ini b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/platformio.ini deleted file mode 100644 index dce1ac84456..00000000000 --- a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/platformio.ini +++ /dev/null @@ -1,22 +0,0 @@ -; PlatformIO Project Configuration File -; -; Build options: build flags, source filter -; Upload options: custom upload port, speed and extra flags -; Library options: dependencies, extra library storages -; Advanced options: extra scripting -; -; Please visit documentation for the other options and examples -; https://docs.platformio.org/page/projectconf.html - -[platformio] -default_envs = esp32 - -[env] -framework = arduino - -[env:esp32] -platform = espressif32 -board = esp32dev -board_build.partitions = partitions_custom.csv -monitor_filters = esp32_exception_decoder -monitor_speed = 115200 diff --git a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/src/main.cpp b/libraries/LittleFS/examples/LITTLEFS_PlatformIO/src/main.cpp deleted file mode 100644 index 5ae9e8d7dfc..00000000000 --- a/libraries/LittleFS/examples/LITTLEFS_PlatformIO/src/main.cpp +++ /dev/null @@ -1,286 +0,0 @@ -#include -#include "FS.h" -#include -#include - -/* You only need to format LittleFS the first time you run a - test or else use the LITTLEFS plugin to create a partition - https://github.com/lorol/arduino-esp32littlefs-plugin */ - -#define FORMAT_LITTLEFS_IF_FAILED true - -void listDir(fs::FS &fs, const char *dirname, uint8_t levels) { - Serial.printf("Listing directory: %s\r\n", dirname); - - File root = fs.open(dirname); - if (!root) { - Serial.println("- failed to open directory"); - return; - } - if (!root.isDirectory()) { - Serial.println(" - not a directory"); - return; - } - - File file = root.openNextFile(); - while (file) { - if (file.isDirectory()) { - Serial.print(" DIR : "); - - Serial.print(file.name()); - time_t t = file.getLastWrite(); - struct tm *tmstruct = localtime(&t); - Serial.printf( - " LAST WRITE: %d-%02d-%02d %02d:%02d:%02d\n", (tmstruct->tm_year) + 1900, (tmstruct->tm_mon) + 1, tmstruct->tm_mday, tmstruct->tm_hour, - tmstruct->tm_min, tmstruct->tm_sec - ); - - if (levels) { - listDir(fs, file.name(), levels - 1); - } - } else { - Serial.print(" FILE: "); - Serial.print(file.name()); - Serial.print(" SIZE: "); - - Serial.print(file.size()); - time_t t = file.getLastWrite(); - struct tm *tmstruct = localtime(&t); - Serial.printf( - " LAST WRITE: %d-%02d-%02d %02d:%02d:%02d\n", (tmstruct->tm_year) + 1900, (tmstruct->tm_mon) + 1, tmstruct->tm_mday, tmstruct->tm_hour, - tmstruct->tm_min, tmstruct->tm_sec - ); - } - file = root.openNextFile(); - } -} - -void createDir(fs::FS &fs, const char *path) { - Serial.printf("Creating Dir: %s\n", path); - if (fs.mkdir(path)) { - Serial.println("Dir created"); - } else { - Serial.println("mkdir failed"); - } -} - -void removeDir(fs::FS &fs, const char *path) { - Serial.printf("Removing Dir: %s\n", path); - if (fs.rmdir(path)) { - Serial.println("Dir removed"); - } else { - Serial.println("rmdir failed"); - } -} - -void readFile(fs::FS &fs, const char *path) { - Serial.printf("Reading file: %s\r\n", path); - - File file = fs.open(path); - if (!file || file.isDirectory()) { - Serial.println("- failed to open file for reading"); - return; - } - - Serial.println("- read from file:"); - while (file.available()) { - Serial.write(file.read()); - } - file.close(); -} - -void writeFile(fs::FS &fs, const char *path, const char *message) { - Serial.printf("Writing file: %s\r\n", path); - - File file = fs.open(path, FILE_WRITE); - if (!file) { - Serial.println("- failed to open file for writing"); - return; - } - if (file.print(message)) { - Serial.println("- file written"); - } else { - Serial.println("- write failed"); - } - file.close(); -} - -void appendFile(fs::FS &fs, const char *path, const char *message) { - Serial.printf("Appending to file: %s\r\n", path); - - File file = fs.open(path, FILE_APPEND); - if (!file) { - Serial.println("- failed to open file for appending"); - return; - } - if (file.print(message)) { - Serial.println("- message appended"); - } else { - Serial.println("- append failed"); - } - file.close(); -} - -void renameFile(fs::FS &fs, const char *path1, const char *path2) { - Serial.printf("Renaming file %s to %s\r\n", path1, path2); - if (fs.rename(path1, path2)) { - Serial.println("- file renamed"); - } else { - Serial.println("- rename failed"); - } -} - -void deleteFile(fs::FS &fs, const char *path) { - Serial.printf("Deleting file: %s\r\n", path); - if (fs.remove(path)) { - Serial.println("- file deleted"); - } else { - Serial.println("- delete failed"); - } -} - -// SPIFFS-like write and delete file - -// See: https://github.com/esp8266/Arduino/blob/master/libraries/LittleFS/src/LittleFS.cpp#L60 -void writeFile2(fs::FS &fs, const char *path, const char *message) { - if (!fs.exists(path)) { - if (strchr(path, '/')) { - Serial.printf("Create missing folders of: %s\r\n", path); - char *pathStr = strdup(path); - if (pathStr) { - char *ptr = strchr(pathStr, '/'); - while (ptr) { - *ptr = 0; - fs.mkdir(pathStr); - *ptr = '/'; - ptr = strchr(ptr + 1, '/'); - } - } - free(pathStr); - } - } - - Serial.printf("Writing file to: %s\r\n", path); - File file = fs.open(path, FILE_WRITE); - if (!file) { - Serial.println("- failed to open file for writing"); - return; - } - if (file.print(message)) { - Serial.println("- file written"); - } else { - Serial.println("- write failed"); - } - file.close(); -} - -// See: https://github.com/esp8266/Arduino/blob/master/libraries/LittleFS/src/LittleFS.h#L149 -void deleteFile2(fs::FS &fs, const char *path) { - Serial.printf("Deleting file and empty folders on path: %s\r\n", path); - - if (fs.remove(path)) { - Serial.println("- file deleted"); - } else { - Serial.println("- delete failed"); - } - - char *pathStr = strdup(path); - if (pathStr) { - char *ptr = strrchr(pathStr, '/'); - if (ptr) { - Serial.printf("Removing all empty folders on path: %s\r\n", path); - } - while (ptr) { - *ptr = 0; - fs.rmdir(pathStr); - ptr = strrchr(pathStr, '/'); - } - free(pathStr); - } -} - -void testFileIO(fs::FS &fs, const char *path) { - Serial.printf("Testing file I/O with %s\r\n", path); - - static uint8_t buf[512]; - size_t len = 0; - File file = fs.open(path, FILE_WRITE); - if (!file) { - Serial.println("- failed to open file for writing"); - return; - } - - size_t i; - Serial.print("- writing"); - uint32_t start = millis(); - for (i = 0; i < 2048; i++) { - if ((i & 0x001F) == 0x001F) { - Serial.print("."); - } - file.write(buf, 512); - } - Serial.println(""); - uint32_t end = millis() - start; - Serial.printf(" - %u bytes written in %u ms\r\n", 2048 * 512, end); - file.close(); - - file = fs.open(path); - start = millis(); - end = start; - i = 0; - if (file && !file.isDirectory()) { - len = file.size(); - size_t flen = len; - start = millis(); - Serial.print("- reading"); - while (len) { - size_t toRead = len; - if (toRead > 512) { - toRead = 512; - } - file.read(buf, toRead); - if ((i++ & 0x001F) == 0x001F) { - Serial.print("."); - } - len -= toRead; - } - Serial.println(""); - end = millis() - start; - Serial.printf("- %u bytes read in %u ms\r\n", flen, end); - file.close(); - } else { - Serial.println("- failed to open file for reading"); - } -} - -void setup() { - Serial.begin(115200); - if (!LittleFS.begin(FORMAT_LITTLEFS_IF_FAILED)) { - Serial.println("LittleFS Mount Failed"); - return; - } - - listDir(LittleFS, "/", 0); - createDir(LittleFS, "/mydir"); - writeFile(LittleFS, "/mydir/hello2.txt", "Hello2"); - //writeFile(LittleFS, "/mydir/newdir2/newdir3/hello3.txt", "Hello3"); - writeFile2(LittleFS, "/mydir/newdir2/newdir3/hello3.txt", "Hello3"); - listDir(LittleFS, "/", 3); - deleteFile(LittleFS, "/mydir/hello2.txt"); - //deleteFile(LittleFS, "/mydir/newdir2/newdir3/hello3.txt"); - deleteFile2(LittleFS, "/mydir/newdir2/newdir3/hello3.txt"); - removeDir(LittleFS, "/mydir"); - listDir(LittleFS, "/", 3); - writeFile(LittleFS, "/hello.txt", "Hello "); - appendFile(LittleFS, "/hello.txt", "World!\r\n"); - readFile(LittleFS, "/hello.txt"); - renameFile(LittleFS, "/hello.txt", "/foo.txt"); - readFile(LittleFS, "/foo.txt"); - deleteFile(LittleFS, "/foo.txt"); - testFileIO(LittleFS, "/test.txt"); - deleteFile(LittleFS, "/test.txt"); - - Serial.println("Test complete"); -} - -void loop() {} diff --git a/libraries/NetworkClientSecure/README.md b/libraries/NetworkClientSecure/README.md index d028158730d..f83cf246287 100644 --- a/libraries/NetworkClientSecure/README.md +++ b/libraries/NetworkClientSecure/README.md @@ -32,25 +32,11 @@ This method is similar to the single root certificate verification above, but it root certificates from Mozilla to authenticate against, while the previous method only accepts a single certificate for a given server. This allows the client to connect to all public SSL servers. -To use this feature in PlatformIO: -1. create a certificate bundle as described in the document below, or obtain a pre-built one you trust: -https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/protocols/esp_crt_bundle.html -(gen_crt_bundle.py can be found in the /tools folder) - a. note: the full bundle will take up around 64k of flash space, but has minimal RAM usage, as only - the index of the certificates is kept in RAM -2. Place the bundle under the file name "data/cert/x509_crt_bundle.bin" in your platformio project -3. add "board_build.embed_files = data/cert/x509_crt_bundle.bin" in your platformio.ini -4. add the following global declaration in your project: - extern const uint8_t rootca_crt_bundle_start[] asm("_binary_data_cert_x509_crt_bundle_bin_start"); -5. before initiating the first SSL connection, call - my_client.setCACertBundle(rootca_crt_bundle_start); - To use this feature in Arduino IDE: If the Arduino IDE added support for embedding files in the meantime, then follow the instructions above. -If not, you have three choices: -1. convert your project to PlatformIO -2. create a makefile where you can add the idf_component_register() declaration to include the certificate bundle -3. Store the bundle as a SPIFFS file, but then you have to load it into RAM in runtime and waste 64k of precious memory +If not, you have two choices: +1. create a makefile where you can add the idf_component_register() declaration to include the certificate bundle +2. Store the bundle as a SPIFFS file, but then you have to load it into RAM in runtime and waste 64k of precious memory Using a root CA cert and client cert/keys ----------------------------------------- diff --git a/libraries/WebServer/examples/MultiHomedServers/README.md b/libraries/WebServer/examples/MultiHomedServers/README.md index 83ec6223850..04b96dfbd53 100644 --- a/libraries/WebServer/examples/MultiHomedServers/README.md +++ b/libraries/WebServer/examples/MultiHomedServers/README.md @@ -67,10 +67,6 @@ To get more information about the Espressif boards see [Espressif Development Ki * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - ## Example Log Output ``` diff --git a/libraries/WiFi/examples/FTM/FTM_Initiator/README.md b/libraries/WiFi/examples/FTM/FTM_Initiator/README.md index 3558f75d372..b9c7f8d438d 100644 --- a/libraries/WiFi/examples/FTM/FTM_Initiator/README.md +++ b/libraries/WiFi/examples/FTM/FTM_Initiator/README.md @@ -55,10 +55,6 @@ To get more information about the Espressif boards see [Espressif Development Ki * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. - ## Log Output Expected log output: diff --git a/libraries/WiFi/examples/FTM/FTM_Responder/README.md b/libraries/WiFi/examples/FTM/FTM_Responder/README.md index feede0867f3..fdcf1ab921b 100644 --- a/libraries/WiFi/examples/FTM/FTM_Responder/README.md +++ b/libraries/WiFi/examples/FTM/FTM_Responder/README.md @@ -48,10 +48,6 @@ To get more information about the Espressif boards see [Espressif Development Ki * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. - ## Log Output Expected log output: diff --git a/libraries/WiFi/examples/WiFiClient/README.md b/libraries/WiFi/examples/WiFiClient/README.md index 8b6a5d9caeb..9d3698a543a 100644 --- a/libraries/WiFi/examples/WiFiClient/README.md +++ b/libraries/WiFi/examples/WiFiClient/README.md @@ -61,10 +61,6 @@ To get more information about the Espressif boards see [Espressif Development Ki * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - ## Example Log Output The initial output which is common for all examples can be ignored: diff --git a/libraries/WiFi/examples/WiFiClientConnect/README.md b/libraries/WiFi/examples/WiFiClientConnect/README.md index eab02b674ff..939d44c5b76 100644 --- a/libraries/WiFi/examples/WiFiClientConnect/README.md +++ b/libraries/WiFi/examples/WiFiClientConnect/README.md @@ -18,10 +18,6 @@ Currently, this example supports the following targets. * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port`` option on the `platformio.ini` file. - ## Example/Log Output ``` diff --git a/libraries/WiFi/examples/WiFiScan/README.md b/libraries/WiFi/examples/WiFiScan/README.md index ec39cc6c639..f1268f21b5c 100644 --- a/libraries/WiFi/examples/WiFiScan/README.md +++ b/libraries/WiFi/examples/WiFiScan/README.md @@ -18,10 +18,6 @@ Currently, this example supports the following targets. * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. - ## Example/Log Output ``` diff --git a/libraries/WiFi/examples/WiFiScanAsync/README.md b/libraries/WiFi/examples/WiFiScanAsync/README.md index a557173c10f..26120aaa31c 100644 --- a/libraries/WiFi/examples/WiFiScanAsync/README.md +++ b/libraries/WiFi/examples/WiFiScanAsync/README.md @@ -18,10 +18,6 @@ Currently, this example supports the following targets. * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. - ## Example/Log Output ``` diff --git a/libraries/WiFi/examples/WiFiScanDualAntenna/README.md b/libraries/WiFi/examples/WiFiScanDualAntenna/README.md index f7ec7cc3ef9..9a6611149d0 100644 --- a/libraries/WiFi/examples/WiFiScanDualAntenna/README.md +++ b/libraries/WiFi/examples/WiFiScanDualAntenna/README.md @@ -17,10 +17,6 @@ This example is compatible with the ESP32-WROOM-DA. * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or set the `upload_port` option on the `platformio.ini` file. - ## Example/Log Output ``` diff --git a/libraries/WiFi/examples/WiFiScanTime/README.md b/libraries/WiFi/examples/WiFiScanTime/README.md index f56ba893925..7be0e05d4fe 100644 --- a/libraries/WiFi/examples/WiFiScanTime/README.md +++ b/libraries/WiFi/examples/WiFiScanTime/README.md @@ -18,10 +18,6 @@ Currently, this example supports the following targets. * Before Compile/Verify, select the correct board: `Tools -> Board`. * Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. -#### Using Platform IO - -* Select the COM port: `Devices` or setting the `upload_port` option on the `platformio.ini` file. - ## Example/Log Output ``` From c03a57470c68249b2f58ff5f4ed23a3d17d83bc3 Mon Sep 17 00:00:00 2001 From: Rodrigo Garcia Date: Fri, 29 Nov 2024 19:21:39 -0300 Subject: [PATCH 4/7] fix(support): left over in documentation. --- docs/en/tutorials/blink.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/en/tutorials/blink.rst b/docs/en/tutorials/blink.rst index 5d6f13c8d17..f4a53ec945d 100644 --- a/docs/en/tutorials/blink.rst +++ b/docs/en/tutorials/blink.rst @@ -7,7 +7,7 @@ Introduction This is the interactive blink tutorial using `Wokwi`_. For this tutorial, you don't need the ESP32 board or the Arduino toolchain. -.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use it on the `Arduino IDE` _. +.. note:: If you don't want to use this tutorial with the simulation, you can copy and paste the :ref:`blink_example_code` from `Wokwi`_ editor and use it on the `Arduino IDE`. About this Tutorial ------------------- From d0b2c59c9c3488b103e609e577686610b996a6e7 Mon Sep 17 00:00:00 2001 From: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> Date: Mon, 2 Dec 2024 18:37:56 -0300 Subject: [PATCH 5/7] Revert "feat(support): toll and ci changes" This reverts commit 857935c31442fa0d37a790edd09241e3d076d790. --- .github/ISSUE_TEMPLATE/Issue-report.yml | 2 +- .github/scripts/install-platformio-esp32.sh | 170 +++++++++++++ .github/scripts/on-push.sh | 81 ++++--- .github/scripts/on-release.sh | 1 + .github/scripts/set_push_chunks.sh | 1 + .github/workflows/push.yml | 30 +++ platform.txt | 1 + tools/platformio-build.py | 251 ++++++++++++++++++++ 8 files changed, 507 insertions(+), 30 deletions(-) create mode 100755 .github/scripts/install-platformio-esp32.sh create mode 100644 tools/platformio-build.py diff --git a/.github/ISSUE_TEMPLATE/Issue-report.yml b/.github/ISSUE_TEMPLATE/Issue-report.yml index acbd9a3c29a..d5b756085c7 100644 --- a/.github/ISSUE_TEMPLATE/Issue-report.yml +++ b/.github/ISSUE_TEMPLATE/Issue-report.yml @@ -75,7 +75,7 @@ body: attributes: label: IDE Name description: What IDE are you using? - placeholder: eg. Arduino IDE, VSCode, Sloeber... + placeholder: eg. Arduino IDE, PlatformIO, Sloeber... validations: required: true - type: input diff --git a/.github/scripts/install-platformio-esp32.sh b/.github/scripts/install-platformio-esp32.sh new file mode 100755 index 00000000000..80c668bdc0e --- /dev/null +++ b/.github/scripts/install-platformio-esp32.sh @@ -0,0 +1,170 @@ +#!/bin/bash + +export PLATFORMIO_ESP32_PATH="$HOME/.platformio/packages/framework-arduinoespressif32" +PLATFORMIO_ESP32_URL="https://github.com/platformio/platform-espressif32.git" + +TOOLCHAIN_VERSION="12.2.0+20230208" +ESPTOOLPY_VERSION="~1.40501.0" +ESPRESSIF_ORGANIZATION_NAME="espressif" +SDKCONFIG_DIR="$PLATFORMIO_ESP32_PATH/tools/esp32-arduino-libs" +SCRIPTS_DIR="./.github/scripts" +COUNT_SKETCHES="${SCRIPTS_DIR}/sketch_utils.sh count" +CHECK_REQUIREMENTS="${SCRIPTS_DIR}/sketch_utils.sh check_requirements" + +echo "Installing Python Wheel ..." +pip install wheel > /dev/null 2>&1 + +echo "Installing PlatformIO ..." +pip install -U https://github.com/platformio/platformio/archive/master.zip > /dev/null 2>&1 + +echo "Installing Platform ESP32 ..." +python -m platformio platform install $PLATFORMIO_ESP32_URL > /dev/null 2>&1 + +echo "Replacing the package versions ..." +replace_script="import json; import os;" +replace_script+="fp=open(os.path.expanduser('~/.platformio/platforms/espressif32/platform.json'), 'r+');" +replace_script+="data=json.load(fp);" +# Use framework sources from the repository +replace_script+="data['packages']['framework-arduinoespressif32']['version'] = '*';" +replace_script+="del data['packages']['framework-arduinoespressif32']['owner'];" +# Use toolchain packages from the "espressif" organization +replace_script+="data['packages']['toolchain-xtensa-esp32']['owner']='$ESPRESSIF_ORGANIZATION_NAME';" +replace_script+="data['packages']['toolchain-xtensa-esp32s2']['owner']='$ESPRESSIF_ORGANIZATION_NAME';" +replace_script+="data['packages']['toolchain-riscv32-esp']['owner']='$ESPRESSIF_ORGANIZATION_NAME';" +# Update versions to use the upstream +replace_script+="data['packages']['toolchain-xtensa-esp32']['version']='$TOOLCHAIN_VERSION';" +replace_script+="data['packages']['toolchain-xtensa-esp32s2']['version']='$TOOLCHAIN_VERSION';" +replace_script+="data['packages']['toolchain-xtensa-esp32s3']['version']='$TOOLCHAIN_VERSION';" +replace_script+="data['packages']['toolchain-riscv32-esp']['version']='$TOOLCHAIN_VERSION';" +# Add new "framework-arduinoespressif32-libs" package +# Read "package_esp32_index.template.json" to extract a url to a zip package for "esp32-arduino-libs" +replace_script+="fpackage=open(os.path.join('package', 'package_esp32_index.template.json'), 'r+');" +replace_script+="package_data=json.load(fpackage);" +replace_script+="fpackage.close();" +replace_script+="libs_package_archive_url=next(next(system['url'] for system in tool['systems'] if system['host'] == 'x86_64-pc-linux-gnu') for tool in package_data['packages'][0]['tools'] if tool['name'] == 'esp32-arduino-libs');" +replace_script+="data['packages'].update({'framework-arduinoespressif32-libs':{'type':'framework','optional':False,'version':libs_package_archive_url}});" +replace_script+="data['packages']['toolchain-xtensa-esp32'].update({'optional':False});" +# esptool.py may require an upstream version (for now platformio is the owner) +replace_script+="data['packages']['tool-esptoolpy']['version']='$ESPTOOLPY_VERSION';" +# Save results +replace_script+="fp.seek(0);fp.truncate();json.dump(data, fp, indent=2);fp.close()" +python -c "$replace_script" + +if [ "$GITHUB_REPOSITORY" == "espressif/arduino-esp32" ]; then + echo "Linking Core..." + ln -s $GITHUB_WORKSPACE "$PLATFORMIO_ESP32_PATH" +else + echo "Cloning Core Repository ..." + git clone --recursive https://github.com/espressif/arduino-esp32.git "$PLATFORMIO_ESP32_PATH" > /dev/null 2>&1 +fi + +echo "PlatformIO for ESP32 has been installed" +echo "" + +function build_pio_sketch(){ # build_pio_sketch + if [ "$#" -lt 3 ]; then + echo "ERROR: Illegal number of parameters" + echo "USAGE: build_pio_sketch " + return 1 + fi + + local board="$1" + local options="$2" + local sketch="$3" + local sketch_dir=$(dirname "$sketch") + echo "" + echo "Compiling '"$(basename "$sketch")"' ..." + python -m platformio ci --board "$board" "$sketch_dir" --project-option="$options" +} + +function build_pio_sketches(){ # build_pio_sketches + if [ "$#" -lt 3 ]; then + echo "ERROR: Illegal number of parameters" + echo "USAGE: build_pio_sketches [ ]" + return 1 + fi + + local board=$1 + local options="$2" + local examples=$3 + local chunk_idex=$4 + local chunks_num=$5 + + if [ "$#" -lt 5 ]; then + chunk_idex="0" + chunks_num="1" + fi + + if [ "$chunks_num" -le 0 ]; then + echo "ERROR: Chunks count must be positive number" + return 1 + fi + if [ "$chunk_idex" -ge "$chunks_num" ]; then + echo "ERROR: Chunk index must be less than chunks count" + return 1 + fi + + set +e + ${COUNT_SKETCHES} "$examples" "esp32" + local sketchcount=$? + set -e + local sketches=$(cat sketches.txt) + rm -rf sketches.txt + + local chunk_size=$(( $sketchcount / $chunks_num )) + local all_chunks=$(( $chunks_num * $chunk_size )) + if [ "$all_chunks" -lt "$sketchcount" ]; then + chunk_size=$(( $chunk_size + 1 )) + fi + + local start_index=$(( $chunk_idex * $chunk_size )) + if [ "$sketchcount" -le "$start_index" ]; then + echo "Skipping job" + return 0 + fi + + local end_index=$(( $(( $chunk_idex + 1 )) * $chunk_size )) + if [ "$end_index" -gt "$sketchcount" ]; then + end_index=$sketchcount + fi + + local start_num=$(( $start_index + 1 )) + echo "Found $sketchcount Sketches"; + echo "Chunk Count : $chunks_num" + echo "Chunk Size : $chunk_size" + echo "Start Sketch: $start_num" + echo "End Sketch : $end_index" + + local sketchnum=0 + for sketch in $sketches; do + local sketchdir=$(dirname $sketch) + local sketchdirname=$(basename $sketchdir) + local sketchname=$(basename $sketch) + if [[ "$sketchdirname.ino" != "$sketchname" ]]; then + continue + elif [ -f $sketchdir/ci.json ]; then + # If the target is listed as false, skip the sketch. Otherwise, include it. + is_target=$(jq -r '.targets[esp32]' $sketchdir/ci.json) + if [[ "$is_target" == "false" ]]; then + continue + fi + + local has_requirements=$(${CHECK_REQUIREMENTS} $sketchdir "$SDKCONFIG_DIR/esp32/sdkconfig") + if [ "$has_requirements" == "0" ]; then + continue + fi + fi + + sketchnum=$(($sketchnum + 1)) + if [ "$sketchnum" -le "$start_index" ] \ + || [ "$sketchnum" -gt "$end_index" ]; then + continue + fi + build_pio_sketch "$board" "$options" "$sketch" + local result=$? + if [ $result -ne 0 ]; then + return $result + fi + done + return 0 +} diff --git a/.github/scripts/on-push.sh b/.github/scripts/on-push.sh index 7f436c7b0ee..08ff505f1c0 100755 --- a/.github/scripts/on-push.sh +++ b/.github/scripts/on-push.sh @@ -54,11 +54,14 @@ CHUNK_INDEX=$1 CHUNKS_CNT=$2 BUILD_LOG=$3 SKETCHES_FILE=$4 +BUILD_PIO=0 if [ "$#" -lt 2 ] || [ "$CHUNKS_CNT" -le 0 ]; then CHUNK_INDEX=0 CHUNKS_CNT=1 elif [ "$CHUNK_INDEX" -gt "$CHUNKS_CNT" ] && [ "$CHUNKS_CNT" -ge 2 ]; then CHUNK_INDEX=$CHUNKS_CNT +elif [ "$CHUNK_INDEX" -eq "$CHUNKS_CNT" ]; then + BUILD_PIO=1 fi if [ -z "$BUILD_LOG" ] || [ "$BUILD_LOG" -le 0 ]; then @@ -69,34 +72,54 @@ fi #git -C "$GITHUB_WORKSPACE" submodule update --init --recursive > /dev/null 2>&1 SCRIPTS_DIR="./.github/scripts" -source ${SCRIPTS_DIR}/install-arduino-cli.sh -source ${SCRIPTS_DIR}/install-arduino-core-esp32.sh - -SKETCHES_ESP32="\ - $ARDUINO_ESP32_PATH/libraries/NetworkClientSecure/examples/WiFiClientSecure/WiFiClientSecure.ino\ - $ARDUINO_ESP32_PATH/libraries/BLE/examples/Server/Server.ino\ - $ARDUINO_ESP32_PATH/libraries/ESP32/examples/Camera/CameraWebServer/CameraWebServer.ino\ - $ARDUINO_ESP32_PATH/libraries/Insights/examples/MinimalDiagnostics/MinimalDiagnostics.ino\ -" -#create sizes_file -sizes_file="$GITHUB_WORKSPACE/cli_compile_$CHUNK_INDEX.json" - -if [ "$BUILD_LOG" -eq 1 ]; then - #create sizes_file and echo start of JSON array with "boards" key - echo "{\"boards\": [" > $sizes_file -fi +if [ "$BUILD_PIO" -eq 0 ]; then + source ${SCRIPTS_DIR}/install-arduino-cli.sh + source ${SCRIPTS_DIR}/install-arduino-core-esp32.sh + + SKETCHES_ESP32="\ + $ARDUINO_ESP32_PATH/libraries/NetworkClientSecure/examples/WiFiClientSecure/WiFiClientSecure.ino\ + $ARDUINO_ESP32_PATH/libraries/BLE/examples/Server/Server.ino\ + $ARDUINO_ESP32_PATH/libraries/ESP32/examples/Camera/CameraWebServer/CameraWebServer.ino\ + $ARDUINO_ESP32_PATH/libraries/Insights/examples/MinimalDiagnostics/MinimalDiagnostics.ino\ + " + #create sizes_file + sizes_file="$GITHUB_WORKSPACE/cli_compile_$CHUNK_INDEX.json" + + if [ "$BUILD_LOG" -eq 1 ]; then + #create sizes_file and echo start of JSON array with "boards" key + echo "{\"boards\": [" > $sizes_file + fi -#build sketches for different targets -build "esp32s3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" -build "esp32s2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" -build "esp32c3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" -build "esp32c6" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" -build "esp32h2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" -build "esp32" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" - -if [ "$BUILD_LOG" -eq 1 ]; then - #remove last comma from the last JSON object - sed -i '$ s/,$//' "$sizes_file" - #echo end of JSON array - echo "]}" >> $sizes_file + #build sketches for different targets + build "esp32s3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" + build "esp32s2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" + build "esp32c3" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" + build "esp32c6" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" + build "esp32h2" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" + build "esp32" "$CHUNK_INDEX" "$CHUNKS_CNT" "$BUILD_LOG" "$SKETCHES_FILE" "$SKETCHES_ESP32" + + if [ "$BUILD_LOG" -eq 1 ]; then + #remove last comma from the last JSON object + sed -i '$ s/,$//' "$sizes_file" + #echo end of JSON array + echo "]}" >> $sizes_file + fi +else + source ${SCRIPTS_DIR}/install-platformio-esp32.sh + # PlatformIO ESP32 Test + BOARD="esp32dev" + OPTIONS="board_build.partitions = huge_app.csv" + build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/WiFi/examples/WiFiClient/WiFiClient.ino" && \ + build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/NetworkClientSecure/examples/WiFiClientSecure/WiFiClientSecure.ino" && \ + build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/BluetoothSerial/examples/SerialToSerialBT/SerialToSerialBT.ino" && \ + build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/BLE/examples/Server/Server.ino" && \ + build_pio_sketch "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries/ESP32/examples/Camera/CameraWebServer/CameraWebServer.ino" + + # Basic sanity testing for other series + for board in "esp32-c3-devkitm-1" "esp32-s2-saola-1" "esp32-s3-devkitc-1" + do + python -m platformio ci --board "$board" "$PLATFORMIO_ESP32_PATH/libraries/WiFi/examples/WiFiClient" --project-option="board_build.partitions = huge_app.csv" + done + + #build_pio_sketches "$BOARD" "$OPTIONS" "$PLATFORMIO_ESP32_PATH/libraries" fi diff --git a/.github/scripts/on-release.sh b/.github/scripts/on-release.sh index 2308717e9d8..e0dd7b752c5 100755 --- a/.github/scripts/on-release.sh +++ b/.github/scripts/on-release.sh @@ -207,6 +207,7 @@ cp -f "$GITHUB_WORKSPACE/tools/gen_insights_package.py" "$PKG_DIR/tools/" cp -f "$GITHUB_WORKSPACE/tools/gen_insights_package.exe" "$PKG_DIR/tools/" cp -Rf "$GITHUB_WORKSPACE/tools/partitions" "$PKG_DIR/tools/" cp -Rf "$GITHUB_WORKSPACE/tools/ide-debug" "$PKG_DIR/tools/" +cp -f "$GITHUB_WORKSPACE/tools/platformio-build.py" "$PKG_DIR/tools/" # Remove unnecessary files in the package folder echo "Cleaning up folders ..." diff --git a/.github/scripts/set_push_chunks.sh b/.github/scripts/set_push_chunks.sh index 3e3dd89f3ae..11a93a7159d 100644 --- a/.github/scripts/set_push_chunks.sh +++ b/.github/scripts/set_push_chunks.sh @@ -78,5 +78,6 @@ echo "build_all=$build_all" >> $GITHUB_OUTPUT echo "build_libraries=$BUILD_LIBRARIES" >> $GITHUB_OUTPUT echo "build_static_sketches=$BUILD_STATIC_SKETCHES" >> $GITHUB_OUTPUT echo "build_idf=$BUILD_IDF" >> $GITHUB_OUTPUT +echo "build_platformio=$BUILD_PLATFORMIO" >> $GITHUB_OUTPUT echo "chunk_count=$chunks_count" >> $GITHUB_OUTPUT echo "chunks=$chunks" >> $GITHUB_OUTPUT diff --git a/.github/workflows/push.yml b/.github/workflows/push.yml index 899a0fe7b88..82159e1b8a4 100644 --- a/.github/workflows/push.yml +++ b/.github/workflows/push.yml @@ -61,6 +61,7 @@ jobs: build_libraries: ${{ steps.set-chunks.outputs.build_libraries }} build_static_sketches: ${{ steps.set-chunks.outputs.build_static_sketches }} build_idf: ${{ steps.set-chunks.outputs.build_idf }} + build_platformio: ${{ steps.set-chunks.outputs.build_platformio }} chunk_count: ${{ steps.set-chunks.outputs.chunk_count }} chunks: ${{ steps.set-chunks.outputs.chunks }} steps: @@ -76,9 +77,11 @@ jobs: files_yaml: | core: - '.github/**' + - '!.github/scripts/install-platformio-esp32.sh' - 'cores/**' - 'package/**' - 'tools/**' + - '!tools/platformio-build.py' - 'platform.txt' - 'programmers.txt' - "variants/esp32/**/*" @@ -107,6 +110,10 @@ jobs: - 'Kconfig.projbuild' - 'CMakeLists.txt' - "variants/esp32c2/**/*" + platformio: + - 'package.json' + - '.github/scripts/install-platformio-esp32.sh' + - 'tools/platformio-build.py' - name: Set chunks id: set-chunks @@ -114,6 +121,7 @@ jobs: LIB_FILES: ${{ steps.changed-files.outputs.libraries_all_changed_files }} IS_PR: ${{ github.event_name == 'pull_request' }} MAX_CHUNKS: ${{ env.MAX_CHUNKS }} + BUILD_PLATFORMIO: ${{ steps.changed-files.outputs.platformio_any_changed == 'true' }} BUILD_IDF: ${{ steps.changed-files.outputs.idf_any_changed == 'true' }} BUILD_LIBRARIES: ${{ steps.changed-files.outputs.libraries_any_changed == 'true' }} BUILD_STATIC_SKETCHES: ${{ steps.changed-files.outputs.static_sketeches_any_changed == 'true' }} @@ -204,6 +212,28 @@ jobs: - name: Build Sketches run: bash ./.github/scripts/on-push.sh + # PlatformIO on Windows, Ubuntu and Mac + build-platformio: + name: PlatformIO on ${{ matrix.os }} + needs: gen-chunks + if: | + needs.gen-chunks.outputs.build_all == 'true' || + needs.gen-chunks.outputs.build_static_sketches == 'true' || + needs.gen-chunks.outputs.build_platformio == 'true' + runs-on: ${{ matrix.os }} + strategy: + fail-fast: false + matrix: + os: [ubuntu-latest, windows-latest, macOS-latest] + + steps: + - uses: actions/checkout@v4 + - uses: actions/setup-python@v5 + with: + python-version: '3.x' + - name: Build Sketches + run: bash ./.github/scripts/on-push.sh 1 1 #equal and non-zero to trigger PIO + build-esp-idf-component: name: Build with ESP-IDF ${{ matrix.idf_ver }} for ${{ matrix.idf_target }} needs: gen-chunks diff --git a/platform.txt b/platform.txt index ec1245c9b92..d1c3fb3a3dd 100644 --- a/platform.txt +++ b/platform.txt @@ -47,6 +47,7 @@ compiler.warning_flags.more=-Wall compiler.warning_flags.all=-Wall -Wextra # Additional flags specific to Arduino (not based on IDF flags). +# Update tools/platformio-build.py when changing these flags. compiler.common_werror_flags=-Werror=return-type # Compile Flags diff --git a/tools/platformio-build.py b/tools/platformio-build.py new file mode 100644 index 00000000000..1ece3afddff --- /dev/null +++ b/tools/platformio-build.py @@ -0,0 +1,251 @@ +# Copyright 2014-present PlatformIO +# +# Licensed under the Apache License, Version 2.0 (the "License"); +# you may not use this file except in compliance with the License. +# You may obtain a copy of the License at +# +# http://www.apache.org/licenses/LICENSE-2.0 +# +# Unless required by applicable law or agreed to in writing, software +# distributed under the License is distributed on an "AS IS" BASIS, +# WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. +# See the License for the specific language governing permissions and +# limitations under the License. + +""" +Arduino + +Arduino Wiring-based Framework allows writing cross-platform software to +control devices attached to a wide range of Arduino boards to create all +kinds of creative coding, interactive objects, spaces or physical experiences. + +http://arduino.cc/en/Reference/HomePage +""" + +# Extends: https://github.com/platformio/platform-espressif32/blob/develop/builder/main.py + +from os.path import abspath, basename, isdir, isfile, join +from copy import deepcopy +from SCons.Script import DefaultEnvironment, SConscript + +env = DefaultEnvironment() +platform = env.PioPlatform() +board_config = env.BoardConfig() +build_mcu = board_config.get("build.mcu", "").lower() +partitions_name = board_config.get("build.partitions", board_config.get("build.arduino.partitions", "")) + +FRAMEWORK_DIR = platform.get_package_dir("framework-arduinoespressif32") +FRAMEWORK_LIBS_DIR = platform.get_package_dir("framework-arduinoespressif32-libs") +assert isdir(FRAMEWORK_DIR) + + +# +# Helpers +# + + +def get_partition_table_csv(variants_dir): + fwpartitions_dir = join(FRAMEWORK_DIR, "tools", "partitions") + variant_partitions_dir = join(variants_dir, board_config.get("build.variant", "")) + + if partitions_name: + # A custom partitions file is selected + if isfile(env.subst(join(variant_partitions_dir, partitions_name))): + return join(variant_partitions_dir, partitions_name) + + return abspath( + join(fwpartitions_dir, partitions_name) + if isfile(env.subst(join(fwpartitions_dir, partitions_name))) + else partitions_name + ) + + variant_partitions = join(variant_partitions_dir, "partitions.csv") + return variant_partitions if isfile(env.subst(variant_partitions)) else join(fwpartitions_dir, "default.csv") + + +def get_bootloader_image(variants_dir): + bootloader_image_file = "bootloader.bin" + if partitions_name.endswith("tinyuf2.csv"): + bootloader_image_file = "bootloader-tinyuf2.bin" + + variant_bootloader = join( + variants_dir, + board_config.get("build.variant", ""), + board_config.get("build.arduino.custom_bootloader", bootloader_image_file), + ) + + return ( + variant_bootloader + if isfile(env.subst(variant_bootloader)) + else generate_bootloader_image( + join( + FRAMEWORK_LIBS_DIR, + build_mcu, + "bin", + "bootloader_${__get_board_boot_mode(__env__)}_${__get_board_f_boot(__env__)}.elf", + ) + ) + ) + + +def generate_bootloader_image(bootloader_elf): + bootloader_cmd = env.Command( + join("$BUILD_DIR", "bootloader.bin"), + bootloader_elf, + env.VerboseAction( + " ".join( + [ + '"$PYTHONEXE" "$OBJCOPY"', + "--chip", + build_mcu, + "elf2image", + "--flash_mode", + "${__get_board_flash_mode(__env__)}", + "--flash_freq", + "${__get_board_f_image(__env__)}", + "--flash_size", + board_config.get("upload.flash_size", "4MB"), + "-o", + "$TARGET", + "$SOURCES", + ] + ), + "Building $TARGET", + ), + ) + + env.Depends("$BUILD_DIR/$PROGNAME$PROGSUFFIX", bootloader_cmd) + + # Because the Command always returns a NodeList, we have to + # access the first element in the list to get the Node object + # that actually represents the bootloader image. + # Also, this file is later used in generic Python code, so the + # Node object in converted to a generic string + return str(bootloader_cmd[0]) + + +def add_tinyuf2_extra_image(): + tinuf2_image = board_config.get( + "upload.arduino.tinyuf2_image", + join(variants_dir, board_config.get("build.variant", ""), "tinyuf2.bin"), + ) + + # Add the UF2 image only if it exists and it's not already added + if not isfile(env.subst(tinuf2_image)): + print("Warning! The `%s` UF2 bootloader image doesn't exist" % env.subst(tinuf2_image)) + return + + if any("tinyuf2.bin" == basename(extra_image[1]) for extra_image in env.get("FLASH_EXTRA_IMAGES", [])): + print("Warning! An extra UF2 bootloader image is already added!") + return + + env.Append( + FLASH_EXTRA_IMAGES=[ + ( + board_config.get( + "upload.arduino.uf2_bootloader_offset", + ("0x2d0000" if env.subst("$BOARD").startswith("adafruit") else "0x410000"), + ), + tinuf2_image, + ), + ] + ) + + +# +# Run target-specific script to populate the environment with proper build flags +# + +SConscript( + join( + FRAMEWORK_LIBS_DIR, + build_mcu, + "platformio-build.py", + ) +) + +# +# Additional flags specific to Arduino core (not based on IDF) +# + +env.Append( + CFLAGS=["-Werror=return-type"], + CXXFLAGS=["-Werror=return-type"], +) + +# +# Target: Build Core Library +# + +# Set -DARDUINO_CORE_BUILD only for the core library +corelib_env = env.Clone() +corelib_env.Append(CPPDEFINES=["ARDUINO_CORE_BUILD"]) + +libs = [] + +variants_dir = join(FRAMEWORK_DIR, "variants") + +if "build.variants_dir" in board_config: + variants_dir = join("$PROJECT_DIR", board_config.get("build.variants_dir")) + +if "build.variant" in board_config: + env.Append(CPPPATH=[join(variants_dir, board_config.get("build.variant"))]) + corelib_env.Append(CPPPATH=[join(variants_dir, board_config.get("build.variant"))]) + corelib_env.BuildSources( + join("$BUILD_DIR", "FrameworkArduinoVariant"), + join(variants_dir, board_config.get("build.variant")), + ) + +libs.append( + corelib_env.BuildLibrary( + join("$BUILD_DIR", "FrameworkArduino"), + join(FRAMEWORK_DIR, "cores", board_config.get("build.core")), + ) +) + +env.Prepend(LIBS=libs) + +# +# Process framework extra images +# + +env.Append( + LIBSOURCE_DIRS=[join(FRAMEWORK_DIR, "libraries")], + FLASH_EXTRA_IMAGES=[ + ( + "0x1000" if build_mcu in ("esp32", "esp32s2") else "0x0000", + get_bootloader_image(variants_dir), + ), + ("0x8000", join(env.subst("$BUILD_DIR"), "partitions.bin")), + ("0xe000", join(FRAMEWORK_DIR, "tools", "partitions", "boot_app0.bin")), + ] + + [(offset, join(FRAMEWORK_DIR, img)) for offset, img in board_config.get("upload.arduino.flash_extra_images", [])], +) + +# Add an extra UF2 image if the 'TinyUF2' partition is selected +if partitions_name.endswith("tinyuf2.csv") or board_config.get("upload.arduino.tinyuf2_image", ""): + add_tinyuf2_extra_image() + +# +# Generate partition table +# + +env.Replace(PARTITIONS_TABLE_CSV=get_partition_table_csv(variants_dir)) + +partition_table = env.Command( + join("$BUILD_DIR", "partitions.bin"), + "$PARTITIONS_TABLE_CSV", + env.VerboseAction( + '"$PYTHONEXE" "%s" -q $SOURCE $TARGET' % join(FRAMEWORK_DIR, "tools", "gen_esp32part.py"), + "Generating partitions $TARGET", + ), +) +env.Depends("$BUILD_DIR/$PROGNAME$PROGSUFFIX", partition_table) + +# +# Adjust the `esptoolpy` command in the `ElfToBin` builder with firmware checksum offset +# + +action = deepcopy(env["BUILDERS"]["ElfToBin"].action) +action.cmd_list = env["BUILDERS"]["ElfToBin"].action.cmd_list.replace("-o", "--elf-sha256-offset 0xb0 -o") +env["BUILDERS"]["ElfToBin"].action = action From 47c61465679c3e947ad02dece7a72ca4065d2d77 Mon Sep 17 00:00:00 2001 From: Lucas Saavedra Vaz <32426024+lucasssvaz@users.noreply.github.com> Date: Mon, 2 Dec 2024 18:39:19 -0300 Subject: [PATCH 6/7] fix(template): Fix Issue Report Template --- .github/ISSUE_TEMPLATE/Issue-report.yml | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/.github/ISSUE_TEMPLATE/Issue-report.yml b/.github/ISSUE_TEMPLATE/Issue-report.yml index d5b756085c7..acbd9a3c29a 100644 --- a/.github/ISSUE_TEMPLATE/Issue-report.yml +++ b/.github/ISSUE_TEMPLATE/Issue-report.yml @@ -75,7 +75,7 @@ body: attributes: label: IDE Name description: What IDE are you using? - placeholder: eg. Arduino IDE, PlatformIO, Sloeber... + placeholder: eg. Arduino IDE, VSCode, Sloeber... validations: required: true - type: input From 723ad19f5c8c0a79b61a9816141a3bb4f4d7f1d3 Mon Sep 17 00:00:00 2001 From: "pre-commit-ci-lite[bot]" <117423508+pre-commit-ci-lite[bot]@users.noreply.github.com> Date: Tue, 3 Dec 2024 14:00:56 +0000 Subject: [PATCH 7/7] ci(pre-commit): Apply automatic fixes --- .../ESP32/examples/FreeRTOS/Mutex/README.md | 234 ++++++++--------- .../ESP32/examples/FreeRTOS/Queue/README.md | 142 +++++------ .../examples/FreeRTOS/Semaphore/README.md | 154 ++++++------ .../Template/ExampleTemplate/README.md | 238 +++++++++--------- 4 files changed, 384 insertions(+), 384 deletions(-) diff --git a/libraries/ESP32/examples/FreeRTOS/Mutex/README.md b/libraries/ESP32/examples/FreeRTOS/Mutex/README.md index 32c9f027bff..435528bd771 100644 --- a/libraries/ESP32/examples/FreeRTOS/Mutex/README.md +++ b/libraries/ESP32/examples/FreeRTOS/Mutex/README.md @@ -1,117 +1,117 @@ -# Mutex Example - -This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading. -Please refer to other examples in this folder to better understand the usage of tasks. -It is also advised to read the documentation on FreeRTOS web pages: -https://www.freertos.org/a00106.html - -This example creates 2 tasks with the same implementation - they write into a shared variable and then read it and check if it is the same as what they have written. -In single-thread programming like on Arduino this is of no concern and will be always ok, however when multi-threading is used the execution of the task is switched by the FreeRTOS and the value can be rewritten from another task before reading again. -The tasks print write and read operation - each in their column for better reading. Task 0 is on the left and Task 1 is on the right. -Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them. -Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches! - -### Theory: -Mutex is a specialized version of Semaphore (please see the Semaphore example for more info). -In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked). -When two or more processes access the same resource (variable, peripheral, etc) it might happen, for example, that when one task starts to read a variable and the operating system (FreeRTOS) will schedule the execution of another task -which will write to this variable and when the previous task runs again it will read something different. - -Mutexes and binary semaphores are very similar but have some subtle differences: -Mutexes include a priority inheritance mechanism, whereas binary semaphores do not. -This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better -choice for implementing simple mutual exclusion. -What is priority inheritance? -If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which -then tries to take the Mutex, the low-priority task will temporarily ‘inherit’ the high priority so a middle-priority task can't block the low-priority task, and thus also block the high priority task. -Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them. - -A mutex can also be recursive - if a task that holds the mutex takes it again, it will succeed, and the mutex will be released -for other tasks only when it is given the same number of times that it was taken. - -You can check the danger by commenting on the definition of USE_MUTEX which will disable the mutex and present the danger of concurrent access. - - -# Supported Targets - -This example supports all ESP32 SoCs. - -## How to Use Example - -Flash and observe the serial output. - -Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable. - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -## Example Log Output - -The expected output of shared variables protected by mutex demonstrates mutually exclusive access from tasks - they do not interrupt each other and do not rewrite the value before the other task has read it back. - -``` - Task 0 | Task 1 - | Starting - | 0 <- 227 - Starting | - | R: 227 - 227 <- 737 | - R: 737 | - | 737 <- 282 - | R: 282 - 282 <- 267 | -``` - -The output of unprotected access to shared variable - it happens often that a task is interrupted after writing and before reading the other task write a different value - a corruption occurred! - -``` - Task 0 | Task 1 - | Starting - | 0 <- 333 - Starting | - 333 <- 620 | - R: 620 | - 620 <- 244 | - | R: 244 - | Mismatch! - | 244 <- 131 - R: 131 | - Mismatch! | - 131 <- 584 | - | R: 584 - | Mismatch! - | 584 <- 134 - | R: 134 - | 134 <- 554 - R: 554 | - Mismatch! | - 554 <- 313 | -``` - -## Troubleshooting - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -## Contribute - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Mutex Example + +This example demonstrates the basic usage of FreeRTOS Mutually Exclusive Locks (Mutex) for securing access to shared resources in multi-threading. +Please refer to other examples in this folder to better understand the usage of tasks. +It is also advised to read the documentation on FreeRTOS web pages: +https://www.freertos.org/a00106.html + +This example creates 2 tasks with the same implementation - they write into a shared variable and then read it and check if it is the same as what they have written. +In single-thread programming like on Arduino this is of no concern and will be always ok, however when multi-threading is used the execution of the task is switched by the FreeRTOS and the value can be rewritten from another task before reading again. +The tasks print write and read operation - each in their column for better reading. Task 0 is on the left and Task 1 is on the right. +Watch the writes and read in secure mode when using the mutex (default) as the results are as you would expect them. +Then try to comment the USE_MUTEX and watch again - there will be a lot of mismatches! + +### Theory: +Mutex is a specialized version of Semaphore (please see the Semaphore example for more info). +In essence, the mutex is a variable whose value determines if the mute is taken (locked) or given (unlocked). +When two or more processes access the same resource (variable, peripheral, etc) it might happen, for example, that when one task starts to read a variable and the operating system (FreeRTOS) will schedule the execution of another task +which will write to this variable and when the previous task runs again it will read something different. + +Mutexes and binary semaphores are very similar but have some subtle differences: +Mutexes include a priority inheritance mechanism, whereas binary semaphores do not. +This makes binary semaphores the better choice for implementing synchronization (between tasks or between tasks and an interrupt), and mutexes the better +choice for implementing simple mutual exclusion. +What is priority inheritance? +If a low-priority task holds the Mutex but gets interrupted by a Higher priority task, which +then tries to take the Mutex, the low-priority task will temporarily ‘inherit’ the high priority so a middle-priority task can't block the low-priority task, and thus also block the high priority task. +Semaphores don't have the logic to handle this, in part because Semaphores aren't 'owned' by the task that takes them. + +A mutex can also be recursive - if a task that holds the mutex takes it again, it will succeed, and the mutex will be released +for other tasks only when it is given the same number of times that it was taken. + +You can check the danger by commenting on the definition of USE_MUTEX which will disable the mutex and present the danger of concurrent access. + + +# Supported Targets + +This example supports all ESP32 SoCs. + +## How to Use Example + +Flash and observe the serial output. + +Comment the `USE_MUTEX` definition, save and flash again and observe the behavior of unprotected access to the shared variable. + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example Log Output + +The expected output of shared variables protected by mutex demonstrates mutually exclusive access from tasks - they do not interrupt each other and do not rewrite the value before the other task has read it back. + +``` + Task 0 | Task 1 + | Starting + | 0 <- 227 + Starting | + | R: 227 + 227 <- 737 | + R: 737 | + | 737 <- 282 + | R: 282 + 282 <- 267 | +``` + +The output of unprotected access to shared variable - it happens often that a task is interrupted after writing and before reading the other task write a different value - a corruption occurred! + +``` + Task 0 | Task 1 + | Starting + | 0 <- 333 + Starting | + 333 <- 620 | + R: 620 | + 620 <- 244 | + | R: 244 + | Mismatch! + | 244 <- 131 + R: 131 | + Mismatch! | + 131 <- 584 | + | R: 584 + | Mismatch! + | 584 <- 134 + | R: 134 + | 134 <- 554 + R: 554 | + Mismatch! | + 554 <- 313 | +``` + +## Troubleshooting + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +## Contribute + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) diff --git a/libraries/ESP32/examples/FreeRTOS/Queue/README.md b/libraries/ESP32/examples/FreeRTOS/Queue/README.md index b1cc3f3e3ac..e81d6741e2a 100644 --- a/libraries/ESP32/examples/FreeRTOS/Queue/README.md +++ b/libraries/ESP32/examples/FreeRTOS/Queue/README.md @@ -1,71 +1,71 @@ -# Queue Example - -This example demonstrates the basic usage of FreeRTOS Queues which enables tasks to pass data between each other in a secure asynchronous way. -Please refer to other examples in this folder to better understand the usage of tasks. -It is also advised to read the documentation on FreeRTOS web pages: -[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) - -This example reads data received on the serial port (sent by the user) pass it via queue to another task which will send it back on Serial Output. - -### Theory: -A queue is a simple-to-use data structure (in the most basic way) controlled by `xQueueSend` and `xQueueReceive` functions. -Usually, one task writes into the queue and the other task reads from it. -Usage of queues enables the reading task to yield the CPU until there are data in the queue and therefore not waste precious computation time. - -# Supported Targets - -This example supports all ESP32 SoCs. - -## How to Use Example - -Flash and write anything to serial input. - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -## Example Log Output - -``` -Anything you write will return as echo. -Maximum line length is 63 characters (+ terminating '0'). -Anything longer will be sent as a separate line. - -``` -< Input text "Short input" - -``Echo line of size 11: "Short input"`` - -< Input text "An example of very long input which is longer than default 63 characters will be split." - -``` -Echo line of size 63: "An example of very long input which is longer than default 63 c" -Echo line of size 24: "haracters will be split." -``` - -## Troubleshooting - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -## Contribute - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Queue Example + +This example demonstrates the basic usage of FreeRTOS Queues which enables tasks to pass data between each other in a secure asynchronous way. +Please refer to other examples in this folder to better understand the usage of tasks. +It is also advised to read the documentation on FreeRTOS web pages: +[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) + +This example reads data received on the serial port (sent by the user) pass it via queue to another task which will send it back on Serial Output. + +### Theory: +A queue is a simple-to-use data structure (in the most basic way) controlled by `xQueueSend` and `xQueueReceive` functions. +Usually, one task writes into the queue and the other task reads from it. +Usage of queues enables the reading task to yield the CPU until there are data in the queue and therefore not waste precious computation time. + +# Supported Targets + +This example supports all ESP32 SoCs. + +## How to Use Example + +Flash and write anything to serial input. + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example Log Output + +``` +Anything you write will return as echo. +Maximum line length is 63 characters (+ terminating '0'). +Anything longer will be sent as a separate line. + +``` +< Input text "Short input" + +``Echo line of size 11: "Short input"`` + +< Input text "An example of very long input which is longer than default 63 characters will be split." + +``` +Echo line of size 63: "An example of very long input which is longer than default 63 c" +Echo line of size 24: "haracters will be split." +``` + +## Troubleshooting + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +## Contribute + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) diff --git a/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md b/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md index 0a076713e14..fcb38eed1d6 100644 --- a/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md +++ b/libraries/ESP32/examples/FreeRTOS/Semaphore/README.md @@ -1,77 +1,77 @@ -# Semaphore Example - -This example demonstrates the basic usage of FreeRTOS Semaphores and queue sets for coordination between tasks for multi-threading. -Please refer to other examples in this folder to better understand the usage of tasks. -It is also advised to read the documentation on FreeRTOS web pages: -[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) - -### Theory: -Semaphore is in essence a variable. Tasks can set the value, wait until one or more -semaphores are set and thus communicate between each other their state. -A binary semaphore is a semaphore that has a maximum count of 1, hence the 'binary' name. -A task can only 'take' the semaphore if it is available, and the semaphore is only available if its count is 1. - -Semaphores can be controlled by any number of tasks. If you use semaphore as a one-way -signalization with only one task giving and only one task taking there is a much faster option -called Task Notifications - please see FreeRTOS documentation and read more about them: [https://www.freertos.org/RTOS-task-notifications.html](https://www.freertos.org/RTOS-task-notifications.html) - -This example uses a semaphore to signal when a package is delivered to a warehouse by multiple -delivery trucks, and multiple workers are waiting to receive the package. - -# Supported Targets - -This example supports all ESP32 SoCs. - -## How to Use Example - -Read the code and try to understand it, then flash and observe the Serial output. - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -## Example Log Output - -``` -Anything you write will return as echo. -Maximum line length is 63 characters (+ terminating '0'). -Anything longer will be sent as a separate line. - -``` -< Input text "Short input" - -``Echo line of size 11: "Short input"`` - -< Input text "An example of very long input which is longer than default 63 characters will be split." - -``` -Echo line of size 63: "An example of very long input which is longer than default 63 c" -Echo line of size 24: "haracters will be split." -``` - -## Troubleshooting - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -## Contribute - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Semaphore Example + +This example demonstrates the basic usage of FreeRTOS Semaphores and queue sets for coordination between tasks for multi-threading. +Please refer to other examples in this folder to better understand the usage of tasks. +It is also advised to read the documentation on FreeRTOS web pages: +[https://www.freertos.org/a00106.html](https://www.freertos.org/a00106.html) + +### Theory: +Semaphore is in essence a variable. Tasks can set the value, wait until one or more +semaphores are set and thus communicate between each other their state. +A binary semaphore is a semaphore that has a maximum count of 1, hence the 'binary' name. +A task can only 'take' the semaphore if it is available, and the semaphore is only available if its count is 1. + +Semaphores can be controlled by any number of tasks. If you use semaphore as a one-way +signalization with only one task giving and only one task taking there is a much faster option +called Task Notifications - please see FreeRTOS documentation and read more about them: [https://www.freertos.org/RTOS-task-notifications.html](https://www.freertos.org/RTOS-task-notifications.html) + +This example uses a semaphore to signal when a package is delivered to a warehouse by multiple +delivery trucks, and multiple workers are waiting to receive the package. + +# Supported Targets + +This example supports all ESP32 SoCs. + +## How to Use Example + +Read the code and try to understand it, then flash and observe the Serial output. + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example Log Output + +``` +Anything you write will return as echo. +Maximum line length is 63 characters (+ terminating '0'). +Anything longer will be sent as a separate line. + +``` +< Input text "Short input" + +``Echo line of size 11: "Short input"`` + +< Input text "An example of very long input which is longer than default 63 characters will be split." + +``` +Echo line of size 63: "An example of very long input which is longer than default 63 c" +Echo line of size 24: "haracters will be split." +``` + +## Troubleshooting + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +## Contribute + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) diff --git a/libraries/ESP32/examples/Template/ExampleTemplate/README.md b/libraries/ESP32/examples/Template/ExampleTemplate/README.md index 4c4f497f43c..91b50967e9e 100644 --- a/libraries/ESP32/examples/Template/ExampleTemplate/README.md +++ b/libraries/ESP32/examples/Template/ExampleTemplate/README.md @@ -1,119 +1,119 @@ -# Arduino-ESP32 Example/Library Name ==(REQUIRED)== - -==*Add a brief description of this example/library here!*== - -This example/library demonstrates how to create a new example README file. - -# Supported Targets ==(REQUIRED)== - -==*Add the supported devices here!*== - -Currently, this example supports the following targets. - -| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | -| ----------------- | ----- | -------- | -------- | - -## How to Use Example/Library ==(OPTIONAL)== - -==*Add a brief description of how to use this example.*== - -* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). - -### Hardware Connection ==(OPTIONAL)== - -==*Add a brief description of wiring or any other hardware-specific connection.*== - -To use this example, you need to connect the LED to the `GPIOx`. - -SDCard GPIO connection scheme: - -| SDCard Pin | Function | GPIO | -| ----------- | -------- | ------ | -| 1 | CS | GPIO5 | -| 2 | DI/MOSI | GPIO23 | -| 3 | VSS/GND | GND | -| 4 | VDD/3V3 | 3V3 | -| 5 | SCLK | GPIO18 | -| 6 | VSS/GND | GND | -| 7 | DO/MISO | GPIO19 | - -To add images, please create a folder `_asset` inside the example folder to add the relevant images. - -### Configure the Project ==(OPTIONAL)== - -==*Add a brief description of this example here!*== - -Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`. - -#### Example for the GPIO4: - -==*Add some code explanation if relevant to the example.*== - -```cpp -// the setup function runs once when you press reset or power the board -void setup() { -// initialize digital pin 4 as an output. -pinMode(4, OUTPUT); -} -``` - -#### Using Arduino IDE - -To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). - -* Before Compile/Verify, select the correct board: `Tools -> Board`. -* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. - -## Example/Log Output ==(OPTIONAL)== - -==*Add the log/serial output here!*== - -``` -ets Jul 29 2019 12:21:46 - -rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) -configsip: 0, SPIWP:0xee -clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 -mode:DIO, clock div:1 -load:0x3fff0030,len:1412 -load:0x40078000,len:13400 -load:0x40080400,len:3672 -entry 0x400805f8 -ESP32 Chip model = ESP32-D0WDQ5 Rev 3 -This chip has 2 cores -Chip ID: 3957392 -``` - -## Troubleshooting ==(REQUIRED)== - -==*Add specific issues you may find by using this example here!*== - -***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** - -* **LED not blinking:** Check the wiring connection and the IO selection. -* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed. -* **COM port not detected:** Check the USB cable and the USB to Serial driver installation. - -If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). - -## Contribute ==(REQUIRED)== - -==*Do not change! Keep it as is.*== - -To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) - -If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! - -Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. - -## Resources ==(REQUIRED)== - -==*Do not change here! Keep it as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*== - -* Official ESP32 Forum: [Link](https://esp32.com) -* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) -* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) -* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) -* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) -* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) -* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com) +# Arduino-ESP32 Example/Library Name ==(REQUIRED)== + +==*Add a brief description of this example/library here!*== + +This example/library demonstrates how to create a new example README file. + +# Supported Targets ==(REQUIRED)== + +==*Add the supported devices here!*== + +Currently, this example supports the following targets. + +| Supported Targets | ESP32 | ESP32-S2 | ESP32-C3 | +| ----------------- | ----- | -------- | -------- | + +## How to Use Example/Library ==(OPTIONAL)== + +==*Add a brief description of how to use this example.*== + +* How to install the Arduino IDE: [Install Arduino IDE](https://github.com/espressif/arduino-esp32/tree/master/docs/arduino-ide). + +### Hardware Connection ==(OPTIONAL)== + +==*Add a brief description of wiring or any other hardware-specific connection.*== + +To use this example, you need to connect the LED to the `GPIOx`. + +SDCard GPIO connection scheme: + +| SDCard Pin | Function | GPIO | +| ----------- | -------- | ------ | +| 1 | CS | GPIO5 | +| 2 | DI/MOSI | GPIO23 | +| 3 | VSS/GND | GND | +| 4 | VDD/3V3 | 3V3 | +| 5 | SCLK | GPIO18 | +| 6 | VSS/GND | GND | +| 7 | DO/MISO | GPIO19 | + +To add images, please create a folder `_asset` inside the example folder to add the relevant images. + +### Configure the Project ==(OPTIONAL)== + +==*Add a brief description of this example here!*== + +Set the LED GPIO by changing the `LED_BUILTIN` value in the function `pinMode(LED_BUILTIN, OUTPUT);`. By default, the GPIO is: `GPIOx`. + +#### Example for the GPIO4: + +==*Add some code explanation if relevant to the example.*== + +```cpp +// the setup function runs once when you press reset or power the board +void setup() { +// initialize digital pin 4 as an output. +pinMode(4, OUTPUT); +} +``` + +#### Using Arduino IDE + +To get more information about the Espressif boards see [Espressif Development Kits](https://www.espressif.com/en/products/devkits). + +* Before Compile/Verify, select the correct board: `Tools -> Board`. +* Select the COM port: `Tools -> Port: xxx` where the `xxx` is the detected COM port. + +## Example/Log Output ==(OPTIONAL)== + +==*Add the log/serial output here!*== + +``` +ets Jul 29 2019 12:21:46 + +rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT) +configsip: 0, SPIWP:0xee +clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00 +mode:DIO, clock div:1 +load:0x3fff0030,len:1412 +load:0x40078000,len:13400 +load:0x40080400,len:3672 +entry 0x400805f8 +ESP32 Chip model = ESP32-D0WDQ5 Rev 3 +This chip has 2 cores +Chip ID: 3957392 +``` + +## Troubleshooting ==(REQUIRED)== + +==*Add specific issues you may find by using this example here!*== + +***Important: Make sure you are using a good quality USB cable and that you have a reliable power source*** + +* **LED not blinking:** Check the wiring connection and the IO selection. +* **Programming Fail:** If the programming/flash procedure fails, try reducing the serial connection speed. +* **COM port not detected:** Check the USB cable and the USB to Serial driver installation. + +If the error persists, you can ask for help at the official [ESP32 forum](https://esp32.com) or see [Contribute](#contribute). + +## Contribute ==(REQUIRED)== + +==*Do not change! Keep it as is.*== + +To know how to contribute to this project, see [How to contribute.](https://github.com/espressif/arduino-esp32/blob/master/CONTRIBUTING.rst) + +If you have any **feedback** or **issue** to report on this example/library, please open an issue or fix it by creating a new PR. Contributions are more than welcome! + +Before creating a new issue, be sure to try Troubleshooting and check if the same issue was already created by someone else. + +## Resources ==(REQUIRED)== + +==*Do not change here! Keep it as is or add only relevant documents/info for this example. Do not add any purchase link/marketing stuff*== + +* Official ESP32 Forum: [Link](https://esp32.com) +* Arduino-ESP32 Official Repository: [espressif/arduino-esp32](https://github.com/espressif/arduino-esp32) +* ESP32 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32_datasheet_en.pdf) +* ESP32-S2 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s2_datasheet_en.pdf) +* ESP32-C3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-c3_datasheet_en.pdf) +* ESP32-S3 Datasheet: [Link to datasheet](https://www.espressif.com/sites/default/files/documentation/esp32-s3_datasheet_en.pdf) +* Official ESP-IDF documentation: [ESP-IDF](https://idf.espressif.com)