diff --git a/docs/en/get-started/index.rst b/docs/en/get-started/index.rst index 713362bb7..10b10c74b 100644 --- a/docs/en/get-started/index.rst +++ b/docs/en/get-started/index.rst @@ -1,4 +1,4 @@ -*********** +*********** Get Started *********** @@ -62,7 +62,7 @@ If you have one of ESP32 development boards listed below, you can click on the l ESP-WROVER-KIT <../hw-reference/get-started-wrover-kit> ESP32-PICO-KIT <../hw-reference/get-started-pico-kit> ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit> - + .. _get-started-step-by-step: @@ -175,6 +175,13 @@ If you want to install the tools without the help of ESP-IDF Tools Installer, op cd %userprofile%\esp\esp-idf install.bat +or with Windows PowerShell + +.. code-block:: powershell + + cd ~/esp/esp-idf + ./install.ps1 + Linux and macOS ~~~~~~~~~~~~~~~ @@ -188,7 +195,7 @@ Customizing the tools installation path The scripts introduced in this step install compilation tools required by ESP-IDF inside the user home directory: ``$HOME/.espressif`` on Linux and macOS, ``%USERPROFILE%\.espressif`` on Windows. If you wish to install the tools into a different directory, set the environment variable ``IDF_TOOLS_PATH`` before running the installation scripts. Make sure that your user has sufficient permissions to read and write this path. -If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the ``install.bat``/``install.sh`` and ``export.bat``/``export.sh`` scripts are executed. +If changing the ``IDF_TOOLS_PATH``, make sure it is set to the same value every time the Install script (``install.bat``, ``install.ps1`` or ``install.sh``) and an Export script (``export.bat``, ``export.ps1`` or ``export.sh``) are executed. .. _get-started-set-up-env: @@ -208,6 +215,12 @@ Alternatively, if you want to use ESP-IDF in an existing Command Prompt window, %userprofile%\esp\esp-idf\export.bat +or with Windows PowerShell + +.. code-block:: powershell + + .$HOME/esp/esp-idf/export.ps1 + Linux and macOS ~~~~~~~~~~~~~~~ @@ -481,9 +494,9 @@ You should update ESP-IDF from time to time, as newer versions fix bugs and prov Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using `. -After updating ESP-IDF, execute ``install.sh`` (``install.bat`` on Windows) again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools`. +After updating ESP-IDF, execute the Install script again, in case the new ESP-IDF version requires different versions of tools. See instructions at :ref:`get-started-set-up-tools`. -Once the new tools are installed, update the environment using ``export.sh`` (``export.bat`` on Windows). See instructions at :ref:`get-started-set-up-env`. +Once the new tools are installed, update the environment using the Export script. See instructions at :ref:`get-started-set-up-env`. Related Documents ================= diff --git a/docs/en/get-started/windows-setup-update.rst b/docs/en/get-started/windows-setup-update.rst index a1206354d..531573e7d 100644 --- a/docs/en/get-started/windows-setup-update.rst +++ b/docs/en/get-started/windows-setup-update.rst @@ -4,20 +4,24 @@ Updating ESP-IDF tools on Windows .. _get-started-install_bat-windows: -Install ESP-IDF tools using ``install.bat`` -=========================================== +Install ESP-IDF tools using a script +==================================== From the Windows Command Prompt, change to the directory where ESP-IDF is installed. Then run:: install.bat +For Powershell, change to the directory where ESP-IDF is installed. Then run:: + + install.ps1 + This will download and install the tools necessary to use ESP-IDF. If the specific version of the tool is already installed, no action will be taken. The tools are downloaded and installed into a directory specified during ESP-IDF Tools Installer process. By default, this is ``C:\Users\username\.espressif``. .. _get-started-export_bat-windows: -Add ESP-IDF tools to PATH using ``export.bat`` -============================================== +Add ESP-IDF tools to PATH using an export script +================================================ ESP-IDF tools installer creates a Start menu shortcut for "ESP-IDF Command Prompt". This shortcut opens a Command Prompt window where all the tools are already available. @@ -28,4 +32,9 @@ In the command prompt where you need to use ESP-IDF, change to the directory whe cd %userprofile%\esp\esp-idf export.bat +Alternatively in the Powershell where you need to use ESP-IDF, change to the directory where ESP-IDF is installed, then execute ``export.ps1``:: + + cd ~/esp/esp-idf + export.ps1 + When this is done, the tools will be available in this command prompt. diff --git a/export.ps1 b/export.ps1 new file mode 100644 index 000000000..a2cafd55a --- /dev/null +++ b/export.ps1 @@ -0,0 +1,62 @@ +if ($env:MSYSTEM -ne $null) { + Write-Output "This .ps1 file is for Windows Powershell only. When using MSYS, run:`n. ./export.sh." + exit 1 +} + + +$IDF_PATH = $PSScriptRoot + +Write-Output "Setting IDF_PATH: $IDF_PATH" +$env:IDF_PATH=$IDF_PATH + +Write-Output "Adding ESP-IDF tools to PATH..." +$OLD_PATH=$env:Path.split(";") | Select-Object -Unique # array without duplicates +# using idf_tools.py to get $envars_array to set +$envars_raw = python.exe $IDF_PATH\tools\idf_tools.py export --format key-value +if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } # if error + +$envars_array # will be filled like: +# [ +# [vname1, vval1], [vname2, vval2], ... +# ] +foreach ($line in $envars_raw) +{ + $pair = $line.split("=") # split in name, val + $var_name = $pair[0].Trim() # trim spaces on the ends of the name + $var_val = $pair[1].Trim() # trim spaces on the ends of the val + $var_val = $var_val -replace "%(.+)%", "`$env:`$1" # convert var syntax to PS using RegEx + $var_val = $ExecutionContext.InvokeCommand.ExpandString($var_val) # expand variables to values + $envars_array+=(,($var_name, $var_val)) +} + +foreach ($pair in $envars_array) # setting the values +{ + $var_name = $pair[0].Trim() # trim spaces on the ends of the name + $var_val = $pair[1].Trim() # trim spaces on the ends of the val + Set-Item -Path "Env:$var_name" -Value "$var_val" +} + +#Compare Path's OLD vs. NEW +$NEW_PATH = $env:Path.split(";") | Select-Object -Unique # array without duplicates +$dif_Path = Compare-Object -ReferenceObject $OLD_PATH -DifferenceObject $NEW_PATH -PassThru +if ($dif_Path -ne $null) +{ + Write-Output $dif_Path +} +else { + Write-Output "No directories added to PATH:" + Write-Output $OLD_PATH +} + + +Write-Output "Checking if Python packages are up to date..." + +Start-Process -Wait -NoNewWindow -FilePath "python" -Args "$IDF_PATH/tools/check_python_dependencies.py" +if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } # if error + +Write-Output " +Done! You can now compile ESP-IDF projects. +Go to the project directory and run: + idf.py build + +" diff --git a/install.ps1 b/install.ps1 new file mode 100644 index 000000000..8067df81e --- /dev/null +++ b/install.ps1 @@ -0,0 +1,22 @@ +if ($env:MSYSTEM -ne $null) { + Write-Output "This .ps1 file is for Windows Powershell only. When using MSYS, run:`n. ./export.sh." + exit 1 +} + + +$IDF_PATH = $PSScriptRoot + + +Write-Output "Installing ESP-IDF tools" +Start-Process -Wait -NoNewWindow -FilePath "python.exe" -Args "$IDF_PATH/tools/idf_tools.py install" +if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE } # if error + +Write-Output "Setting up Python environment" +Start-Process -Wait -NoNewWindow -FilePath "python.exe" -Args "$IDF_PATH/tools/idf_tools.py install-python-env" +if ($LASTEXITCODE -ne 0) { exit $LASTEXITCODE} # if error + + +Write-Output " +All done! You can now run: + export.ps1 +"