eaw/esp-idf
1
0
Fork 0
Code Issues Packages 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
parent b4eda4c4f7 8c3169b6be
commit 8bd6feedd4
13 changed files with 120 additions and 237 deletions
Download Patch File Download Diff File Expand all files Collapse all files

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`

68
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,37 +215,44 @@ 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:
bin/openocd -l openocd_log.txt -d 3 -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
::
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level ``-d 3`` is set. If you still like to see the log on the screen, then use another command instead:
bin/openocd -l openocd_log.txt -d 3 -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg
::
Logging to a file this way will prevent information displayed on the terminal. This may be a good thing taken amount of information provided, when increased debug level ``-d 3`` is set. If you still like to see the log on the screen, then use another command instead:
bin/openocd -d 3 -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg 2>&1 | tee openocd.log
::
.. note::
bin/openocd -d 3 -s share/openocd/scripts -f interface/ftdi/esp32_devkitj_v1.cfg -f board/esp-wroom-32.cfg 2>&1 | tee openocd.log
See :ref:`jtag-debugging-building-openocd` for slightly different command format, when running OpenOCD built from sources.
.. note::
Debugger:
See :ref:`jtag-debugging-building-openocd` for slightly different command format, when running OpenOCD built from sources.
::
Debugger:
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
::
Optionally add command ``remotelogfile gdb_log.txt`` to the ``gdbinit`` file.
xtensa-esp32-elf-gdb -ex "set remotelogfile gdb_log.txt" <all other options>
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`_