Skip to content

Commit

Permalink
Merge branch 'docs-bss-in-psram' into 'main'
Browse files Browse the repository at this point in the history 
docs: FAQ for moving BSS segments to PSRAM for reduced internal memory usage

See merge request app-frameworks/esp-matter!1026
  • Loading branch information
@chshu
chshu committed Feb 18, 2025
2 parents 5477dd4 + c376474 commit 2a7a61a
Showing 1 changed file with 83 additions and 99 deletions.
182 changes: 83 additions & 99 deletions docs/en/faq.rst
View file
Original file line number Diff line number Diff line change
Expand Up @@ -6,18 +6,14 @@ A1.1 Compilation errors

I cannot build the application:

- Make sure you are on the correct esp-idf branch/release. Run ``git submodule
update —init —recursive`` to make sure the submodules are at the
correct heads
- Make sure you have the correct ESP_MATTER_PATH (and any other required paths).
- Delete the build/ directory and also sdkconfig and sdkconfig.old and
- Make sure you are on the correct esp-idf branch/release.
- Run ``git submodule update —init —recursive`` to make sure the submodules are at the
correct heads.
- Make sure you have the correct ``ESP_MATTER_PATH`` (and any other required paths).
- Delete the ``build/`` directory and also ``sdkconfig`` and ``sdkconfig.old`` and
then build again.
- If you are still facing issues, reproduce it on the default
example and then raise it `here <https://github.com/espressif/esp-matter/issues>`__. Please make sure to
share these:

- The complete device logs taken over UART.
- The esp-matter and esp-idf branch you are using.
example and then raise a `Github issue`_.

A1.2 Device commissioning using chip-tool
-----------------------------------------
Expand All @@ -26,18 +22,12 @@ I cannot commission a new device through the chip-tool:

- If the ``chip-tool pairing ble-wifi`` command is failing,
make sure the arguments are correct.
- Please check ``chip-tool pairing ble-wifi --help`` for argument help.
- Make sure Bluetooth is turned on, on your client (host).
- If you are still facing issues, reproduce it on the default
example for the device and then raise it `here <https://github.com/espressif/esp-matter/issues>`__. Make sure
to share these:

- The complete device logs.
- The complete chip-tool logs.
- The esp-matter and esp-idf branch you are using.

Bluetooth/BLE does not work on by device:

- There are some `known issues <https://github.com/project-chip/connectedhomeip/issues/13303>`__ where BLE does not work on MacOS.
- There is a known issues `#13303`_ where BLE does not work on MacOS.
- In this case, the following can be done:

- Run the device console command:
Expand All @@ -46,12 +36,7 @@ Bluetooth/BLE does not work on by device:
``chip-tool pairing onnetwork 0x7283 20202021``.

- If you are still facing issues, reproduce it on the default
example for the device and then raise it `here <https://github.com/espressif/esp-matter/issues>`__. Make sure
to share these:

- The complete device logs taken over UART.
- The complete chip-tool logs.
- The esp-matter and esp-idf branch you are using.
example for the device and then raise a `Github issue`_.

A1.3 Device crashing
--------------------
Expand All @@ -66,31 +51,20 @@ My device is crashing:
- Make sure you are on the correct esp-idf branch. Run ``git submodule
update —init —recursive`` to make sure the submodules are at the
correct heads.
- Make sure you have the correct ESP_MATTER_PATH (and any other paths)
- Make sure you have the correct ``ESP_MATTER_PATH`` (and any other paths)
is (are) exported.
- Delete the build/ directory and also sdkconfig and sdkconfig.old and
- Delete the ``build/`` directory and also ``sdkconfig`` and ``sdkconfig.old`` and
then build and flash again.
- If you are still facing issues, reproduce it on the default
example for the device and then raise it `here <https://github.com/espressif/esp-matter/issues>`__. Make sure
to share these:
example for the device and then raise a `Github issue`_. Along with the
details mentioned in the issue template, please share the following details:

- The steps you followed to reproduce the issue.

- The complete device logs taken over UART.

-

.. raw:: html

<example>

.elf file from the build/ directory.

- The .elf file from the build/ directory.
- If you have gdb enabled, run the command ``backtrace`` and share the
output of gdb too.

- The esp-matter and esp-idf branch you are using.

A1.4 Device not crashed but not responding
------------------------------------------

Expand All @@ -101,27 +75,14 @@ My device is not responding to commands:
- Make sure the node_id and the endpoint_id are correct in the command
from chip-tool.
- If you are still facing issues, reproduce it on the default
example for the device and then raise it `here <https://github.com/espressif/esp-matter/issues>`__. Make sure
to share these:
example for the device and then raise a `Github issue`_. Along with the
details mentioned in the issue template, please share the following details:

