Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Merge branch 'bugfix/docs_updates' into 'master'

Browse source 
Removed redundant 'Logging to Host' and docs cleaning

See merge request !1158
This commit is contained in:
Angus Gratton 2017-08-30 09:43:00 +08:00
commit 8bd6feedd4
13 changed files with 120 additions and 237 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

134
components/log/README.rst
View file

@ -6,7 +6,7 @@ Overview
Log library has two ways of managing log verbosity: compile time, set via menuconfig; and runtime, using ``esp_log_level_set`` function.
At compile time, filtering is done using ``CONFIG_LOG_DEFAULT_LEVEL`` macro, set via menuconfig. All logging statments for levels higher than ``CONFIG_LOG_DEFAULT_LEVEL`` will be removed by the preprocessor.
At compile time, filtering is done using ``CONFIG_LOG_DEFAULT_LEVEL`` macro, set via menuconfig. All logging statements for levels higher than ``CONFIG_LOG_DEFAULT_LEVEL`` will be removed by the preprocessor.
At run time, all logs below ``CONFIG_LOG_DEFAULT_LEVEL`` are enabled by default. ``esp_log_level_set`` function may be used to set logging level per module. Modules are identified by their tags, which are human-readable ASCII zero-terminated strings.
@ -33,7 +33,7 @@ Several macros are available for different verbosity levels:
* ``ESP_LOGD`` - debug
* ``ESP_LOGV`` - verbose
Additionally there is an _EARLY_ variant for each of these macros (e.g. ``ESP_EARLY_LOGE`` ).These variants can run in startup code, before heap allocator and syscalls have been initialized. When compiling bootloader, normal ``ESP_LOGx`` macros fall back to the same implementation as ``ESP_EARLY_LOGx`` macros. So the only place where ``ESP_EARLY_LOGx`` have to be used explicitly is the early startup code, such as heap allocator initialization code.
Additionally there is an _EARLY_ variant for each of these macros (e.g. ``ESP_EARLY_LOGE``). These variants can run in startup code, before heap allocator and syscalls have been initialized. When compiling bootloader, normal ``ESP_LOGx`` macros fall back to the same implementation as ``ESP_EARLY_LOGx`` macros. So the only place where ``ESP_EARLY_LOGx`` have to be used explicitly is the early startup code, such as heap allocator initialization code.
(Note that such distinction would not have been necessary if we would have an ``ets_vprintf`` function in the ROM. Then it would be possible to switch implementation from _EARLY_ version to normal version on the fly. Unfortunately, ``ets_vprintf`` in ROM has been inlined by the compiler into ``ets_printf``, so it is not accessible outside.)
@ -62,133 +62,5 @@ To configure logging output per module at runtime, add calls to ``esp_log_level_
Logging to Host via JTAG
^^^^^^^^^^^^^^^^^^^^^^^^
By default logging library uses vprintf-like function to write formatted output to dedicated UART. In general it invloves the following steps:
1. Format string is parsed to obtain type of each argument.
2. According to its type every argument is converted to string representation.
3. Format string combined with converted arguments is sent to UART.
Though implementation of vprintf-like function can be optimised to a certain level, all steps above have to be peformed in any case and every step takes some time (especially item 3). So it is frequent situation when addition of extra logging to the program to diagnose some problem changes its behaviour and problem dissapears or in the worst cases program can not work normally at all and ends up with an error or even hangs.
Possible ways to overcome this problem are to use faster UART bitrates (or another faster interface) and/or move string formatting procedure to the host.
ESP IDF has `Application Tracing` feature which allows to sent arbitrary application data to host via JTAG. This feature can also be used to transfer log information to host using ``esp_apptrace_vprintf`` function. This function does not perform full parsing of the format string and arguments, instead it just calculates number of arguments passed and sends them along with the format string address to the host. On the host log data are processed and printed out by a special Python script.
Config Options and Dependencies
"""""""""""""""""""""""""""""""
Using of the feature depends on two components:
1. Host side: Application tracing is done over JTAG, so it needs OpenOCD to be set up and running on host machine. For instructions how to set it up, please, see :idf:`OpenOCD setup for ESP32` section for details. **NOTE:** `in order to achieve higher data rates you may need to modify JTAG adapter working frequency in OpenOCD config file. Maximum tested stable speed is 26MHz, so you need to have the following statement in your configuration file` ``adapter_khz 26000`` `instead of default` ``adapter_khz 200``. `Actually maximum stable JTAG frequency can depend on host system configuration.`
2. Target side: Application tracing functionality can be enabled by ``CONFIG_ESP32_APPTRACE_ENABLE`` macro via menuconfig. This option enables the module and makes ``esp_apptrace_vprintf`` available for users.
Limitations
"""""""""""
Curent implmentation of logging over JTAG has several limitations:
1. Tracing from ``ESP_EARLY_LOGx`` macros is not supported.
2. No support for printf arguments which size exceeds 4 bytes (e.g. ``double`` and ``uint64_t``).
3. Only strings from .rodata section are supported as format strings and arguments.
4. Maximum number of printf arguments is 256.
How To Use It
"""""""""""""
To use logging via JTAG user needs to perform the following steps:
1. On target side special vprintf-like function needs to be installed. As it was mentioned earlier this function is ``esp_apptrace_vprintf``. It sends log data to the host via JTAG. Example code is shown below.
.. code-block:: c
#include "esp_app_trace.h"
...
void app_main()
{
// set log vprintf handler
esp_log_set_vprintf(esp_apptrace_vprintf);
...
// user code using ESP_LOGx starts here
// all data passed to ESP_LOGx are sent to host
...
// restore log vprintf handler
esp_log_set_vprintf(vprintf);
// flush last data to host
esp_apptrace_flush(ESP_APPTRACE_DEST_TRAX, 100000 /*tmo in us*/);
ESP_LOGI(TAG, "Tracing is finished."); // this will be printed out to UART
while (1);
}
2. Build the program image and download it to target as described in :idf:`Developing With the ESP-IDF` section.
3. Run OpenOCD (see :idf:`OpenOCD setup for ESP32` section).
4. Connect to OpenOCD telnet server. On Linux it can be done using the following command in terminal ``telnet <oocd_host> 4444``. If telnet session is opened on the same machine which runs OpenOCD you can use `localhost` as `<oocd_host>` in the command.
5. Run the following command in OpenOCD telnet session: ``esp108 apptrace start /path/to/trace/file 0 -1 -1 1``. This command will wait for board reset and transfer tracing data at the highest possible rate.
6. Reset the board. Logging to host will start automatically.
7. ``esp108 apptrace`` command with given arguments will never return (see other command options below), so you must stop it manually by resetting the board or pressing CTRL+C in OpenOCD window (not one with the telnet session).
8. Reset board or press CTRL+C in OpenOCD window (not one with the telnet session) when tracing is completed (for the example code above after the message `"Tracing is finished."` appears on UART).
9. To print out collected log records run the following command in terminal: ``$IDF_PATH/tools/esp_app_trace/logtrace_proc.py /path/to/trace/file /path/to/program/elf/file``.
OpenOCD Application Tracing Command Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Command usage:
``esp108 apptrace [start <outfile> [options] | [stop] | [status] | [dump <outfile>]``
Sub-commands:
* ``start``. Start tracing (continuous streaming).
* ``stop``. Stop tracing.
* ``status``. Get tracing status.
* ``dump``. Dump as much data as possible without waiting for trace memory block switch (post-mortem dump).
Start command syntax:
``start <outfile> [trace_size [stop_tmo [skip_size [poll_period [wait4halt]]]]]``
.. list-table::
:widths: 20 80
:header-rows: 1
* - Argument
- Description
* - outfile
- Path to log trace file to save data
* - trace_size
- Maximum size of data to collect (in bytes). Tracing is stopped after specified amount of data is received. By default -1 (trace size stop trigger is disabled).
* - stop_tmo
- Idle timeout (in ms). Tracing is stopped if there is no data for specified period of time. By default 10 s (-1 to disable this stop trigger).
* - skip_size
- Number of bytes to skip at the start. By default 0.
* - poll_period
- Data polling period (in ms). If greater then 0 then command runs in non-blocking mode, otherwise command line will not be avalable until tracing is stopped. By default 1 ms.
* - wait4halt
- If 0 start tracing immediately, otherwise command waits for the target to be halted (after reset, by breakpoint etc) and then automatically resumes it and starts tracing. By default 0.
Log Trace Processor Command Options
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
Command usage:
``logtrace_proc.py [-h] [--no-errors] <trace_file> <elf_file>``
Positional arguments:
.. list-table::
:widths: 20 80
:header-rows: 1
* - Argument
- Description
* - trace_file
- Path to log trace file
* - elf_file
- Path to program ELF file
Optional arguments:
.. list-table::
:widths: 20 80
:header-rows: 1
* - Argument
- Description
* - -h, --help
- show this help message and exit
* - --no-errors, -n
- Do not print errors
By default logging library uses vprintf-like function to write formatted output to dedicated UART. With calling a simple API, all log output my be routed to JTAG instead, and make the logging several times faster. For details please refer to section :ref:`app_trace-logging-to-host`.

33
docs/api-guides/app_trace.rst
View file

@ -43,7 +43,7 @@ Using of this feature depends on two components:
.. note::
In order to achieve higher data rates and minimize number of dropped packets it is recommended to modify JTAG adapter working frequency in respective OpenOCD config file, e.g. ``modules/esp-wroom-32.cfg``, if you are using ESP-WROOM-32 module. For example on ESP-WROVER-KIT board the maximum tested stable speed is 26MHz, so for this board you can update the following statement in your configuration file ``adapter_khz 26000``, instead of the default ``adapter_khz 20000``. Actually maximum stable JTAG frequency can depend on the host system configuration. In general JTAG clock should not exceed APB clock / 4.
In order to achieve higher data rates and minimize number of dropped packets it is recommended to optimize setting of JTAG clock frequency, so it is at maximum and still provides stable operation of JTAG, see :ref:`jtag-debugging-tip-optimize-jtag-speed`.
There are two additional menuconfig options not mentioned above:
@ -245,6 +245,8 @@ Command usage examples:
There is an option to configure target to halt after reset on start of scheduler. To do so, go to menuconfig and enable option *Stop program on scheduler start when JTAG/OCD is detected* under *Component config > FreeRTOS*.
.. _app_trace-logging-to-host:
Logging to Host
^^^^^^^^^^^^^^^
@ -279,28 +281,7 @@ How To Use It
In order to use logging via trace module user needs to perform the following steps:
1. On target side special vprintf-like function needs to be installed. As it was mentioned earlier this function is ``esp_apptrace_vprintf``. It sends log data to the host. Example code is shown below.
.. code-block:: c
#include "esp_app_trace.h"
...
void app_main()
{
// set log vprintf handler
esp_log_set_vprintf(esp_apptrace_vprintf);
...
// user code using ESP_LOGx starts here
// all data passed to ESP_LOGx are sent to host
...
// restore log vprintf handler
esp_log_set_vprintf(vprintf);
// flush last data to host
esp_apptrace_flush(ESP_APPTRACE_DEST_TRAX, 100000 /*tmo in us*/);
ESP_LOGI(TAG, "Tracing is finished."); // this will be printed out to UART
while (1);
}
1. On target side special vprintf-like function needs to be installed. As it was mentioned earlier this function is ``esp_apptrace_vprintf``. It sends log data to the host. Example code is provided in :example:`system/app_trace_to_host`.
2. Follow instructions in items 2-5 in `Application Specific Tracing`_.
3. To print out collected log records, run the following command in terminal: ``$IDF_PATH/tools/esp_app_trace/logtrace_proc.py /path/to/trace/file /path/to/program/elf/file``.
@ -401,11 +382,11 @@ Command usage examples:
.. highlight:: none
1. Collect SystemView tracing data to files "pro-cpu.str" and "pro-cpu.str". The files will be saved in "openocd-esp32" directory.
1. Collect SystemView tracing data to files "pro-cpu.SVDat" and "pro-cpu.SVDat". The files will be saved in "openocd-esp32" directory.
::
esp32 sysview start file://pro-cpu.str file://app-cpu.str
esp32 sysview start file://pro-cpu.SVDat file://app-cpu.SVDat
The tracing data will be retrieved and saved in non-blocking mode. To stop data this process enter ``esp32 apptrace stop`` command on OpenOCD telnet prompt, Optionally pressing Ctrl+C in OpenOCD window.
@ -413,7 +394,7 @@ Command usage examples:
::
esp32 sysview start file://pro-cpu.str file://app-cpu.str 0 -1 -1
esp32 sysview start file://pro-cpu.SVDat file://app-cpu.SVDat 0 -1 -1
OpenOCD telnet command line prompt will not be available until tracing is stopped. To stop tracing, press Ctrl+C in OpenOCD window.

4
docs/api-guides/jtag-debugging/configure-wrover.rst
View file

@ -7,7 +7,7 @@ All versions of ESP32 WROVER KIT boards have JTAG functionality build in. Puttin
Configure Hardware
^^^^^^^^^^^^^^^^^^
1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../get-started/get-started-wrover-kit`, section :ref:`esp-wrover-setup-options`.
1. Enable on-board JTAG functionality by setting JP8 according to :doc:`../../get-started/get-started-wrover-kit`, section :ref:`esp-wrover-kit-setup-options`.
2. Verify if ESP32 pins used for JTAG communication are not connected to some other h/w that may disturb JTAG operation:
@ -70,7 +70,7 @@ Linux
.. highlight:: none
2. Open a terminal, enter ``ls -l /dev/ttyUSB*`` command and check, if board's USB ports are recognized by the O/S. You are looking for similar result:
2. Open a terminal, enter ``ls -l /dev/ttyUSB*`` command and check, if board's USB ports are recognized by the OS. You are looking for similar result:
::

3
docs/api-guides/jtag-debugging/index.rst
View file

@ -11,7 +11,7 @@ GDB. The document is structured as follows:
:ref:`jtag-debugging-selecting-jtag-adapter`
What are the criteria and options to select JTAG adapter hardware.
:ref:`jtag-debugging-setup-openocd`
Procedure to install OpenOCD using prebuild software packages for :doc:`Windows <setup-openocd-windows>`, :doc:`Linux <setup-openocd-linux>` and :doc:`MacOS <setup-openocd-macos>` operating systems.
Procedure to install OpenOCD using prebuilt software packages for :doc:`Windows <setup-openocd-windows>`, :doc:`Linux <setup-openocd-linux>` and :doc:`MacOS <setup-openocd-macos>` operating systems.
:ref:`jtag-debugging-configuring-esp32-target`
Configuration of OpenOCD software and set up JTAG adapter hardware that will make together a debugging target.
:ref:`jtag-debugging-launching-debugger`
@ -285,6 +285,7 @@ This section provides collection of links to all tips and quirks referred to fro
* :ref:`jtag-debugging-tip-code-options`
* :ref:`jtag-debugging-tip-freertos-support`
* :ref:`jtag-debugging-tip-code-flash-voltage`
* :ref:`jtag-debugging-tip-optimize-jtag-speed`
* :ref:`jtag-debugging-tip-debugger-startup-commands`
* :ref:`jtag-debugging-tip-openocd-configure-target`
* :ref:`jtag-debugging-tip-reset-by-debugger`

48
docs/api-guides/jtag-debugging/tips-and-quirks.rst
View file

@ -56,6 +56,19 @@ To handle this issue OpenOCD's board configuration file (e.g. ``boards\esp-wroom
Check specification of ESP32 module connected to JTAG, what is the power supply voltage of SPI flash chip. Then set ``ESP32_FLASH_VOLTAGE`` accordingly. Most WROOM modules use 3.3V flash, while WROVER modules use 1.8V flash.
.. _jtag-debugging-tip-optimize-jtag-speed:
Optimize JTAG speed
^^^^^^^^^^^^^^^^^^^
In order to achieve higher data rates and minimize number of dropped packets it is recommended to optimize setting of JTAG clock frequency, so it is at maximum and still provides stable operation of JTAG. To do so use the following tips.
1. The upper limit of JTAG clock frequency is 20 MHz if CPU runs at 80 MHz, or 26 MHz if CPU runs at 160 MHz or 240 MHz.
2. Depending on particular JTAG adapter and the length of connecting cables, you may need to reduce JTAG frequency below 20 / 26 MHz.
3. In particular reduce frequency, if you get DSR/DIR errors (and they do not relate to OpenOCD trying to read from a memory range without physical memory being present there).
4. ESP-WROVER-KIT operates stable at 20 / 26 MHz.
.. _jtag-debugging-tip-debugger-startup-commands:
What is the meaning of debugger's startup commands?
@ -93,6 +106,8 @@ Adapter's clock speed
adapter_khz 20000
See :ref:`jtag-debugging-tip-optimize-jtag-speed` for guidance how to set this value.
Single core debugging
"""""""""""""""""""""
@ -167,7 +182,19 @@ The board can be reset by entering ``mon reset`` or ``mon reset halt`` into GDB.
Do not use JTAG pins for something else
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides ESP32 module and JTAG adapter.
Operation of JTAG may be disturbed, if some other h/w is connected to JTAG pins besides ESP32 module and JTAG adapter. ESP32 JTAG us using the following pins:
+---+----------------+-------------+
| | ESP32 JTAG Pin | JTAG Signal |
+===+================+=============+
| 1 | MTDO / GPIO15 | TDO |
+---+----------------+-------------+
| 2 | MTDI / GPIO12 | TDI |
+---+----------------+-------------+
| 3 | MTCK / GPIO13 | TCK |
+---+----------------+-------------+
| 4 | MTMS / GPIO14 | TMS |
+---+----------------+-------------+
JTAG communication will likely fail, if configuration of JTAG pins is changed by user application. If OpenOCD initializes correctly (detects the two Tensilica cores), but loses sync and spews out a lot of DTR/DIR errors when the program is ran, it is likely that the application reconfigures the JTAG pins to something else, or the user forgot to connect Vtar to a JTAG adapter that needed it.
@ -188,15 +215,22 @@ Below is an excerpt from series of errors reported by GDB after the application
Reporting issues with OpenOCD / GDB
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
In case you encounter a problem with OpenOCD or GDB programs itself, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues.
In case you encounter a problem with OpenOCD or GDB programs itself and do not find a solution searching available resources on the web, open an issue in the OpenOCD issue tracker under https://github.com/espressif/openocd-esp32/issues.
Create a simple example that is representative to observed issue. Describe steps how to reproduce it. In such an example debugging should not be affected by non-deterministic behaviour introduced by the Wi-Fi stack, so problems will likely be easier to reproduce, if encountered once.
1. In issue report provide details of your configuration:
Prepare logs from debugging session by adding additional parameters to start up commands.
a. JTAG adapter type.
b. Release of ESP-IDF used to compile and load application that is being debugged.
c. Details of OS used for debugging.
d. Is OS running natively on a PC or on a virtual machine?
2. Create a simple example that is representative to observed issue. Describe steps how to reproduce it. In such an example debugging should not be affected by non-deterministic behaviour introduced by the Wi-Fi stack, so problems will likely be easier to reproduce, if encountered once.
.. highlight:: bash
OpenOCD:
3. Prepare logs from debugging session by adding additional parameters to start up commands.
OpenOCD:
::
@ -212,7 +246,7 @@ OpenOCD:
See :ref:`jtag-debugging-building-openocd` for slightly different command format, when running OpenOCD built from sources.
Debugger:
Debugger:
::
@ -221,4 +255,4 @@ Debugger:
Optionally add command ``remotelogfile gdb_log.txt`` to the ``gdbinit`` file.
Attach both ``openocd_log.txt`` and ``gdb_log.txt`` files to your issue report.
4. Attach both ``openocd_log.txt`` and ``gdb_log.txt`` files to your issue report.

