mirror of
https://github.com/espressif/esp-idf.git
synced 2025-08-07 20:00:53 +00:00
docs: Functional renaming commit for CMake-as-default
Rename all the files which will be edited substantially in the next commit, without changing their contents Docs will not build for this ocmmit. This is done so that git doesn't decide we renamed xxx-cmake -> xxx-legacy in the next commit, which is what it will infer otherwise (and makes rebasing more of a pain than it should be)
This commit is contained in:
Angus Gratton
committed by
Angus Gratton
Angus Gratton
parent
86dbe9299a
commit
62ed221daf
@@ -0,0 +1,65 @@
|
||||
Add IDF_PATH to User Profile
|
||||
============================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
To preserve setting of ``IDF_PATH`` environment variable between system restarts, add it to the user profile, following instructions below.
|
||||
|
||||
|
||||
.. _add-idf_path-to-profile-windows:
|
||||
|
||||
Windows
|
||||
-------
|
||||
|
||||
The user profile scripts are contained in ``C:/msys32/etc/profile.d/`` directory. They are executed every time you open an MSYS2 window.
|
||||
|
||||
#. Create a new script file in ``C:/msys32/etc/profile.d/`` directory. Name it ``export_idf_path.sh``.
|
||||
|
||||
#. Identify the path to ESP-IDF directory. It is specific to your system configuration and may look something like ``C:\msys32\home\user-name\esp\esp-idf``
|
||||
|
||||
#. Add the ``export`` command to the script file, e.g.::
|
||||
|
||||
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
|
||||
|
||||
Remember to replace back-slashes with forward-slashes in the original Windows path.
|
||||
|
||||
#. Save the script file.
|
||||
|
||||
#. Close MSYS2 window and open it again. Check if ``IDF_PATH`` is set, by typing::
|
||||
|
||||
printenv IDF_PATH
|
||||
|
||||
The path previusly entered in the script file should be printed out.
|
||||
|
||||
If you do not like to have ``IDF_PATH`` set up permanently in user profile, you should enter it manually on opening of an MSYS2 window::
|
||||
|
||||
export IDF_PATH="C:/msys32/home/user-name/esp/esp-idf"
|
||||
|
||||
If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
|
||||
|
||||
|
||||
.. _add-idf_path-to-profile-linux-macos:
|
||||
|
||||
Linux and MacOS
|
||||
---------------
|
||||
|
||||
Set up ``IDF_PATH`` by adding the following line to ``~/.profile`` file::
|
||||
|
||||
export IDF_PATH=~/esp/esp-idf
|
||||
|
||||
Log off and log in back to make this change effective.
|
||||
|
||||
.. note::
|
||||
|
||||
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead.
|
||||
|
||||
Run the following command to check if ``IDF_PATH`` is set::
|
||||
|
||||
printenv IDF_PATH
|
||||
|
||||
The path previously entered in ``~/.profile`` file (or set manually) should be printed out.
|
||||
|
||||
If you do not like to have ``IDF_PATH`` set up permanently, you should enter it manually in terminal window on each restart or logout::
|
||||
|
||||
export IDF_PATH=~/esp/esp-idf
|
||||
|
||||
If you got here from section :ref:`get-started-setup-path`, while installing s/w for ESP32 development, then go back to section :ref:`get-started-start-project`.
|
||||
109
docs/en/get-started-legacy/get-started/eclipse-setup.rst
Normal file
109
docs/en/get-started-legacy/get-started/eclipse-setup.rst
Normal file
@@ -0,0 +1,109 @@
|
||||
********************************
|
||||
Build and Flash with Eclipse IDE
|
||||
********************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. _eclipse-install-steps:
|
||||
|
||||
Installing Eclipse IDE
|
||||
======================
|
||||
|
||||
The Eclipse IDE gives you a graphical integrated development environment for writing, compiling and debugging ESP-IDF projects.
|
||||
|
||||
* Start by installing the esp-idf for your platform (see files in this directory with steps for Windows, OS X, Linux).
|
||||
|
||||
* We suggest building a project from the command line first, to get a feel for how that process works. You also need to use the command line to configure your esp-idf project (via ``make menuconfig``), this is not currently supported inside Eclipse.
|
||||
|
||||
* Download the Eclipse Installer for your platform from eclipse.org_.
|
||||
|
||||
* When running the Eclipse Installer, choose "Eclipse for C/C++ Development" (in other places you'll see this referred to as CDT.)
|
||||
|
||||
Setting up Eclipse
|
||||
==================
|
||||
|
||||
Once your new Eclipse installation launches, follow these steps:
|
||||
|
||||
Import New Project
|
||||
------------------
|
||||
|
||||
* Eclipse makes use of the Makefile support in ESP-IDF. This means you need to start by creating an ESP-IDF project. You can use the idf-template project from github, or open one of the examples in the esp-idf examples subdirectory.
|
||||
|
||||
* Once Eclipse is running, choose File -> Import...
|
||||
|
||||
* In the dialog that pops up, choose "C/C++" -> "Existing Code as Makefile Project" and click Next.
|
||||
|
||||
* On the next page, enter "Existing Code Location" to be the directory of your IDF project. Don't specify the path to the ESP-IDF directory itself (that comes later). The directory you specify should contain a file named "Makefile" (the project Makefile).
|
||||
|
||||
* On the same page, under "Toolchain for Indexer Settings" choose "Cross GCC". Then click Finish.
|
||||
|
||||
|
||||
Project Properties
|
||||
------------------
|
||||
|
||||
* The new project will appear under Project Explorer. Right-click the project and choose Properties from the context menu.
|
||||
|
||||
* Click on the "Environment" properties page under "C/C++ Build". Click "Add..." and enter name ``BATCH_BUILD`` and value ``1``.
|
||||
|
||||
* Click "Add..." again, and enter name ``IDF_PATH``. The value should be the full path where ESP-IDF is installed. Windows users can copy the ``IDF_PATH`` from windows explorer.
|
||||
|
||||
* Edit the ``PATH`` environment variable. Keep the current value, and append the path to the Xtensa toolchain installed as part of IDF setup, if this is not already listed on the PATH. A typical path to the toolchain looks like ``/home/user-name/esp/xtensa-esp32-elf/bin``. Note that you need to add a colon ``:`` before the appended path. Windows users will need to prepend ``C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin;C:\msys32\usr\bin`` to ``PATH`` environment variable (If you installed msys32 to a different directory then you’ll need to change these paths to match).
|
||||
|
||||
* On macOS, add a ``PYTHONPATH`` environment variable and set it to ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages``. This is so that the system Python, which has pyserial installed as part of the setup steps, overrides any built-in Eclipse Python.
|
||||
|
||||
**ADDITIONAL NOTE**: If either the IDF_PATH directory or the project directory is located outside ``C:\msys32\home`` directory, you will have to give custom build command in C/C++ Build properties as: ``python ${IDF_PATH}/tools/windows/eclipse_make.py`` (Please note that the build time may get significantly increased by this method.)
|
||||
|
||||
Navigate to "C/C++ General" -> "Preprocessor Include Paths" property page:
|
||||
|
||||
* Click the "Providers" tab
|
||||
|
||||
* In the list of providers, click "CDT Cross GCC Built-in Compiler Settings". Change "Command to get compiler specs" to ``xtensa-esp32-elf-gcc ${FLAGS} -std=c++11 -E -P -v -dD "${INPUTS}"``.
|
||||
|
||||
* In the list of providers, click "CDT GCC Build Output Parser" and change the "Compiler command pattern" to ``xtensa-esp32-elf-(gcc|g\+\+|c\+\+|cc|cpp|clang)``
|
||||
|
||||
Navigate to "C/C++ General" -> "Indexer" property page:
|
||||
|
||||
* Check "Enable project specific settings" to enable the rest of the settings on this page.
|
||||
|
||||
* Uncheck "Allow heuristic resolution of includes". When this option is enabled Eclipse sometimes fails to find correct header directories.
|
||||
|
||||
Navigate to "C/C++ Build" -> "Behavior" property page:
|
||||
|
||||
* Check "Enable parallel build" to enable multiple build jobs in parallel.
|
||||
|
||||
.. _eclipse-build-project:
|
||||
|
||||
Building in Eclipse
|
||||
-------------------
|
||||
|
||||
Before your project is first built, Eclipse may show a lot of errors and warnings about undefined values. This is because some source files are automatically generated as part of the esp-idf build process. These errors and warnings will go away after you build the project.
|
||||
|
||||
* Click OK to close the Properties dialog in Eclipse.
|
||||
|
||||
* Outside Eclipse, open a command line prompt. Navigate to your project directory, and run ``make menuconfig`` to configure your project's esp-idf settings. This step currently has to be run outside Eclipse.
|
||||
|
||||
*If you try to build without running a configuration step first, esp-idf will prompt for configuration on the command line - but Eclipse is not able to deal with this, so the build will hang or fail.*
|
||||
|
||||
* Back in Eclipse, choose Project -> Build to build your project.
|
||||
|
||||
**TIP**: If your project had already been built outside Eclipse, you may need to do a Project -> Clean before choosing Project -> Build. This is so Eclipse can see the compiler arguments for all source files. It uses these to determine the header include paths.
|
||||
|
||||
Flash from Eclipse
|
||||
------------------
|
||||
|
||||
You can integrate the "make flash" target into your Eclipse project to flash using esptool.py from the Eclipse UI:
|
||||
|
||||
* Right-click your project in Project Explorer (important to make sure you select the project, not a directory in the project, or Eclipse may find the wrong Makefile.)
|
||||
|
||||
* Select Build Targets -> Create... from the context menu.
|
||||
|
||||
* Type "flash" as the target name. Leave the other options as their defaults.
|
||||
|
||||
* Now you can use Project -> Build Target -> Build (Shift+F9) to build the custom flash target, which will compile and flash the project.
|
||||
|
||||
Note that you will need to use "make menuconfig" to set the serial port and other config options for flashing. "make menuconfig" still requires a command line terminal (see the instructions for your platform.)
|
||||
|
||||
Follow the same steps to add ``bootloader`` and ``partition_table`` targets, if necessary.
|
||||
|
||||
|
||||
.. _eclipse.org: https://www.eclipse.org/
|
||||
|
||||
@@ -0,0 +1,152 @@
|
||||
Establish Serial Connection with ESP32
|
||||
======================================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This section provides guidance how to establish serial connection between ESP32 and PC.
|
||||
|
||||
|
||||
Connect ESP32 to PC
|
||||
--------------------
|
||||
|
||||
Connect the ESP32 board to the PC using the USB cable. If device driver does not install automatically, identify USB to serial converter chip on your ESP32 board (or external converter dongle), search for drivers in internet and install them.
|
||||
|
||||
Below are the links to drivers for ESP32 and other boards produced by Espressif:
|
||||
|
||||
|
||||
.. csv-table::
|
||||
:header: Development Board, USB Driver, Remarks
|
||||
:widths: 40, 20, 40
|
||||
|
||||
:ref:`ESP32-DevKitC <esp-modules-and-boards-esp32-devkitc>`, `CP210x`_
|
||||
`ESP32-LyraT <https://www.espressif.com/en/products/hardware/esp32-lyrat>`_, `CP210x`_
|
||||
`ESP32-LyraTD-MSC <https://www.espressif.com/en/products/hardware/esp32-lyratd-msc>`_, `CP210x`_
|
||||
:ref:`ESP32-PICO-KIT <esp-modules-and-boards-esp32-pico-kit>`, `CP210x`_
|
||||
:ref:`ESP-WROVER-KIT <esp-modules-and-boards-esp-wrover-kit>`, `FTDI`_
|
||||
:ref:`ESP32 Demo Board <esp-modules-and-boards-esp32-demo-board>`, `FTDI`_
|
||||
`ESP-Prog`_, `FTDI`_, Programmer board (w/o ESP32)
|
||||
`ESP32-MeshKit-Sense <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP32-MeshKit-Sense_guide_en.md#esp32-meshkit-sense-hardware-design-guidelines>`_, n/a, Use with `ESP-Prog`_
|
||||
`ESP32-Sense Kit <https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/esp32_sense_kit_guide_en.md#guide-for-esp32-sense-development-kit>`_, n/a, Use with `ESP-Prog`_
|
||||
|
||||
.. _CP210x: https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers
|
||||
.. _FTDI: http://www.ftdichip.com/Drivers/VCP.htm
|
||||
.. _ESP-Prog: https://github.com/espressif/esp-iot-solution/blob/master/documents/evaluation_boards/ESP-Prog_guide_en.md#introduction-to-the-esp-prog-board
|
||||
|
||||
* CP210x: `CP210x USB to UART Bridge VCP Drivers <https://www.silabs.com/products/development-tools/software/usb-to-uart-bridge-vcp-drivers>`_
|
||||
* FTDI: `FTDI Virtual COM Port Drivers <http://www.ftdichip.com/Drivers/VCP.htm>`_
|
||||
|
||||
The drivers above are primarily for reference. Under normal circumstances, the drivers should be bundled with and operating system and automatically installed upon connecting one of the listed boards to the PC.
|
||||
|
||||
|
||||
Check port on Windows
|
||||
---------------------
|
||||
|
||||
Check the list of identified COM ports in the Windows Device Manager. Disconnect ESP32 and connect it back, to verify which port disappears from the list and then shows back again.
|
||||
|
||||
Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
|
||||
|
||||
.. figure:: ../../_static/esp32-devkitc-in-device-manager.png
|
||||
:align: center
|
||||
:alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager
|
||||
:figclass: align-center
|
||||
|
||||
USB to UART bridge of ESP32-DevKitC in Windows Device Manager
|
||||
|
||||
.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png
|
||||
:align: center
|
||||
:alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
|
||||
:figclass: align-center
|
||||
|
||||
Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
|
||||
|
||||
|
||||
Check port on Linux and MacOS
|
||||
-----------------------------
|
||||
|
||||
To check the device name for the serial port of your ESP32 board (or external converter dongle), run this command two times, first with the board / dongle unplugged, then with plugged in. The port which appears the second time is the one you need:
|
||||
|
||||
Linux ::
|
||||
|
||||
ls /dev/tty*
|
||||
|
||||
MacOS ::
|
||||
|
||||
ls /dev/cu.*
|
||||
|
||||
|
||||
.. _linux-dialout-group:
|
||||
|
||||
Adding user to ``dialout`` on Linux
|
||||
-----------------------------------
|
||||
|
||||
The currently logged user should have read and write access the serial port over USB. On most Linux distributions, this is done by adding the user to ``dialout`` group with the following command::
|
||||
|
||||
sudo usermod -a -G dialout $USER
|
||||
|
||||
on Arch Linux this is done by adding the user to ``uucp`` group with the following command::
|
||||
|
||||
sudo usermod -a -G uucp $USER
|
||||
|
||||
Make sure you re-login to enable read and write permissions for the serial port.
|
||||
|
||||
|
||||
Verify serial connection
|
||||
------------------------
|
||||
|
||||
Now verify that the serial connection is operational. You can do this using a serial terminal program. In this example we will use `PuTTY SSH Client <http://www.putty.org/>`_ that is available for both Windows and Linux. You can use other serial program and set communication parameters like below.
|
||||
|
||||
Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
|
||||
|
||||
.. figure:: ../../_static/putty-settings-windows.png
|
||||
:align: center
|
||||
:alt: Setting Serial Communication in PuTTY on Windows
|
||||
:figclass: align-center
|
||||
|
||||
Setting Serial Communication in PuTTY on Windows
|
||||
|
||||
.. figure:: ../../_static/putty-settings-linux.png
|
||||
:align: center
|
||||
:alt: Setting Serial Communication in PuTTY on Linux
|
||||
:figclass: align-center
|
||||
|
||||
Setting Serial Communication in PuTTY on Linux
|
||||
|
||||
|
||||
Then open serial port in terminal and check, if you see any log printed out by ESP32. The log contents will depend on application loaded to ESP32. An example log by ESP32 is shown below.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
ets Jun 8 2016 00:22:57
|
||||
|
||||
rst:0x5 (DEEPSLEEP_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
|
||||
ets Jun 8 2016 00:22:57
|
||||
|
||||
rst:0x7 (TG0WDT_SYS_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
|
||||
configsip: 0, SPIWP:0x00
|
||||
clk_drv:0x00,q_drv:0x00,d_drv:0x00,cs0_drv:0x00,hd_drv:0x00,wp_drv:0x00
|
||||
mode:DIO, clock div:2
|
||||
load:0x3fff0008,len:8
|
||||
load:0x3fff0010,len:3464
|
||||
load:0x40078000,len:7828
|
||||
load:0x40080000,len:252
|
||||
entry 0x40080034
|
||||
I (44) boot: ESP-IDF v2.0-rc1-401-gf9fba35 2nd stage bootloader
|
||||
I (45) boot: compile time 18:48:10
|
||||
|
||||
...
|
||||
|
||||
If you see some legible log, it means serial connection is working and you are ready to proceed with installation and finally upload of application to ESP32.
|
||||
|
||||
.. note::
|
||||
|
||||
For some serial port wiring configurations, the serial RTS & DTR pins need to be disabled in the terminal program before the ESP32 will boot and produce serial output. This depends on the hardware itself, most development boards (including all Espressif boards) *do not* have this issue. The issue is present if RTS & DTR are wired directly to the EN & GPIO0 pins. See the `esptool documentation`_ for more details.
|
||||
|
||||
.. note::
|
||||
|
||||
Close serial terminal after verification that communication is working. In next step we are going to use another application to upload ESP32. This application will not be able to access serial port while it is open in terminal.
|
||||
|
||||
If you got here from section :ref:`get-started-connect` when installing s/w for ESP32 development, then go back to section :ref:`get-started-configure`.
|
||||
|
||||
|
||||
.. _esptool documentation: https://github.com/espressif/esptool/wiki/ESP32-Boot-Mode-Selection#automatic-bootloader
|
||||
452
docs/en/get-started-legacy/get-started/index.rst
Normal file
452
docs/en/get-started-legacy/get-started/index.rst
Normal file
@@ -0,0 +1,452 @@
|
||||
***********
|
||||
Get Started
|
||||
***********
|
||||
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
This document is intended to help you set up the software development environment for the hardware based on Espressif ESP32.
|
||||
|
||||
After that, a simple example will show you how to use ESP-IDF (Espressif IoT Development Framework) for menu configuration, then how to build and flash firmware onto an ESP32 board.
|
||||
|
||||
.. include:: /_build/inc/version-note.inc
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
ESP32 is a system on a chip that integrates the following features:
|
||||
|
||||
* Wi-Fi (2.4 GHz band)
|
||||
* Bluetooth 4.2
|
||||
* Dual high performance cores
|
||||
* Ultra Low Power co-processor
|
||||
* Several peripherals
|
||||
|
||||
Powered by 40 nm technology, ESP32 provides a robust, highly integrated platform, which helps meet the continuous demands for efficient power usage, compact design, security, high performance, and reliability.
|
||||
|
||||
Espressif provides basic hardware and software resources to help application developers realize their ideas using the ESP32 series hardware. The software development framework by Espressif is intended for development of Internet-of-Things (IoT) applications with Wi-Fi, Bluetooth, power management and several other system features.
|
||||
|
||||
What You Need
|
||||
=============
|
||||
|
||||
Hardware:
|
||||
|
||||
* An **ESP32** board
|
||||
* **USB cable** - USB A / micro USB B
|
||||
* **Computer** running Windows, Linux, or macOS
|
||||
|
||||
Software:
|
||||
|
||||
* **Toolchain** to build the **Application** for ESP32
|
||||
* **ESP-IDF** that essentially contains API (software libraries and source code) for ESP32 and scripts to operate the **Toolchain**
|
||||
* **Text editor** to write programs (**Projects**) in C, e.g., `Eclipse <https://www.eclipse.org/>`_
|
||||
|
||||
|
||||
.. figure:: ../../_static/what-you-need.png
|
||||
:align: center
|
||||
:alt: Development of applications for ESP32
|
||||
:figclass: align-center
|
||||
|
||||
Development of applications for ESP32
|
||||
|
||||
|
||||
Development Board Overviews
|
||||
===========================
|
||||
|
||||
If you have one of ESP32 development boards listed below, you can click on the link to learn more about its hardware.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
ESP32-DevKitC <get-started-devkitc>
|
||||
ESP-WROVER-KIT <get-started-wrover-kit>
|
||||
ESP32-PICO-KIT <get-started-pico-kit>
|
||||
ESP32-Ethernet-Kit <../hw-reference/get-started-ethernet-kit>
|
||||
|
||||
|
||||
.. _get-started-step-by-step:
|
||||
|
||||
Installation Step by Step
|
||||
=========================
|
||||
|
||||
This is a detailed roadmap to walk you through the installation process.
|
||||
|
||||
Setting up Development Environment
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* :ref:`get-started-setup-toolchain` for :doc:`Windows <windows-setup>`, :doc:`Linux <linux-setup>` or :doc:`MacOS <macos-setup>`
|
||||
* :ref:`get-started-get-esp-idf`
|
||||
* :ref:`get-started-setup-path`
|
||||
* :ref:`get-started-get-packages`
|
||||
|
||||
Creating Your First Project
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* :ref:`get-started-start-project`
|
||||
* :ref:`get-started-connect`
|
||||
* :ref:`get-started-configure`
|
||||
* :ref:`get-started-build-and-flash`
|
||||
* :ref:`get-started-monitor`
|
||||
|
||||
|
||||
.. _get-started-setup-toolchain:
|
||||
|
||||
Step 1. Set up the Toolchain
|
||||
============================
|
||||
|
||||
The toolchain is a set of programs for compiling code and building applications.
|
||||
|
||||
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow the provided instructions.
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
|
||||
Windows <windows-setup>
|
||||
Linux <linux-setup>
|
||||
MacOS <macos-setup>
|
||||
|
||||
+-------------------+-------------------+-------------------+
|
||||
| |windows-logo| | |linux-logo| | |macos-logo| |
|
||||
+-------------------+-------------------+-------------------+
|
||||
| `Windows`_ | `Linux`_ | `Mac OS`_ |
|
||||
+-------------------+-------------------+-------------------+
|
||||
|
||||
.. |windows-logo| image:: ../../_static/windows-logo.png
|
||||
:target: ../get-started/windows-setup.html
|
||||
|
||||
.. |linux-logo| image:: ../../_static/linux-logo.png
|
||||
:target: ../get-started/linux-setup.html
|
||||
|
||||
.. |macos-logo| image:: ../../_static/macos-logo.png
|
||||
:target: ../get-started/macos-setup.html
|
||||
|
||||
.. _Windows: ../get-started/windows-setup.html
|
||||
.. _Linux: ../get-started/linux-setup.html
|
||||
.. _Mac OS: ../get-started/macos-setup.html
|
||||
|
||||
.. note::
|
||||
|
||||
This guide uses the directory ``~/esp`` on Linux and macOS or ``%userprofile%\esp`` on Windows as an installation folder for ESP-IDF. You can use any directory, but you will need to adjust paths for the commands respectively. Keep in mind that ESP-IDF does not support spaces in paths.
|
||||
|
||||
Depending on your experience and preferences, you may want to customize your environment instead of using a prebuilt toolchain. To set up the system your own way go to Section :ref:`get-started-customized-setup`.
|
||||
|
||||
|
||||
.. _get-started-get-esp-idf:
|
||||
|
||||
Step 2. Get ESP-IDF
|
||||
===================
|
||||
|
||||
Besides the toolchain, you also need ESP32-specific API (software libraries and source code). They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_.
|
||||
|
||||
To get a local copy of ESP-IDF, navigate to your installation directory and clone the repository with ``git clone``.
|
||||
|
||||
Open Terminal, and run the following commands:
|
||||
|
||||
.. include:: /_build/inc/git-clone-bash.inc
|
||||
|
||||
ESP-IDF will be downloaded into ``~/esp/esp-idf``.
|
||||
|
||||
Consult :doc:`/versions` for information about which ESP-IDF version to use in a given situation.
|
||||
|
||||
.. include:: /_build/inc/git-clone-notes.inc
|
||||
|
||||
.. note::
|
||||
|
||||
Do not miss the ``--recursive`` option. If you have already cloned ESP-IDF without this option, run another command to get all the submodules::
|
||||
|
||||
cd esp-idf
|
||||
git submodule update --init
|
||||
|
||||
|
||||
.. _get-started-setup-path:
|
||||
|
||||
Step 3. Set Environment Variables
|
||||
=================================
|
||||
|
||||
The toolchain uses the environment variable ``IDF_PATH`` to access the ESP-IDF directory. This variable should be set up on your computer, otherwise projects will not build.
|
||||
|
||||
These variables can be set temporarily (per session) or permanently. Please follow the instructions specific to :ref:`Windows <add-idf_path-to-profile-windows>` , :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` in Section :doc:`add-idf_path-to-profile`.
|
||||
|
||||
|
||||
.. _get-started-get-packages:
|
||||
|
||||
Step 4. Install the Required Python Packages
|
||||
============================================
|
||||
|
||||
The python packages required by ESP-IDF are located in ``IDF_PATH/requirements.txt``. You can install them by running::
|
||||
|
||||
python -m pip install --user -r $IDF_PATH/requirements.txt
|
||||
|
||||
.. note::
|
||||
|
||||
Please check the version of the Python interpreter that you will be using with ESP-IDF. For this, run
|
||||
the command ``python --version`` and depending on the result, you might want to use ``python2``, ``python2.7``
|
||||
or similar instead of just ``python``, e.g.::
|
||||
|
||||
python2.7 -m pip install --user -r $IDF_PATH/requirements.txt
|
||||
|
||||
|
||||
.. _get-started-start-project:
|
||||
|
||||
Step 5. Start a Project
|
||||
=======================
|
||||
|
||||
Now you are ready to prepare your application for ESP32. You can start with :example:`get-started/hello_world` project from :idf:`examples` directory in IDF.
|
||||
|
||||
Copy :example:`get-started/hello_world` to the ``~/esp`` directory:
|
||||
|
||||
Linux and MacOS
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp
|
||||
cp -r $IDF_PATH/examples/get-started/hello_world .
|
||||
|
||||
Windows
|
||||
~~~~~~~
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
cd %userprofile%\esp
|
||||
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
|
||||
|
||||
There is a range of example projects in the :idf:`examples` directory in ESP-IDF. You can copy any project in the same way as presented above and run it.
|
||||
|
||||
It is also possible to build examples in-place, without copying them first.
|
||||
|
||||
.. important::
|
||||
|
||||
The esp-idf build system does not support spaces in the paths to either esp-idf or to projects.
|
||||
|
||||
.. _get-started-connect:
|
||||
|
||||
Step 6. Connect Your Device
|
||||
===========================
|
||||
|
||||
Now connect your ESP32 board to the computer and check under what serial port the board is visible.
|
||||
|
||||
Serial ports have the following patterns in their names:
|
||||
|
||||
- **Windows**: names like ``COM1``
|
||||
- **Linux**: starting with ``/dev/tty``
|
||||
- **macOS**: starting with ``/dev/cu.``
|
||||
|
||||
If you are not sure how to check the serial port name, please refer to :doc:`establish-serial-connection` for full details.
|
||||
|
||||
.. note::
|
||||
|
||||
Keep the port name handy as you will need it in the next steps.
|
||||
|
||||
|
||||
.. _get-started-configure:
|
||||
|
||||
Step 7. Configure
|
||||
=================
|
||||
|
||||
Navigate to your ``hello_world`` directory from :ref:`get-started-start-project` and run the project configuration utility ``menuconfig``.
|
||||
|
||||
Linux and MacOS
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp/hello_world
|
||||
make menuconfig
|
||||
|
||||
Windows
|
||||
~~~~~~~
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
cd %userprofile%\esp\hello_world
|
||||
make menuconfig
|
||||
|
||||
If the previous steps have been done correctly, the following menu appears:
|
||||
|
||||
.. figure:: ../../_static/project-configuration.png
|
||||
:align: center
|
||||
:alt: Project configuration - Home window
|
||||
:figclass: align-center
|
||||
|
||||
Project configuration - Home window
|
||||
|
||||
In the menu, navigate to ``Serial flasher config`` > ``Default serial port`` to configure the serial port, where project will be loaded to. Confirm selection by pressing enter, save configuration by selecting ``< Save >`` and then exit ``menuconfig`` by selecting ``< Exit >``.
|
||||
|
||||
To navigate and use ``menuconfig``, press the following keys:
|
||||
|
||||
* Arrow keys for navigation
|
||||
* ``Enter`` to go into a submenu
|
||||
* ``Esc`` to go up one level or exit
|
||||
* ``?`` to see a help screen. Enter key exits the help screen
|
||||
* ``Space``, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
|
||||
* ``?`` while highlighting a configuration item to display help about that item
|
||||
* ``/`` to find configuration items
|
||||
|
||||
.. note::
|
||||
|
||||
If you are **Arch Linux** user, navigate to ``SDK tool configuration`` and change the name of ``Python 2 interpreter`` from ``python`` to ``python2``.
|
||||
|
||||
.. attention::
|
||||
|
||||
If you use ESP32-DevKitC board with the **ESP32-SOLO-1** module, enable single core mode (:ref:`CONFIG_FREERTOS_UNICORE`) in menuconfig before flashing examples.
|
||||
|
||||
.. _get-started-build-and-flash:
|
||||
|
||||
Step 8. Build and Flash
|
||||
=======================
|
||||
|
||||
Build and flash the project by running::
|
||||
|
||||
make flash
|
||||
|
||||
This command will compile the application and all ESP-IDF components, then it will generate the bootloader, partition table, and application binaries. After that, these binaries will be flashed onto your ESP32 board.
|
||||
|
||||
If there are no issues by the end of the flash process, you will see messages (below) describing progress of the loading process. Then the board will be reset and the "hello_world" application will start up.
|
||||
|
||||
.. highlight:: none
|
||||
|
||||
::
|
||||
|
||||
esptool.py v2.0-beta2
|
||||
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
|
||||
esptool.py v2.0-beta2
|
||||
Connecting........___
|
||||
Uploading stub...
|
||||
Running stub...
|
||||
Stub running...
|
||||
Changing baud rate to 921600
|
||||
Changed.
|
||||
Attaching SPI flash...
|
||||
Configuring flash size...
|
||||
Auto-detected Flash size: 4MB
|
||||
Flash params set to 0x0220
|
||||
Compressed 11616 bytes to 6695...
|
||||
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 408096 bytes to 171625...
|
||||
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
|
||||
Hash of data verified.
|
||||
Compressed 3072 bytes to 82...
|
||||
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
|
||||
Hash of data verified.
|
||||
|
||||
Leaving...
|
||||
Hard resetting...
|
||||
|
||||
|
||||
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
|
||||
|
||||
|
||||
.. _get-started-monitor:
|
||||
|
||||
Step 9. Monitor
|
||||
===============
|
||||
|
||||
To check if "hello_world" is indeed running, type ``make monitor``.
|
||||
|
||||
This command launches the :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` application::
|
||||
|
||||
$ make monitor
|
||||
MONITOR
|
||||
--- idf_monitor on /dev/ttyUSB0 115200 ---
|
||||
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
|
||||
ets Jun 8 2016 00:22:57
|
||||
|
||||
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
|
||||
ets Jun 8 2016 00:22:57
|
||||
...
|
||||
|
||||
After startup and diagnostic logs scroll up, you should see "Hello world!" printed out by the application.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
...
|
||||
Hello world!
|
||||
Restarting in 10 seconds...
|
||||
I (211) cpu_start: Starting scheduler on APP CPU.
|
||||
Restarting in 9 seconds...
|
||||
Restarting in 8 seconds...
|
||||
Restarting in 7 seconds...
|
||||
|
||||
To exit IDF monitor use the shortcut ``Ctrl+]``.
|
||||
|
||||
If IDF monitor fails shortly after the upload, or if instead of the messages above you see a random garbage similar to what is given below, your board is likely using a 26MHz crystal. Most development board designs use 40MHz, so ESP-IDF uses this frequency as a default value.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
e<><65><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
|
||||
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
|
||||
|
||||
If you have such a problem, do the following:
|
||||
|
||||
1. Exit the monitor.
|
||||
2. Go back to :ref:`menuconfig <get-started-configure>`.
|
||||
3. Go to Component config --> ESP32-specific --> Main XTAL frequency, then change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz.
|
||||
4. After that, :ref:`build and flash <get-started-build-and-flash>` the application again.
|
||||
|
||||
.. note::
|
||||
|
||||
You can combine building, flashing and monitoring into one step by running::
|
||||
|
||||
make flash monitor
|
||||
|
||||
See also :doc:`IDF Monitor <../api-guides/tools/idf-monitor>` for handy shortcuts and more details on using IDF monitor.
|
||||
|
||||
**That's all that you need to get started with ESP32!**
|
||||
|
||||
Now you are ready to try some other :idf:`examples`, or go straight to developing your own applications.
|
||||
|
||||
|
||||
Environment Variables
|
||||
=====================
|
||||
|
||||
Some environment variables can be specified whilst calling ``make`` allowing users to **override arguments without the need to reconfigure them using** ``make menuconfig``.
|
||||
|
||||
+-----------------+--------------------------------------------------------------+
|
||||
| Variables | Description & Usage |
|
||||
+=================+==============================================================+
|
||||
| ``ESPPORT`` | Overrides the serial port used in ``flash`` and ``monitor``. |
|
||||
| | |
|
||||
| | Examples: ``make flash ESPPORT=/dev/ttyUSB1``, |
|
||||
| | ``make monitor ESPPORT=COM1`` |
|
||||
+-----------------+--------------------------------------------------------------+
|
||||
| ``ESPBAUD`` | Overrides the serial baud rate when flashing the ESP32. |
|
||||
| | |
|
||||
| | Example: ``make flash ESPBAUD=9600`` |
|
||||
+-----------------+--------------------------------------------------------------+
|
||||
| ``MONITORBAUD`` | Overrides the serial baud rate used when monitoring. |
|
||||
| | |
|
||||
| | Example: ``make monitor MONITORBAUD=9600`` |
|
||||
+-----------------+--------------------------------------------------------------+
|
||||
|
||||
.. note::
|
||||
|
||||
You can export environment variables (e.g. ``export ESPPORT=/dev/ttyUSB1``).
|
||||
All subsequent calls of ``make`` within the same terminal session will use
|
||||
the exported value given that the variable is not simultaneously overridden.
|
||||
|
||||
|
||||
Updating ESP-IDF
|
||||
================
|
||||
|
||||
You should update ESP-IDF from time to time, as newer versions fix bugs and provide new features. The simplest way to do the update is to delete the existing ``esp-idf`` folder and clone it again, as if performing the initial installation described in :ref:`get-started-get-esp-idf`.
|
||||
|
||||
If downloading to a new path, remember to :doc:`add-idf_path-to-profile` so that the toolchain scripts can find ESP-IDF in its release specific location.
|
||||
|
||||
Another solution is to update only what has changed. :ref:`The update procedure depends on the version of ESP-IDF you are using <updating>`.
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
add-idf_path-to-profile
|
||||
establish-serial-connection
|
||||
make-project
|
||||
eclipse-setup
|
||||
../api-guides/tools/idf-monitor
|
||||
toolchain-setup-scratch
|
||||
|
||||
.. _Stable version: https://docs.espressif.com/projects/esp-idf/en/stable/
|
||||
.. _Releases page: https://github.com/espressif/esp-idf/releases
|
||||
@@ -0,0 +1,75 @@
|
||||
**********************************
|
||||
Setup Linux Toolchain from Scratch
|
||||
**********************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. note::
|
||||
|
||||
Standard process for installing the toolchain is described :doc:`here <linux-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
|
||||
|
||||
Install Prerequisites
|
||||
=====================
|
||||
|
||||
To compile with ESP-IDF you need to get the following packages:
|
||||
|
||||
- Ubuntu and Debian::
|
||||
|
||||
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
|
||||
|
||||
- Arch::
|
||||
|
||||
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
|
||||
|
||||
.. note::
|
||||
|
||||
Some older (pre-2014) Linux distributions may use ``pyserial`` version 2.x which is not supported by ESP-IDF.
|
||||
In this case please install a supported version via ``pip`` as it is described in section
|
||||
:ref:`get-started-get-packages`.
|
||||
|
||||
Compile the Toolchain from Source
|
||||
=================================
|
||||
|
||||
- Install dependencies:
|
||||
|
||||
- CentOS 7::
|
||||
|
||||
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool
|
||||
|
||||
- Ubuntu pre-16.04::
|
||||
|
||||
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool
|
||||
|
||||
- Ubuntu 16.04 or newer::
|
||||
|
||||
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin
|
||||
|
||||
- Debian 9::
|
||||
|
||||
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin
|
||||
|
||||
- Arch::
|
||||
|
||||
TODO
|
||||
|
||||
Create the working directory and go into it::
|
||||
|
||||
mkdir -p ~/esp
|
||||
cd ~/esp
|
||||
|
||||
Download ``crosstool-NG`` and build it:
|
||||
|
||||
.. include:: /_build/inc/scratch-build-code.inc
|
||||
|
||||
Build the toolchain::
|
||||
|
||||
./ct-ng xtensa-esp32-elf
|
||||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-esp32-elf
|
||||
|
||||
Toolchain will be built in ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-linux-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
|
||||
118
docs/en/get-started-legacy/get-started/linux-setup.rst
Normal file
118
docs/en/get-started-legacy/get-started/linux-setup.rst
Normal file
@@ -0,0 +1,118 @@
|
||||
*************************************
|
||||
Standard Setup of Toolchain for Linux
|
||||
*************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Install Prerequisites
|
||||
=====================
|
||||
|
||||
To compile with ESP-IDF you need to get the following packages:
|
||||
|
||||
- CentOS 7::
|
||||
|
||||
sudo yum install gcc git wget make ncurses-devel flex bison gperf python python2-cryptography
|
||||
|
||||
- Ubuntu and Debian::
|
||||
|
||||
sudo apt-get install gcc git wget make libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools
|
||||
|
||||
- Arch::
|
||||
|
||||
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-cryptography python2-future python2-pyparsing python2-pyelftools
|
||||
|
||||
.. note::
|
||||
|
||||
Some older Linux distributions may be missing some of the Python packages listed above (or may use ``pyserial`` version 2.x which is not supported by ESP-IDF). It is possible to install these packages via ``pip`` instead - as described in section :ref:`get-started-get-packages`.
|
||||
|
||||
Toolchain Setup
|
||||
===============
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
ESP32 toolchain for Linux is available for download from Espressif website:
|
||||
|
||||
- for 64-bit Linux:
|
||||
|
||||
|download_link_linux64|
|
||||
|
||||
- for 32-bit Linux:
|
||||
|
||||
|download_link_linux32|
|
||||
|
||||
1. Download this file, then extract it in ``~/esp`` directory:
|
||||
|
||||
- for 64-bit Linux:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-linux64.inc
|
||||
|
||||
- for 32-bit Linux:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-linux32.inc
|
||||
|
||||
.. _setup-linux-toolchain-add-it-to-path:
|
||||
|
||||
2. The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
|
||||
|
||||
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
|
||||
|
||||
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
|
||||
|
||||
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
|
||||
|
||||
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
|
||||
|
||||
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
|
||||
|
||||
.. note::
|
||||
|
||||
If you have ``/bin/bash`` set as login shell, and both ``.bash_profile`` and ``.profile`` exist, then update ``.bash_profile`` instead. In CentOS, ``alias`` should set in ``.bashrc``.
|
||||
|
||||
3. Log off and log in back to make the ``.profile`` changes effective. Run the following command to verify if ``PATH`` is correctly set::
|
||||
|
||||
printenv PATH
|
||||
|
||||
You are looking for similar result containing toolchain's path at the beginning of displayed string::
|
||||
|
||||
$ printenv PATH
|
||||
/home/user-name/esp/xtensa-esp32-elf/bin:/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin
|
||||
|
||||
Instead of ``/home/user-name`` there should be a home path specific to your installation.
|
||||
|
||||
|
||||
Permission issues /dev/ttyUSB0
|
||||
------------------------------
|
||||
|
||||
With some Linux distributions you may get the ``Failed to open port /dev/ttyUSB0`` error message when flashing the ESP32. :ref:`This can be solved by adding the current user to the dialout group<linux-dialout-group>`.
|
||||
|
||||
|
||||
Arch Linux Users
|
||||
----------------
|
||||
|
||||
To run the precompiled gdb (xtensa-esp32-elf-gdb) in Arch Linux requires ncurses 5, but Arch uses ncurses 6.
|
||||
|
||||
Backwards compatibility libraries are available in AUR_ for native and lib32 configurations:
|
||||
|
||||
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
|
||||
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
|
||||
|
||||
Before installing these packages you might need to add the author's public key to your keyring as described in the "Comments" section at the links above.
|
||||
|
||||
Alternatively, use crosstool-NG to compile a gdb that links against ncurses 6.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
|
||||
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
linux-setup-scratch
|
||||
|
||||
|
||||
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
|
||||
@@ -0,0 +1,72 @@
|
||||
***************************************
|
||||
Setup Toolchain for Mac OS from Scratch
|
||||
***************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
.. note::
|
||||
|
||||
Standard process for installing the toolchain is described :doc:`here <macos-setup>`. See :ref:`Customized Setup of Toolchain <get-started-customized-setup>` section for some of the reasons why installing the toolchain from scratch may be necessary.
|
||||
|
||||
Install Prerequisites
|
||||
=====================
|
||||
|
||||
- install pip::
|
||||
|
||||
sudo easy_install pip
|
||||
|
||||
.. note::
|
||||
|
||||
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages>`.
|
||||
|
||||
Compile the Toolchain from Source
|
||||
=================================
|
||||
|
||||
- Install dependencies:
|
||||
|
||||
- Install either MacPorts_ or homebrew_ package manager. MacPorts needs a full XCode installation, while homebrew only needs XCode command line tools.
|
||||
|
||||
.. _homebrew: https://brew.sh/
|
||||
.. _MacPorts: https://www.macports.org/install.php
|
||||
|
||||
- with MacPorts::
|
||||
|
||||
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake
|
||||
|
||||
- with homebrew::
|
||||
|
||||
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake
|
||||
|
||||
Create a case-sensitive filesystem image::
|
||||
|
||||
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
|
||||
|
||||
Mount it::
|
||||
|
||||
hdiutil mount ~/esp/crosstool.dmg
|
||||
|
||||
Create a symlink to your work directory::
|
||||
|
||||
mkdir -p ~/esp
|
||||
ln -s /Volumes/ctng ~/esp/ctng-volume
|
||||
|
||||
Go into the newly created directory::
|
||||
|
||||
cd ~/esp/ctng-volume
|
||||
|
||||
Download ``crosstool-NG`` and build it:
|
||||
|
||||
.. include:: /_build/inc/scratch-build-code.inc
|
||||
|
||||
Build the toolchain::
|
||||
|
||||
./ct-ng xtensa-esp32-elf
|
||||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-esp32-elf
|
||||
|
||||
Toolchain will be built in ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``. Follow :ref:`instructions for standard setup <setup-macos-toolchain-add-it-to-path>` to add the toolchain to your ``PATH``.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
|
||||
57
docs/en/get-started-legacy/get-started/macos-setup.rst
Normal file
57
docs/en/get-started-legacy/get-started/macos-setup.rst
Normal file
@@ -0,0 +1,57 @@
|
||||
**************************************
|
||||
Standard Setup of Toolchain for Mac OS
|
||||
**************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Install Prerequisites
|
||||
=====================
|
||||
|
||||
- install pip::
|
||||
|
||||
sudo easy_install pip
|
||||
|
||||
.. note::
|
||||
|
||||
``pip`` will be used later for installing :ref:`the required Python packages <get-started-get-packages>`.
|
||||
|
||||
Toolchain Setup
|
||||
===============
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
ESP32 toolchain for macOS is available for download from Espressif website:
|
||||
|
||||
|download_link_osx|
|
||||
|
||||
Download this file, then extract it in ``~/esp`` directory:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-osx.inc
|
||||
|
||||
.. _setup-macos-toolchain-add-it-to-path:
|
||||
|
||||
The toolchain will be extracted into ``~/esp/xtensa-esp32-elf/`` directory.
|
||||
|
||||
To use it, you will need to update your ``PATH`` environment variable in ``~/.profile`` file. To make ``xtensa-esp32-elf`` available for all terminal sessions, add the following line to your ``~/.profile`` file::
|
||||
|
||||
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
|
||||
|
||||
Alternatively, you may create an alias for the above command. This way you can get the toolchain only when you need it. To do this, add different line to your ``~/.profile`` file::
|
||||
|
||||
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
|
||||
|
||||
Then when you need the toolchain you can type ``get_esp32`` on the command line and the toolchain will be added to your ``PATH``.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
|
||||
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
macos-setup-scratch
|
||||
76
docs/en/get-started-legacy/get-started/make-project.rst
Normal file
76
docs/en/get-started-legacy/get-started/make-project.rst
Normal file
@@ -0,0 +1,76 @@
|
||||
Build and Flash with Make
|
||||
=========================
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
|
||||
Finding a project
|
||||
-----------------
|
||||
|
||||
As well as the `esp-idf-template <https://github.com/espressif/esp-idf-template>`_ project, ESP-IDF comes with some example projects on github in the :idf:`examples` directory.
|
||||
|
||||
Once you've found the project you want to work with, change to its directory and you can configure and build it.
|
||||
|
||||
|
||||
Configuring your project
|
||||
------------------------
|
||||
|
||||
::
|
||||
|
||||
make menuconfig
|
||||
|
||||
|
||||
Compiling your project
|
||||
----------------------
|
||||
|
||||
::
|
||||
|
||||
make all
|
||||
|
||||
... will compile app, bootloader and generate a partition table based on the config.
|
||||
|
||||
|
||||
Flashing your project
|
||||
---------------------
|
||||
|
||||
When ``make all`` finishes, it will print a command line to use esptool.py to flash the chip. However you can also do this from make by running::
|
||||
|
||||
make flash
|
||||
|
||||
This will flash the entire project (app, bootloader and partition table) to a new chip. Also if partition table has ota_data then this command will flash a initial ota_data.
|
||||
It allows to run the newly loaded app from a factory partition (or the first OTA partition, if factory partition is not present).
|
||||
The settings for serial port flashing can be configured with `make menuconfig`.
|
||||
|
||||
You don't need to run ``make all`` before running ``make flash``, ``make flash`` will automatically rebuild anything which needs it.
|
||||
|
||||
|
||||
Compiling & Flashing Just the App
|
||||
---------------------------------
|
||||
|
||||
After the initial flash, you may just want to build and flash just your app, not the bootloader and partition table:
|
||||
|
||||
* ``make app`` - build just the app.
|
||||
* ``make app-flash`` - flash just the app.
|
||||
|
||||
``make app-flash`` will automatically rebuild the app if it needs it.
|
||||
|
||||
There's no downside to reflashing the bootloader and partition table each time, if they haven't changed.
|
||||
|
||||
|
||||
The Partition Table
|
||||
-------------------
|
||||
|
||||
Once you've compiled your project, the "build" directory will contain a binary file with a name like "my_app.bin". This is an ESP32 image binary that can be loaded by the bootloader.
|
||||
|
||||
A single ESP32's flash can contain multiple apps, as well as many kinds of data (calibration data, filesystems, parameter storage, etc). For this reason, a partition table is flashed to offset 0x8000 in the flash.
|
||||
|
||||
Each entry in the partition table has a name (label), type (app, data, or something else), subtype and the offset in flash where the partition is loaded.
|
||||
|
||||
The simplest way to use the partition table is to `make menuconfig` and choose one of the simple predefined partition tables:
|
||||
|
||||
* "Single factory app, no OTA"
|
||||
* "Factory app, two OTA definitions"
|
||||
|
||||
In both cases the factory app is flashed at offset 0x10000. If you `make partition_table` then it will print a summary of the partition table.
|
||||
|
||||
For more details about :doc:`partition tables <../api-guides/partition-tables>` and how to create custom variations, view the :doc:`documentation <../api-guides/partition-tables>`.
|
||||
|
||||
@@ -0,0 +1,25 @@
|
||||
.. _get-started-customized-setup:
|
||||
|
||||
*****************************
|
||||
Customized Setup of Toolchain
|
||||
*****************************
|
||||
|
||||
Instead of downloading binary toolchain from Espressif website (see :ref:`get-started-setup-toolchain`) you may build the toolchain yourself.
|
||||
|
||||
If you can't think of a reason why you need to build it yourself, then probably it's better to stick with the binary version. However, here are some of the reasons why you might want to compile it from source:
|
||||
|
||||
- if you want to customize toolchain build configuration
|
||||
- if you want to use a different GCC version (such as 4.8.5)
|
||||
- if you want to hack gcc or newlib or libstdc++
|
||||
- if you are curious and/or have time to spare
|
||||
- if you don't trust binaries downloaded from the Internet
|
||||
|
||||
In any case, here are the instructions to compile the toolchain yourself.
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
windows-setup-scratch
|
||||
linux-setup-scratch
|
||||
macos-setup-scratch
|
||||
|
||||
117
docs/en/get-started-legacy/get-started/windows-setup-scratch.rst
Normal file
117
docs/en/get-started-legacy/get-started/windows-setup-scratch.rst
Normal file
@@ -0,0 +1,117 @@
|
||||
************************************
|
||||
Setup Windows Toolchain from Scratch
|
||||
************************************
|
||||
|
||||
Setting up the environment gives you some more control over the process, and also provides the information for advanced users to customize the install. The :doc:`pre-built environment <windows-setup>`, addressed to less experienced users, has been prepared by following these steps.
|
||||
|
||||
To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
|
||||
|
||||
|
||||
.. _configure-windows-toolchain-from-scratch:
|
||||
|
||||
Configure Toolchain & Environment from Scratch
|
||||
==============================================
|
||||
|
||||
This process involves installing MSYS2_, then installing the MSYS2_ and Python packages which ESP-IDF uses, and finally downloading and installing the Xtensa toolchain.
|
||||
|
||||
* Navigate to the MSYS2_ installer page and download the ``msys2-i686-xxxxxxx.exe`` installer executable (we only support a 32-bit MSYS environment, it works on both 32-bit and 64-bit Windows.) At time of writing, the latest installer is ``msys2-i686-20161025.exe``.
|
||||
|
||||
* Run through the installer steps. **Uncheck the "Run MSYS2 32-bit now" checkbox at the end.**
|
||||
|
||||
* Once the installer exits, open Start Menu and find "MSYS2 MinGW 32-bit" to run the terminal.
|
||||
|
||||
*(Why launch this different terminal? MSYS2 has the concept of different kinds of environments. The default "MSYS" environment is Cygwin-like and uses a translation layer for all Windows API calls. We need the "MinGW" environment in order to have a native Python which supports COM ports.)*
|
||||
|
||||
* The ESP-IDF repository on github contains a script in the tools directory titled ``windows_install_prerequisites.sh``. If you haven't got a local copy of the ESP-IDF yet, that's OK - you can just download that one file in Raw format from here: :idf_raw:`tools/windows/windows_install_prerequisites.sh`. Save it somewhere on your computer.
|
||||
|
||||
* Type the path to the shell script into the MSYS2 terminal window. You can type it as a normal Windows path, but use forward-slashes instead of back-slashes. ie: ``C:/Users/myuser/Downloads/windows_install_prerequisites.sh``. You can read the script beforehand to check what it does.
|
||||
|
||||
* The ``windows_install_prerequisites.sh`` script will download and install packages for ESP-IDF support, and the ESP32 toolchain.
|
||||
|
||||
|
||||
Troubleshooting
|
||||
~~~~~~~~~~~~~~~
|
||||
|
||||
* While the install script runs, MSYS may update itself into a state where it can no longer operate. You may see errors like the following::
|
||||
|
||||
*** fatal error - cygheap base mismatch detected - 0x612E5408/0x612E4408. This problem is probably due to using incompatible versions of the cygwin DLL.
|
||||
|
||||
If you see errors like this, close the terminal window entirely (terminating the processes running there) and then re-open a new terminal. Re-run ``windows_install_prerequisites.sh`` (tip: use the up arrow key to see the last run command). The update process will resume after this step.
|
||||
|
||||
* MSYS2 is a "rolling" distribution so running the installer script may install newer packages than what is used in the prebuilt environments. If you see any errors that appear to be related to installing MSYS2 packages, please check the `MSYS2-packages issues list`_ for known issues. If you don't see any relevant issues, please `raise an IDF issue`_.
|
||||
|
||||
|
||||
MSYS2 Mirrors in China
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
There are some (unofficial) MSYS2 mirrors inside China, which substantially improves download speeds inside China.
|
||||
|
||||
To add these mirrors, edit the following two MSYS2 mirrorlist files before running the setup script. The mirrorlist files can be found in the ``/etc/pacman.d`` directory (i.e. ``c:\msys2\etc\pacman.d``).
|
||||
|
||||
Add these lines at the top of ``mirrorlist.mingw32``::
|
||||
|
||||
Server = https://mirrors.ustc.edu.cn/msys2/mingw/i686/
|
||||
Server = http://mirror.bit.edu.cn/msys2/REPOS/MINGW/i686
|
||||
|
||||
Add these lines at the top of ``mirrorlist.msys``::
|
||||
|
||||
Server = http://mirrors.ustc.edu.cn/msys2/msys/$arch
|
||||
Server = http://mirror.bit.edu.cn/msys2/REPOS/MSYS2/$arch
|
||||
|
||||
|
||||
HTTP Proxy
|
||||
~~~~~~~~~~
|
||||
|
||||
You can enable an HTTP proxy for MSYS and PIP downloads by setting the ``http_proxy`` variable in the terminal before running the setup script::
|
||||
|
||||
export http_proxy='http://http.proxy.server:PORT'
|
||||
|
||||
Or with credentials::
|
||||
|
||||
export http_proxy='http://user:password@http.proxy.server:PORT'
|
||||
|
||||
Add this line to ``/etc/profile`` in the MSYS directory in order to permanently enable the proxy when using MSYS.
|
||||
|
||||
|
||||
Alternative Setup: Just download a toolchain
|
||||
============================================
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
If you already have an MSYS2 install or want to do things differently, you can download just the toolchain here:
|
||||
|
||||
|download_link_win32|
|
||||
|
||||
.. note::
|
||||
|
||||
If you followed instructions :ref:`configure-windows-toolchain-from-scratch`, you already have the toolchain and you won't need this download.
|
||||
|
||||
.. important::
|
||||
|
||||
Just having this toolchain is *not enough* to use ESP-IDF on Windows. You will need GNU make, bash, and sed at minimum. The above environments provide all this, plus a host compiler (required for menuconfig support).
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
|
||||
|
||||
.. _updating-existing-windows-environment:
|
||||
|
||||
Updating The Environment
|
||||
========================
|
||||
|
||||
When IDF is updated, sometimes new toolchains are required or new system requirements are added to the Windows MSYS2 environment.
|
||||
|
||||
Rather than setting up a new environment, you can update an existing Windows environment & toolchain:
|
||||
|
||||
- Update IDF to the new version you want to use.
|
||||
- Run the ``tools/windows/windows_install_prerequisites.sh`` script inside IDF. This will install any new software packages that weren't previously installed, and download and replace the toolchain with the latest version.
|
||||
|
||||
The script to update MSYS2 may also fail with the same errors mentioned under Troubleshooting_.
|
||||
|
||||
If you need to support multiple IDF versions concurrently, you can have different independent MSYS2 environments in different directories. Alternatively you can download multiple toolchains and unzip these to different directories, then use the PATH environment variable to set which one is the default.
|
||||
|
||||
.. _MSYS2: https://msys2.github.io/
|
||||
.. _MSYS2-packages issues list: https://github.com/Alexpux/MSYS2-packages/issues/
|
||||
.. _raise an IDF issue: https://github.com/espressif/esp-idf/issues/new
|
||||
70
docs/en/get-started-legacy/get-started/windows-setup.rst
Normal file
70
docs/en/get-started-legacy/get-started/windows-setup.rst
Normal file
@@ -0,0 +1,70 @@
|
||||
***************************************
|
||||
Standard Setup of Toolchain for Windows
|
||||
***************************************
|
||||
:link_to_translation:`zh_CN:[中文]`
|
||||
|
||||
Introduction
|
||||
============
|
||||
|
||||
Windows doesn't have a built-in "make" environment, so as well as installing the toolchain you will need a GNU-compatible environment. We use the MSYS2_ environment to provide this. You don't need to use this environment all the time (you can use :doc:`Eclipse <eclipse-setup>` or some other front-end), but it runs behind the scenes.
|
||||
|
||||
|
||||
Toolchain Setup
|
||||
===============
|
||||
|
||||
The quick setup is to download the Windows all-in-one toolchain & MSYS2 zip file from dl.espressif.com:
|
||||
|
||||
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip
|
||||
|
||||
Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment.
|
||||
|
||||
|
||||
Check it Out
|
||||
============
|
||||
|
||||
Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell. Create a directory named ``esp`` that is a default location to develop ESP32 applications. To do so, run the following shell command::
|
||||
|
||||
mkdir -p ~/esp
|
||||
|
||||
By typing ``cd ~/esp`` you can then move to the newly created directory. If there are no error messages you are done with this step.
|
||||
|
||||
.. figure:: ../../_static/msys2-terminal-window.png
|
||||
:align: center
|
||||
:alt: MSYS2 MINGW32 shell window
|
||||
:figclass: align-center
|
||||
|
||||
MSYS2 MINGW32 shell window
|
||||
|
||||
Use this window in the following steps setting up development environment for ESP32.
|
||||
|
||||
|
||||
Next Steps
|
||||
==========
|
||||
|
||||
To carry on with development environment setup, proceed to section :ref:`get-started-get-esp-idf`.
|
||||
|
||||
Updating The Environment
|
||||
========================
|
||||
|
||||
When IDF is updated, sometimes new toolchains are required or new requirements are added to the Windows MSYS2 environment. To move any data from an old version of the precompiled environment to a new one:
|
||||
|
||||
- Take the old MSYS2 environment (ie ``C:\msys32``) and move/rename it to a different directory (ie ``C:\msys32_old``).
|
||||
- Download the new precompiled environment using the steps above.
|
||||
- Unzip the new MSYS2 environment to ``C:\msys32`` (or another location).
|
||||
- Find the old ``C:\msys32_old\home`` directory and move this into ``C:\msys32``.
|
||||
- You can now delete the ``C:\msys32_old`` directory if you no longer need it.
|
||||
|
||||
You can have independent different MSYS2 environments on your system, as long as they are in different directories.
|
||||
|
||||
There are :ref:`also steps to update the existing environment without downloading a new one <updating-existing-windows-environment>`, although this is more complex.
|
||||
|
||||
Related Documents
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
windows-setup-scratch
|
||||
|
||||
|
||||
.. _MSYS2: https://msys2.github.io/
|
||||
Reference in New Issue
Block a user