- The steps you followed to reproduce the issue.
- The complete device logs taken over UART.
- The esp-matter and esp-idf branch you are using.

A1.5 QR code not rendering
--------------------------

The QR code on my device console is not rendering properly:

- Check the below lines on your terminal and copy paste the given URL
in a browser:

::

If QR code is not visible, copy paste the URL in a browser:
https://project-chip.github.io/connectedhomeip/qrcode.html?data=....

A1.6 Onboard LED not working
A1.5 Onboard LED not working
----------------------------

The LED on my devkit is not working:
Expand All @@ -131,16 +92,12 @@ The LED on my devkit is not working:
path.
- Check the version of your board, and if it has the LED connected to a
different pin. If it is different, you can change the
led_driver_config_t accordingly in the device.c file.
``led_driver_config_t`` accordingly in the ``device.c`` file.
- If you are still facing issues, reproduce it on the default
example for the device and then raise it `here <https://github.com/espressif/esp-matter/issues>`__. Make sure
to share these:
example for the device and then raise a `Github issue`_.

- The complete device logs taken over UART.
- The esp-matter and esp-idf branch you are using.
- The devkit and its version that you are using.

A1.7 Using Rotating Device Identifier
A1.6 Using Rotating Device Identifier
-------------------------------------

What is Rotating Device Identifier:
Expand Down Expand Up @@ -179,25 +136,15 @@ Difference between Rotating ID Unique ID and Unique ID
- it SHALL not be identical to the SerialNumber attribute
- it SHALL not be printed on the product or delivered with the product

The value does not need to be human readable.

**Also check the "Appendix FAQs" sections of the respective examples.**

- :project_file:`Light <examples/light/README.md>`
- :project_file:`Light Switch <examples/light_switch/README.md>`
- :project_file:`Zap Light <examples/zap_light/README.md>`
- :project_file:`Zigbee Bridge <examples/bridge_apps/zigbee_bridge/README.md>`
- :project_file:`BLE Mesh Bridge <examples/bridge_apps/blemesh_bridge/README.md>`

A1.8 ModuleNotFoundError: No module named 'lark'
A1.7 ModuleNotFoundError: No module named 'lark'
------------------------------------------------

Encountering the above error while building the esp-matter example could indicate that the steps outlined in the
`getting the repository <https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html#getting-the-repositories>`__
section of the documentation were not properly followed.
`getting the repository`_ section of the documentation were not properly followed.

The esp-matter example relies on several python dependencies that can be found in the
`requirements.txt <https://github.com/espressif/esp-matter/blob/main/requirements.txt>`__.
:project_file:`requirements.txt <requirements.txt>`.
These dependencies must be installed into the python environment of the esp-idf to ensure that the example builds successfully.

One recommended approach to installing these requirements is by running the command
Expand All @@ -217,26 +164,26 @@ However, if the error persists, you can try the following steps to resolve it:
idf.py build


A1.9 Why does free RAM increase after first commissioning
A1.8 Why does free RAM increase after first commissioning
---------------------------------------------------------

After the first commissioning, you may notice that the free RAM increases. This is because, by default,
BLE is only used for the commissioning process. Once the commissioning is complete, BLE is deinitialized,
and all the memory allocated to it is recovered. Here's the link to the
`implementation <https://github.com/espressif/esp-matter/blob/c52fa686d1a3be275b0a5c872ee5f1a3c8f2420d/components/esp_matter/esp_matter_core.cpp#L859-L891>`__ which frees the BLE memory.
:project_file:`implementation which frees the BLE memory <components/esp_matter/esp_matter_core.cpp#L859-L891>`.

However, if you want to continue using the BLE even after the commissioning process, you can disable the
``CONFIG_USE_BLE_ONLY_FOR_COMMISSIONING``. This will ensure that the memory allocated to the BLE functionality
is not released after the commissioning process, and the free RAM won't go up.

A1.10 How to generate Matter Onboarding Codes (QR Code and Manual Pairing Code)
-------------------------------------------------------------------------------
A1.9 How to generate Matter Onboarding Codes (QR Code and Manual Pairing Code)
------------------------------------------------------------------------------

When creating a factory partition using ``esp-matter-mfg-tool``, both the QR code and manual pairing codes are generated.

Along with that, there are two more methods for generating Matter onboarding codes:

- Python script: `generate_setup_payload.py <https://github.com/project-chip/connectedhomeip/tree/master/src/setup_payload/python>`__.
- Python script: `generate_setup_payload.py`_

