Skip to content

Commit d4ec1e6

Browse files
kolipakakondalkolipakakondal
committed
update docs
1 parent 4acd222 commit d4ec1e6

File tree

7 files changed

+280
-1
lines changed

7 files changed

+280
-1
lines changed

‎docs/en/additionalfeatures.rst‎

Lines changed: 2 additions & 1 deletion
Original file line numberDiff line numberDiff line change
@@ -10,4 +10,5 @@ Additional IDE Features
1010
CMake Editor<additionalfeatures/cmakeeditor>
1111
Configure CDT Build Environment Variables<additionalfeatures/configureenvvariables>
1212
Configuring Clang Toolchain<additionalfeatures/clangtoolchain>
13-
Switching Language<additionalfeatures/switchlanguage>
13+
Switching Language<additionalfeatures/switchlanguage>
14+
Heap Tracing<additionalfeatures/heaptracing>

‎docs/en/additionalfeatures/heaptracing.rst‎

Lines changed: 87 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,87 @@
1+
.. _heap_tracing:
2+
3+
Heap Tracing
4+
============
5+
6+
Heap tracing enables you to monitor memory usage over time by generating and analyzing a `svdat` dump file. The IDF Eclipse Plugin supports generating heap trace files through special breakpoints. For more information on SDK-level configuration and tracing features, refer to the official `ESP-IDF documentation <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/heap_debug.html>`_.
7+
8+
Generating Dump File
9+
--------------------
10+
1. **Open the sysview\_heap\_log.c file**
11+
12+
From the Project Explorer, locate and open the `sysview_heap_log.c` file from the **system** templates project.
13+
14+
.. image:: ../../../media/HeapTracing/sysview_heap_log_file.PNG
15+
:alt: sysview_heap_log.c file
16+
17+
2. **Add a Breakpoint and Configure Properties**
18+
19+
Add a breakpoint at the desired line, then right-click on the breakpoint icon in the editor and select `Breakpoint Properties…`.
20+
21+
.. image:: ../../../media/HeapTracing/breakpoint_properties_popup.png
22+
:alt: Breakpoint Properties
23+
24+
3. **Define Heap Tracing Action**
25+
26+
In the Breakpoint Properties window, go to `Actions`, click `New`, and select `Heap Tracing` from the `Action Type` dropdown.
27+
- For the initial breakpoint, set the action to **Start Heap Trace** and specify the save location for the dump file (recommended to store in the project directory). Name the action meaningfully, then click OK.
28+
29+
.. image:: ../../../media/HeapTracing/heap_tracing_action.png
30+
:alt: Heap Tracing Action
31+
32+
4. **Attach the Action to the Breakpoint**
33+
34+
After creating the action, click `Attach` to link it to the breakpoint, which will display it under the Actions for this breakpoint section.
35+
36+
.. image:: ../../../media/HeapTracing/breakpoint_properties_actions_start_attached.png
37+
:alt: Attach Action
38+
39+
5. **Apply and Create Additional Breakpoint**
40+
41+
Now you have a breakpoint that will start tracing and generate a dump file. To stop the tracing, create another breakpoint (e.g., at line 102), set its properties, and choose the **Stop Heap Trace** option in the action settings. Attach this action to the breakpoint as shown below.
42+
43+
.. image:: ../../../media/HeapTracing/breakpoint_properties_actions_stop_attached.png
44+
:alt: Stop Heap Trace Action
45+
46+
6. **Launch Debug Configuration**
47+
48+
Launch the debug configuration for your ESP32 board. When the program hits the breakpoints, the IDE will prompt you to switch to the debugger perspective. Continue execution for each breakpoint to start and stop tracing. Refresh the project in the Project Explorer to view the dump file in the specified location.
49+
50+
Analyzing the Dump File
51+
-----------------------
52+
53+
The IDF Eclipse Plugin allows you to analyze generated `svdat` dump files. Right-click on the dump file and select `Heap Dump Analysis` from the context menu.
54+
55+
**Note:** Ensure the project is built with the appropriate symbols file to enable analysis.
56+
57+
.. image:: ../../../media/HeapTracing/analysis_context_menu.png
58+
:alt: Heap Dump Analysis Context Menu
59+
60+
Overview Tab
61+
-------------
62+
The Overview Tab displays memory consumption over time in a graph format. By default, all contexts are shown; you can select specific contexts corresponding to heap events.
63+
64+
.. image:: ../../../media/HeapTracing/overview_tab_tracing.png
65+
:alt: Memory Consumption Graph
66+
67+
For example, selecting multiple contexts displays them separately on the graph.
68+
69+
.. image:: ../../../media/HeapTracing/overview_tab_tracing_contexts.png
70+
:alt: Selected Contexts in Graph
71+
72+
Details Tab
73+
-------------
74+
The Details Tab provides further insights, showing each event in the heap trace. Rows highlighted in light orange indicate potential memory leaks (since the trace may have ended before a free event was detected). Green rows show free heap events.
75+
76+
.. image:: ../../../media/HeapTracing/details_tab_tracing.png
77+
:alt: Details Tab
78+
79+
To filter entries for possible memory leaks, check the `View Possible Memory Leaks` box. Right-clicking on any entry allows you to view callers, opening the `Callers View` to display the call stack for the heap event.
80+
81+
.. image:: ../../../media/HeapTracing/show_callers_context_menu.png
82+
:alt: Show Callers
83+
84+
Clicking on an entry in the `Callers View` will navigate to the corresponding line in the source file.
85+
86+
.. image:: ../../../media/HeapTracing/callers_view.png
87+
:alt: Callers View