18
docs/api-reference/peripherals/touch_pad.rst
View file

@ -1,20 +1,18 @@
Touch sensor
===========
Touch Sensor
============
Overview
--------
A touch-sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface.
When a user touches the surface, the capacitance variation is triggered and a binary signal is generated to indicate whether the touch is valid.
A touch-sensor system is built on a substrate which carries electrodes and relevant connections under a protective flat surface. When a user touches the surface, the capacitance variation is triggered and a binary signal is generated to indicate whether the touch is valid.
ESP32 can provide up to 10 capacitive touch pads / GPIOs. The sensing pads can be arranged in different combinations,
so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.
ESP32 can provide up to 10 capacitive touch pads / GPIOs. The sensing pads can be arranged in different combinations, so that a larger area or more points can be detected. The touch pad sensing process is under the control of a hardware-implemented finite-state machine (FSM) which is initiated by software or a dedicated hardware timer.
Application Example
-------------------
Application Examples
--------------------
Touch sensor read example: :example:`peripherals/touch_pad_read`.
Touch sensor interrupt example: :example:`peripherals/touch_pad_interrupt`.
- Touch sensor read example: :example:`peripherals/touch_pad_read`.
- Touch sensor interrupt example: :example:`peripherals/touch_pad_interrupt`.
API Reference
-------------