::

Expand All @@ -263,10 +210,10 @@ Along with that, there are two more methods for generating Matter onboarding cod
--vendor-id 0xFFF1 --product-id 0x8004 \
--version 0 --commissioning-mode 1

To create a QR code image, copy the QR code text and paste it into
`CHIP: QR Code <https://project-chip.github.io/connectedhomeip/qrcode.html>`__.
To create a QR code image, copy the QR code text and paste it into `CHIP QR Code`_.


A1.11 Chip stack locking error ... Code is unsafe/racy
A1.10 Chip stack locking error ... Code is unsafe/racy
------------------------------------------------------

::
Expand Down Expand Up @@ -304,12 +251,11 @@ To address this, there are two possible approaches:
chip::DeviceLayer::PlatformMgr().ScheduleWork(WorkHandler, <intptr_t>(nullptr));


A1.12 Firmware Version Number
A1.11 Firmware Version Number
-----------------------------

Similar to the ESP-IDF's application versioning scheme, the ESP-Matter SDK provides two options for setting the firmware
version. It depends on `CONFIG_APP_PROJECT_VER_FROM_CONFIG <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html#config-app-project-ver-from-config>`__
option and by default option is disabled.
version. It depends on `CONFIG_APP_PROJECT_VER_FROM_CONFIG`_ option and by default option is disabled.

If the ``CONFIG_APP_PROJECT_VER_FROM_CONFIG`` option is disabled, you need to set the version and version string by
defining the CMake variables in the project's ``CMakeLists.txt`` file. All the examples use this scheme and have these
Expand Down Expand Up @@ -339,7 +285,7 @@ the following configuration options:
version, even though the binary content may match the previous OTA image.


A1.13 Stuck at "Solving dependencies requirements ....."
A1.12 Stuck at "Solving dependencies requirements ....."
--------------------------------------------------------

When building an example, if it is stuck at "Solving dependencies requirements..."
Expand All @@ -354,12 +300,12 @@ you can resolve this issue by clearing the component manager cache.
rm -rf ~/Library/Caches/Espressif/ComponentManager


A1.14 ESP32-C2 log garbled, unable to perform Matter commissioning and other abnormal issues
A1.13 ESP32-C2 log garbled, unable to perform Matter commissioning and other abnormal issues
--------------------------------------------------------------------------------------------

When encountering the above issues, the following possible causes may exist:
1. Incorrect baud rate settings. See `UART console baud rate <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig.html#config-esp-console-uart-baudrate>`__.
2. Incorrect XTAL crystal frequency settings. The default XTAL crystal frequency in the SDK examples is 26 Mhz, if the ESP32-C2 board used for testing is 40 MHz, please change the configuration as `CONFIG_XTAL_FREQ_40=y`. See `Main XTAL frequency <https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig.html#main-xtal-config>`__. You can check the XTAL frequency with this command.
1. Incorrect baud rate settings. See `UART console baud rate`_
2. Incorrect XTAL crystal frequency settings. The default XTAL crystal frequency in the SDK examples is 26 Mhz, if the ESP32-C2 board used for testing is 40 MHz, please change the configuration as `CONFIG_XTAL_FREQ_40=y`. See `Main XTAL frequency`_ You can check the XTAL frequency with this command.

::

Expand All @@ -373,7 +319,7 @@ When encountering the above issues, the following possible causes may exist:
Crystal is 26MHz
MAC: 08:3a:8d:49:b3:90

A1.15 Generating Matter Onboarding Codes on the device itself
A1.14 Generating Matter Onboarding Codes on the device itself
-------------------------------------------------------------

The Passcode serves as both proof of possession for the device and the shared secret needed to establish
Expand All @@ -383,7 +329,7 @@ For best practices in Passcode generation and storage on the device, refer to
**Section 5.1.7: Generation of the Passcode** in the Core Matter Specification.

Ideally, devices should only store the Spake2p verifier, not the Passcode itself.
If the Passcode is stored on the device, it must be physically separated from the Spake2p verifier’s location
If the Passcode is stored on the device, it must be physically separated from the Spake2p verifier's location
and must be accessible only through local interface and must not be accessible to the unit handling the
Spake2p verifier.

Expand All @@ -396,15 +342,11 @@ along with the corresponding Spake2p verifier and onboarding payload, directly o

Please check `#1128`_ and `#1126`_ for relevant discussion on Github issue

.. _`#1126`: https://github.com/espressif/esp-matter/issues/1126
.. _`#1128`: https://github.com/espressif/esp-matter/issues/1128


