alex/esp-idf
alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2024-10-05 20:47:46 -04:00
Code Issues Actions 2 Packages Projects Releases Wiki Activity

docs: Minor cleanup of getting started docs

Browse Source
This commit is contained in:
Angus Gratton 2018-05-25 16:22:18 +10:00 committed by Angus Gratton
parent 2f433e4342
commit e100acbb73
3 changed files with 29 additions and 27 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

2
docs/en/get-started/establish-serial-connection.rst
View File

@ -71,7 +71,7 @@ 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 avilable for both Windows and Linux. You can use other serial program and set communication parameters like below.
Now verify that the serial connection is operational. You can do this using a serial terminal program. Windows and Linux users can use the `PuTTY SSH Client <http://www.putty.org/>`_ for this. Alternatively, any other serial program can be used with the communication parameters shown 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.

47
docs/en/get-started/index.rst
View File

@ -2,7 +2,7 @@
Get Started
***********
This document is intended to help users set up the software environment for developement of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
This document is intended to help users set up the software environment for development of applications using hardware based on the Espressif ESP32. Through a simple example we would like to illustrate how to use ESP-IDF (Espressif IoT Development Framework), including the menu based configuration, compiling the ESP-IDF and firmware download to ESP32 boards.
.. note::
The CMake-based build system is currently in preview release. Documentation may have missing gaps, and you may enocunter bugs (please report these). To view documentation for the older GNU Make based build system, switch versions to the 'latest' master branch or a stable release.
@ -22,7 +22,8 @@ What You Need
To develop applications for ESP32 you need:
* **PC** loaded with either Windows, Linux or Mac operating system
* **Toolchain** to build the **Application** for ESP32
* **Toolchain** to compile code for ESP32
* **Build tools** CMake and Ninja to build a full **Application** for ESP32
* **ESP-IDF** that essentially contains API for ESP32 and scripts to operate the **Toolchain**
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
@ -34,28 +35,23 @@ To develop applications for ESP32 you need:
Development of applications for ESP32
Preparation of development environment consists of three steps:
Development Environment Steps:
1. Setup of **Toolchain**
2. Getting of **ESP-IDF** from GitHub
3. Installation and configuration of **Eclipse**
2. Getting **ESP-IDF** from GitHub
You may skip the last step, if you prefer to use different editor.
Having environment set up, you are ready to start the most interesting part - the application development. This process may be summarized in four steps:
Once the development environment is set up, we will follow these steps to create an ESP-IDF application:
1. Configuration of a **Project** and writing the code
2. Compilation of the **Project** and linking it to build an **Application**
3. Flashing (uploading) of the **Application** to **ESP32**
4. Monitoring / debugging of the **Application**
See instructions below that will walk you through these steps.
3. Flashing (uploading) the compiled **Application** to **ESP32** over a USB/serial connection
4. Monitoring / debugging of the **Application** output via USB/serial
Guides
======
Development Board Guides
========================
If you have one of ESP32 development boards listed below, click on provided links to get you up and running.
If you have one of ESP32 development boards listed below, click on the link for hardware setup:
.. toctree::
:maxdepth: 1
@ -125,7 +121,7 @@ ESP-IDF will be downloaded into ``~/esp/esp-idf``.
.. highlight:: batch
For Windows Command Prompt users, the equivalent commands are::
For **Windows Command Prompt** users, the equivalent commands are::
mkdir %userprofile%\esp
cd %userprofile%\esp
@ -176,7 +172,7 @@ Copy :example:`get-started/hello_world` to ``~/esp`` directory::
.. highlight:: batch
For Windows Command Prompt users, the equivalent commands are::
For **Windows Command Prompt** users, the equivalent commands are::
cd %userprofile%\esp
xcopy /e /i %IDF_PATH%\examples\get-started\hello_world hello_world
@ -187,7 +183,7 @@ It is also possible to build examples in-place, without copying them first.
.. important::
The esp-idf build system does not support spaces in paths to esp-idf or to projects.
The esp-idf build system does not support spaces in the path to either esp-idf or to projects.
.. _get-started-connect:
@ -197,7 +193,6 @@ Connect
You are almost there. To be able to proceed further, connect ESP32 board to PC, check under what serial port the board is visible and verify if serial communication works. If you are not sure how to do it, check instructions in section :doc:`establish-serial-connection`. Note the port number, as it will be required in the next step.
.. _get-started-configure:
Configure
@ -212,7 +207,7 @@ Being in terminal window, go to directory of ``hello_world`` application by typi
.. highlight:: batch
For Windows Command Prompt users::
For **Windows Command Prompt** users::
cd %userprofile%\esp\hello_world
idf.py menuconfig
@ -235,7 +230,7 @@ If previous steps have been done correctly, the following menu will be displayed
Here are couple of tips on navigation and use of ``menuconfig``:
* Use up & down arrow keys to navigate the menu.
* Use Enter key to go into a submenu, Escape key to go out or to exit.
* Use Enter key to go into a submenu, Escape key to go up a level or exit.
* Type ``?`` to see a help screen. Enter key exits the help screen.
* Use Space key, or ``Y`` and ``N`` keys to enable (Yes) and disable (No) configuration items with checkboxes "``[*]``"
* Pressing ``?`` while highlighting a configuration item displays help about that item.
@ -329,7 +324,7 @@ This step will flash the binaries that you just built to your ESP32 board.
If there are no issues, at the end of build process, you should see messages describing progress of flashing the project binary image onto the ESP32. Finally, the module will be reset and "hello_world" application will be running there.
If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. (Not currently supported) If you'd like to use the Eclipse IDE instead of running ``idf.py``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. _get-started-build-monitor:
@ -369,7 +364,7 @@ To exit the monitor use shortcut ``Ctrl+]``.
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
or monitor fails shortly after upload, your board is likely using 26MHz crystal, while the ESP-IDF assumes default of 40MHz. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
or monitor fails shortly after upload, your board is likely using 26MHz crystal. Most development board designs use 40MHz and the ESP-IDF uses this default value. Exit the monitor, go back to the :ref:`menuconfig <get-started-configure>`, change :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` to 26MHz, then :ref:`build and flash <get-started-build-flash>` the application again. This is found under ``idf.py menuconfig`` under Component config --> ESP32-specific --> Main XTAL frequency.
.. note::
@ -401,7 +396,7 @@ Another solution is to update only what has changed. This method is useful if yo
.. highlight:: batch
For Windows Command Prompt users::
For **Windows Command Prompt** users::
cd %userprofile%\esp\esp-idf
git pull
@ -411,7 +406,7 @@ The ``git pull`` command is fetching and merging changes from ESP-IDF repository
.. highlight:: bash
If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
To use a specific release of ESP-IDF, e.g. `v2.1`, run::
cd ~/esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
@ -421,7 +416,7 @@ If you would like to use specific release of ESP-IDF, e.g. `v2.1`, run::
.. highlight:: batch
For Windows Command Prompt users::
For **Windows Command Prompt** users::
cd %userprofile%\esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1

7
docs/en/get-started/macos-setup.rst
View File

@ -32,6 +32,13 @@ ESP-IDF will use the version of Python installed by default on Mac OS.
- It is strongly recommended to also install ccache_ for faster builds. If you have HomeBrew_, this can be done via ``brew install ccache`` or ``sudo port install ccache`` on MacPorts_.
.. note::
If an error like this is shown during any step::
xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun
Then you will need to install the XCode command line tools to continue. You can install these by running ``xcode-select --install``.
Toolchain Setup
===============