‎docs/en/index.rst‎

Lines changed: 1 addition & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -52,5 +52,6 @@ For more about this project please see https://github.com/espressif/idf-eclipse-
5252
Monitor the Output<monitoroutput>
5353
Debug Your Project<debugproject>
5454
Additional IDE Features<additionalfeatures>
55+
Troubleshooting<troubleshooting>
5556
FAQs<faqs>
5657
Downloads<downloads>

‎docs/en/installation.rst‎

Lines changed: 2 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -6,6 +6,8 @@ Configuring and installing the Espressif-IDE involves two main steps:
66
1. :ref:`Installing the Espressif-IDE <esp-idf-installation>`
77
2. :ref:`Installing the ESP-IDF and related tools within the Espressif-IDE <esp-idf-tools-installation>`
88

9+
For Eclipse CDT users who prefer installing the ESP-IDF Eclipse Plugin via the Update site, please refer to the :ref:`Update Site Installation Guide <marketplaceupdate>`.
10+
911
Espressif-IDE Installation
1012
----------------------------
1113
.. _esp-idf-installation:

‎docs/en/marketplaceupdate.rst‎

Lines changed: 94 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,94 @@
1+
.. _marketplaceupdate:
2+
3+
Update Site Installation Guide
4+
======================================
5+
6+
.. toctree::
7+
:maxdepth: 2
8+
:caption: Contents:
9+
10+
installUpdateSiteURL
11+
install_idf_eclipse_plugin_marketplace
12+
install_idf_eclipse_plugin_local_archive
13+
upgradePlugins
14+
15+
16+
.. _installUpdateSiteURL:
17+
18+
Installing IDF Plugin using update site URL
19+
--------------------------------------------
20+
You can install the IDF Eclipse plugin into an existing IDE using the update site URL. First, add the release repository URL as follows:
21+
22+
1. Go to `Help` > `Install New Software`.
23+
2. Click `Add…`, and in the pop-up window:
24+
* Enter `Name` as `Espressif IDF Plugin for Eclipse`.
25+
* Enter `Location` of the repository
26+
* For the stable release: `<https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/>`_.
27+
* Click `Add`.
28+
3. Select `Espressif IDF` from the list and proceed with the installation.
29+
30+
For adding beta and nightly builds, you can use the following update site URLs:
31+
* For Beta version: `<https://dl.espressif.com/dl/idf-eclipse-plugin/updates/beta/>`_.
32+
* For Nightly build: `<https://dl.espressif.com/dl/idf-eclipse-plugin/updates/nightly/>`_.
33+
34+
> **Note:** While the screenshots are captured on macOS, the installation instructions are applicable to Windows, Linux, and macOS.
35+
36+
.. image:: ../../media/idf_update_site_install.png
37+
38+
39+
.. _install_idf_eclipse_plugin_marketplace:
40+
41+
Installing IDF Eclipse Plugin from Eclipse Marketplace
42+
------------------------------------------------------
43+
44+
To install the ESP-IDF Eclipse Plugin from the Eclipse Marketplace, follow these steps:
45+
46+
1. Open Eclipse and go to `Help` > `Eclipse Marketplace...`.
47+
48+
2. In the search box, enter **ESP-IDF Eclipse Plugin** to locate the plugin.
49+
50+
3. Click **Install** and follow the on-screen instructions to complete the installation.
51+
52+
4. After installation, restart Eclipse to activate the plugin.
53+
54+
55+
.. _install_idf_eclipse_plugin_local_archive:
56+
57+
Installing IDF Eclipse Plugin from Local Archive
58+
------------------------------------------------------
59+
60+
To install the ESP-IDF Eclipse Plugin from a local archive, follow these steps:
61+
62+
1. Download the latest update site archive for the IDF Eclipse Plugin from [here](https://github.com/espressif/idf-eclipse-plugin/releases).
63+
64+
2. In Eclipse, go to `Help` > `Install New Software`.
65+
66+
3. Click the `Add…` button.
67+
68+
4. In the **Add Repository** dialog, select **Archive** and choose the file `com.espressif.idf.update-vxxxxxxx.zip`.
69+
70+
5. Click **Add**.
71+
72+
6. Select **Espressif IDF** from the list and proceed with the installation.
73+
74+
7. Restart Eclipse after the installation is complete.
75+
76+
77+
.. _upgradePlugins:
78+
79+
How do I upgrade my existing IDF Eclipse Plugin?
80+
------------------------------------------------------
81+
If you are installing the IDF Eclipse Plugin for the first time, follow these steps to add the repository for the new release:
82+
83+
1. Go to `Window` > `Preferences` > `Install/Update` > `Available Software Sites`.
84+
2. Click `Add`.
85+
3. Enter the URL of the new repository: `https://dl.espressif.com/dl/idf-eclipse-plugin/updates/latest/`.
86+
4. Click `Ok`.
87+
88+
If you have already installed the IDF Eclipse Plugin using the update site URL, you can upgrade to the latest version with the following steps:
89+
90+
1. Go to `Help` > `Check for Updates`.
91+
2. If updates are found, select `Espressif IDF Plugins for Eclipse` and deselect all other items.
92+
3. Click `Next` to proceed with the installation.
93+
94+
.. image:: ../../media/Update_plugins.png

‎docs/en/monitoroutput.rst‎

Lines changed: 26 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -1,2 +1,28 @@
1+
.. _serialMonitor:
2+
13
Monitor the Output
24
===============================
5+
6+
To see the serial output in Eclipse, we need to configure the `ESP-IDF Serial Monitor` to connect to the serial port. This is integrated with the `IDF Monitor`. Please check more details in the official documentation `here <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-monitor.html#idf-monitor>`_.
7+
8+
.. image:: https://github.com/espressif/idf-eclipse-plugin/assets/8463287/993a1fa2-9c6e-4b0e-a245-713df30331e7
9+
:alt: Serial Monitor
10+
11+
To configure the serial monitor, follow the steps below:
12+
13+
1. Click on the `Open a Terminal` icon from the toolbar.
14+
2. Choose `ESP-IDF Serial Monitor` from the terminal drop-down.
15+
3. Select the `Serial Port` for your board if it's not detected.
16+
4. Configure serial monitor filter options for output filtering.
17+
5. Click on `OK` to launch the terminal, which will listen to the USB port.
18+
19+
.. image:: ../../media//10_serial_terminal.png
20+
21+
22+
ESP-IDF Serial Monitor Settings
23+
-------------------------------
24+
ESP-IDF Serial Monitor will allow you to configure the default settings of the serial monitor character limit and number of lines.
25+
26+
1. Navigate to `Espressif` from the Eclipse Preferences.
27+
2. Click on `ESP-IDF Serial Monitor Settings`.
28+
3. Provide `Console Line Width` and `Limit Console Output`.

‎docs/en/troubleshooting.rst‎

Lines changed: 68 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,68 @@
1+
.. _troubleshooting:
2+
3+
Troubleshooting
4+
===============
5+
6+
Suggestions for Build Errors using Hints Viewer
7+
-----------------------------------------------------------
8+
If you encounter a problem during a build, there may be a hint for this error in the ESP-IDF hint database, located at ``tools/idf_py_actions/hints.yml`` in ESP-IDF. The ESP-IDF Eclipse plugin provides a hint viewer where you can type an error message to find a hint for it.
9+
10+
**Prerequisites:** The ``hints.yml`` file is available from ESP-IDF v5.0 and higher. If you are using an older version, you can manually download the ``hints.yml`` file from `here <https://github.com/espressif/esp-idf/blob/master/tools/idf_py_actions/hints.yml>`_ and save it to ``esp-idf/tools/idf_py_actions/``. To download the file, right-click the ``Raw`` button and select ``Save as...``.
11+
12+
To open the hints viewer:
13+
1. Navigate to ``Windows`` -> ``Show View`` -> ``Other...`` -> ``Espressif`` -> ``Hints``.
14+
15+
.. image:: https://user-images.githubusercontent.com/24419842/189666994-78cc8b24-b934-426f-9df5-79af28c50c55.png
16+
:alt: Hints Viewer
17+
18+
Now you can type or paste an error from the build log, such as:
19+
``ccache error: Failed to create temporary file for esp-idf/libsodium/CMakeFiles/..../....: No such file or directory``
20+
21+
.. image:: https://user-images.githubusercontent.com/24419842/189672552-994624f3-c0c5-48e6-aa2c-61e4ed8915e5.png
22+
:alt: Example Error in Hints Viewer
23+
24+
Double-clicking on the row will display the hint message if it doesn't fully fit on your screen.
25+
26+
.. image:: https://user-images.githubusercontent.com/24419842/189673174-8ce40cda-6933-4dc4-a555-5d2ca617256e.png
27+
:alt: Hint Message
28+
29+
Error Log
30+
---------
31+
The Error Log view captures warnings and errors logged by plug-ins. The log file is stored in the ``.log`` file within the ``.metadata`` subdirectory of the workspace.
32+
33+
To open the Error Log view:
34+
- Go to ``Window`` > ``Show View`` > ``Error Log``.
35+
36+
To export the current log view content:
37+
1. Press the ``Export Log`` toolbar button or select ``Export Log...`` from the context menu.
38+
2. Enter a file name.
39+
40+
It's recommended to include an error log when reporting an issue.
41+
42+
.. image:: ../../media/export_log.png
43+
:alt: Export Log
44+
45+
Console View Log
46+
----------------
47+
The Console View shows warnings and errors related to the current running process or build. To access the Console View:
48+
49+
- From the menu bar, select ``Window`` > ``Show View`` > ``Console``.
50+
51+
.. image:: ../../media/CDT_Build_Console.png
52+
:alt: Console View
53+
54+
CDT Global Build Log
55+
--------------------
56+
To enable global build logging:
57+
- Go to ``Preferences`` > ``C/C++`` > ``Build`` > ``Logging``.
58+
59+
Espressif IDF Tools Console
60+
----------------------------
61+
The Espressif IDF Tools Console is part of the Console view and opens during the installation of IDF tools from Eclipse.
62+
63+
If you encounter any issues during installation of IDF tools via ``Espressif`` > ``ESP-IDF Tools Manager`` > ``Install tools``, check the Espressif IDF Tools Console for errors.
64+
65+
If this console is not active, switch to it by clicking on the ``Display Selected Console`` icon in the console view.
66+
67+
.. image:: ../../media/IDF_tools_console.png
68+
:alt: Espressif IDF Tools Console

0 commit comments

Comments
 (0)