A1.16 Using BLE after Matter commissioning
A1.15 Using BLE after Matter commissioning
------------------------------------------

Most Matter applications do not require BLE after commissioning. By default, BLE is deinitialized after commissioning
to reclaim RAM and increase the available free heap. Refer to `A1.9 Why does free RAM increase after first commissioning`_
to reclaim RAM and increase the available free heap. Refer to `A1.8 Why does free RAM increase after first commissioning`_
for more details.

However, if BLE functionality is needed even after commissioning, you can disable the ``CONFIG_USE_BLE_ONLY_FOR_COMMISSIONING``
Expand Down Expand Up @@ -435,10 +377,52 @@ Please refer to the `advance setup`_ section in the programming guide.
This has been demonstrated in the `blemesh_bridge`_ and `light_wifi_prov`_ examples.


A1.16 Moving BSS Segments to PSRAM to Reduce Memory Usage
---------------------------------------------------------

The BSS section of libesp_matter.a and libCHIP.a can consume significant internal memory.
For devices with PSRAM, you can move the BSS segments to external memory to significantly
reduce the internal memory footprint.

To move the BSS segments of libCHIP.a and libesp_matter.a into external RAM:

1. Enable the ``CONFIG_ESP_ALLOW_BSS_SEG_EXTERNAL_MEMORY`` option in menuconfig.

2. Create a ``linker.lf`` file in your project's main component, you can check the the example
:project_file:`linker.lf <examples/all_device_types_app/main/linker.lf>` file.

3. Modify your main component's ``CMakeLists.txt`` to include:

::

set(ldfragments linker.lf)
idf_component_register(
...
LDFRAGMENTS "${ldfragments}")

This configuration will move the BSS segments to PSRAM when ``CONFIG_ESP_ALLOW_BSS_SEG_EXTERNAL_MEMORY`` is enabled,
significantly reducing the internal memory usage of your application.

Please check `#1123`_ for relevant discussion on Github issue.

.. _bleprph: https://github.com/espressif/esp-idf/tree/b5ac4fbdf9e9fb320bb0a98ee4fbaa18f8566f37/examples/bluetooth/nimble/bleprph
.. _blecent: https://github.com/espressif/esp-idf/tree/b5ac4fbdf9e9fb320bb0a98ee4fbaa18f8566f37/examples/bluetooth/nimble/blecent
.. _bleprph_advertise(): https://github.com/espressif/esp-idf/blob/b5ac4fbdf9e9fb320bb0a98ee4fbaa18f8566f37/examples/bluetooth/nimble/bleprph/main/main.c#L146
.. _blecent_scan(): https://github.com/espressif/esp-idf/blob/b5ac4fbdf9e9fb320bb0a98ee4fbaa18f8566f37/examples/bluetooth/nimble/blecent/main/main.c#L435
.. _advance setup: https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html#advanced-setup
.. _blemesh_bridge: https://github.com/espressif/esp-matter/tree/main/examples/bridge_apps/blemesh_bridge
.. _light_wifi_prov: https://github.com/espressif/esp-matter/tree/main/examples/light_wifi_prov#4-external-platform
.. _getting the repository: https://docs.espressif.com/projects/esp-matter/en/latest/esp32/developing.html#getting-the-repository
.. _requirements.txt: https://github.com/espressif/esp-matter/blob/main/requirements.txt
.. _implementation which frees the BLE memory: https://github.com/espressif/esp-matter/blob/c52fa686d1a3be275b0a5c872ee5f1a3c8f2420d/components/esp_matter/esp_matter_core.cpp#L859-L891
.. _generate_setup_payload.py: https://github.com/project-chip/connectedhomeip/tree/master/src/setup_payload/python
.. _CHIP QR Code: https://project-chip.github.io/connectedhomeip/qrcode.html
.. _CONFIG_APP_PROJECT_VER_FROM_CONFIG: https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/kconfig.html#config-app-project-ver-from-config
.. _UART console baud rate: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig.html#config-esp-console-uart-baudrate
.. _Main XTAL frequency: https://docs.espressif.com/projects/esp-idf/en/latest/esp32c2/api-reference/kconfig.html#main-xtal-config

.. _Github issue: https://github.com/espressif/esp-matter/issues/new?template=issue-template.md
.. _`#1123`: https://github.com/espressif/esp-matter/issues/1123
.. _`#1126`: https://github.com/espressif/esp-matter/issues/1126
.. _`#1128`: https://github.com/espressif/esp-matter/issues/1128
.. _`#13303`: https://github.com/project-chip/connectedhomeip/issues/13303

0 comments on commit 2a7a61a

Please sign in to comment.