2
docs/get-started/get-started-devkitc.rst
View file

@ -49,7 +49,7 @@ Before powering up the ESP32-DevKitC, please make sure that the board has been r
To start development of applications, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toochain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing

4
docs/get-started/get-started-wrover-kit-v2.rst
View file

@ -1,7 +1,7 @@
ESP-WROVER-KIT V2 Getting Started Guide
=======================================
This user guide shows how to get started with ESP-WROVER-KIT V2 development board including description of its functionality and configuration options. You can find out what version you have in section :doc:`../hw-reference/modules-and-boards`.
This user guide shows how to get started with ESP-WROVER-KIT V2 development board including description of its functionality and configuration options. You can find out what version you have in section :ref:`esp-modules-and-boards-esp-wrover-kit`.
If you like to start using this board right now, go directly to section :ref:`esp-wrover-kit-v2-start-development`.
@ -163,7 +163,7 @@ Now to Development
To start development of applications for ESP32-DevKitC, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toochain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing

9
docs/get-started/get-started-wrover-kit.rst
View file

@ -1,7 +1,7 @@
ESP-WROVER-KIT V3 Getting Started Guide
=======================================
This user guide shows how to get started with ESP-WROVER-KIT V3 development board including description of its functionality and configuration options. You can find out what version you have in section :doc:`../hw-reference/modules-and-boards`.
This user guide shows how to get started with ESP-WROVER-KIT V3 development board including description of its functionality and configuration options. You can find out what version you have in section :ref:`esp-modules-and-boards-esp-wrover-kit`.
If you like to start using this board right now, go directly to section :ref:`esp-wrover-kit-start-development`.
@ -314,7 +314,7 @@ Now to Development
To start development of applications for ESP-WROVER-KIT, proceed to section :doc:`index`, that will walk you through the following steps:
* :ref:`get-started-setup-toochain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-setup-toolchain` in your PC to develop applications for ESP32 in C language
* :ref:`get-started-connect` the module to the PC and verify if it is accessible
* :ref:`get-started-build-flash` an example application to the ESP32
* :ref:`get-started-build-monitor` instantly what the application is doing
@ -340,3 +340,8 @@ Related Documents
.. |jp14| image:: ../_static/wrover-jp14.png
.. _ESP-WROVER-KIT V3 schematic: http://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-3.pdf
.. toctree::
:hidden:
get-started-wrover-kit-v2.rst

51
docs/get-started/index.rst
View file

@ -63,21 +63,12 @@ If you have one of ESP32 development boards listed below, click on provided link
If you have different board, move to sections below.
.. _get-started-setup-toochain:
.. _get-started-setup-toolchain:
Setup Toolchain
===============
Depending on your experience and preferences, you may follow standard installation process or customize your environment. Instructions immediately below are for standard installation. To set up the system your own way go to section :ref:`get-started-customized-setup`.
.. _get-started-standard-setup:
Standard Setup of Toolchain
---------------------------
The quickest way to start development with ESP32 is by installing prebuild toolchain. Pick up your O/S below and follow provided instructions.
The quickest way to start development with ESP32 is by installing a prebuilt toolchain. Pick up your OS below and follow provided instructions.
.. toctree::
:hidden:
@ -107,44 +98,21 @@ The quickest way to start development with ESP32 is by installing prebuild toolc
.. note::
We are using ``~/esp`` directory to install prebuild toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
We are using ``~/esp`` directory to install the prebuilt toolchain, ESP-IDF and sample applications. You can use different directory, but need to adjust respective commands.
Depending on your experience and preferences, instead of using a prebuilt toolchain, you may want to customize your environment. To set up the system your own way go to section :ref:`get-started-customized-setup`.
Once you are done with setting up the toolchain then go to section :ref:`get-started-get-esp-idf`.
.. highlight:: bash
.. _get-started-customized-setup:
Customized Setup of Toolchain
-----------------------------
Instead of downloading binary toolchain from Espressif website (:ref:`get-started-standard-setup` above) 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
.. _get-started-get-esp-idf:
Get ESP-IDF
===========
Once you have the toolchain (that contains programs to compile and build the application) installed, you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
.. highlight:: bash
Besides the toolchain (that contains programs to compile and build the application), you also need ESP32 specific API / libraries. They are provided by Espressif in `ESP-IDF repository <https://github.com/espressif/esp-idf>`_. To get it, open terminal, navigate to the directory you want to put ESP-IDF, and clone it using ``git clone`` command::
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
@ -283,6 +251,7 @@ If there are no issues, at the end of build process, you should see messages des
If you'd like to use the Eclipse IDE instead of running ``make``, check out the :doc:`Eclipse guide <eclipse-setup>`.
.. _get-started-build-monitor:
Monitor
@ -324,4 +293,4 @@ Related Documents
make-project
eclipse-setup
idf-monitor
toolchain-setup-scratch

25
docs/get-started/toolchain-setup-scratch.rst Normal file
View file

@ -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

2
docs/get-started/windows-setup-scratch.rst
View file

@ -4,7 +4,7 @@ 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 prebuild environment, proceed to section :doc:`windows-setup`.
To quickly setup the toolchain in standard way, using a prebuilt environment, proceed to section :doc:`windows-setup`.
.. _configure-windows-toolchain-from-scratch:

4
docs/hw-reference/modules-and-boards.rst
View file

@ -132,9 +132,7 @@ This is updated version of ESP32 DevKitJ V1 described above with design improvem
Comparing to previous version, this board has a shiny black finish and a male camera header.
* `Schematic V2 <http://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf>`__ (PDF)
.. * :doc:`../get-started/get-started-wrover-kit-v2`
* :doc:`../get-started/get-started-wrover-kit-v2`
* :doc:`../api-guides/jtag-debugging/index`
* `FTDI Virtual COM Port Drivers`_