feat(docs): add english version

Author: leeebo

docs/doxygen-known-warnings.txt

@@ -1,3 +1,4 @@
 bldc_control.h:line: warning: parameters of member bldc_control_config_t::@49 are not (all) documented
 bldc_control.h:line: warning: parameters of member bldc_control_config_t::@51 are not (all) documented
 sensor_type.h:line: warning: parameters of member sensor_data_t::@53 are not (all) documented
+

docs/en/gettingstarted.rst

@@ -1,188 +1,154 @@
 Get Started
-=================
+==================
 
 :link_to_translation:`zh_CN:[中文]`
 
-This document is intended to help you set up the development environment for ESP-IoT-Solution (Espressif IoT Solution). After that, a simple example will show you how to use ESP-IoT-Solution to set up environment, create a project, build and flash firmware onto an ESP series board, etc.
+This document briefly introduces how to obtain and use components in ESP-IoT-Solution, how to compile and run examples, helping beginners get started quickly.
 
-ESP-IoT-Solution Introduction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ESP-IoT-Solution Version Description
+------------------------------------
 
-ESP-IoT-Solution contains peripheral drivers and code frameworks commonly used in IoT system development, which provide complementary components to ESP-IDF to facilitate simpler development, mainly including the following contents:
+ESP-IoT-Solution has adopted component-based management since ``release/v2.0``, with each component and example independently iterating. Please check the component's ``idf_component.yml`` file for the dependent ESP-IDF version. Release branches only maintain historical major versions, while the master branch continuously integrates new features. It is recommended that new projects obtain required components through the component registry.
 
-- Device drivers such as sensors, screens, audio devices, input devices, actuators, and etc.
-- Code framework and related documents of low power management, security encryption, storage and etc.
-- Entrance guideline for Espressif's open-source solutions from the perspective of practical application.
+Different version descriptions are as follows. For details and component lists, please see `README_CN.md <https://github.com/espressif/esp-iot-solution/blob/master/README_CN.md>`_:
 
-ESP-IoT-Solution Versions
-******************************
+.. list-table:: ESP-IoT-Solution Version Support
+   :header-rows: 1
+   :widths: 20 20 30 20
 
-Specifications of different ESP-IoT-Solution versions are listed in the following table:
+   * - ESP-IoT-Solution
+     - Dependent ESP-IDF
+     - Main Changes
+     - Support Status
+   * - master
+     - >= v5.3
+     - New chip support
+     - New feature development branch
+   * - release/v2.0
+     - <= v5.3, >= v4.4
+     - Component manager support
+     - Historical version maintenance
+   * - release/v1.1
+     - v4.0.1
+     - IDF version update, code migration
+     - Backup, maintenance stopped
+   * - release/v1.0
+     - v3.2.2
+     - Historical version
+     - Backup, maintenance stopped
 
-+--------------------------+-------------------------------+---------------------------------------------------+---------------------------------+
-| ESP-IoT-Solution version | Corresponding ESP-IDF version |                   Main changes                    |             Status              |
-+==========================+===============================+===================================================+=================================+
-| master                   | >=v4.4                        | support component manager and new chips           | New features development branch |
-+--------------------------+-------------------------------+---------------------------------------------------+---------------------------------+
-| release/v1.1             | v4.0.1                        | IDF version updated, deleted codes that have been | Stop maintenance                |
-|                          |                               | moved to other repos                              |                                 |
-+--------------------------+-------------------------------+---------------------------------------------------+---------------------------------+
-| release/v1.0             | v3.2.2                        | Legacy version                                    | Stop maintenance                |
-+--------------------------+-------------------------------+---------------------------------------------------+---------------------------------+
 
-Since the ``master`` branch uses the ``ESP Component Manager`` to manager components, each of them is a separate package, and each package may support a different version of the ESP-IDF, which will be declared in the component's ``idf_component.yml`` file.
+Development Environment Setup
+-----------------------------
 
-ESP-IDF Introduction
-~~~~~~~~~~~~~~~~~~~~~~~
+ESP-IDF is the IoT development framework provided by Espressif for ESP series chips:
 
-ESP-IDF is the IoT development framework for ESP series SoCs provided by Espressif, including:
+- ESP-IDF includes a series of libraries and header files, providing core components required for building software projects based on ESP SoC
+- ESP-IDF also provides the most commonly used tools and functions during development and mass production, such as: build, flash, debug and measurement.
 
-- A series of libraries and header files, providing core components required for building software projects based on ESP SoC;
-- Common tools and functions used during the development and manufacturing processes, e.g., build, flashing, debugging, measurement and etc.
+.. note::
 
-.. Note::
+    Please refer to: `ESP-IDF Programming Guide <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/index.html>`__ to complete the ESP-IDF development environment setup.
 
-    For detailed information, please go to `ESP-IDF Programming Guide <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/index.html>`_.
+Hardware Preparation
+--------------------
 
+You can choose any ESP series development board, or refer to the supported development boards in `esp-bsp <https://github.com/espressif/esp-bsp>`__ for a quick start. For specifications of each series chip, please see `ESP Product Selector <https://products.espressif.com/>`__.
 
-ESP Series SoC Introduction
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+ESP series SoCs support the following features:
 
-You can select any development board from ESP series to get started with ESP-IoT-Solution, or select a supported board from the `Boards Component <./basic/boards.html>`_ directly for a quick start.
+- Wi-Fi (2.4 GHz/5 GHz dual-band)
+- Bluetooth 5.x (BLE/Mesh)
+- High-performance multi-core processor, maximum frequency up to 400 MHz
+- Ultra-low power coprocessor and deep sleep mode
+- Rich peripheral interfaces:
+    - General interfaces: GPIO, UART, I2C, I2S, SPI, SDIO, USB OTG, etc.
+    - Dedicated interfaces: LCD, camera, Ethernet, CAN, Touch, LED PWM, temperature sensor, etc.
+- Large capacity memory:
+    - Internal RAM up to 768 KB
+    - Support for external PSRAM expansion
+    - Support for external Flash storage
+- Enhanced security features:
+    - Hardware encryption engine
+    - Secure boot
+    - Flash encryption
+    - Digital signature
 
-ESP series SoC support the following features:
+ESP series SoCs use advanced process technology, providing industry-leading RF performance, low power consumption characteristics and stable reliability, suitable for IoT, industrial control, smart home, wearable devices and other application scenarios.
 
-- 2.4 GHz Wi-Fi
-- Bluetooth
-- High-performance single core, dual-core processor, capable of running at 240 MHz
-- Ultra-low-power co-processor
-- Various peripherals including GPIO, I2C, I2S, SPI ,UART, SDIO, RMT, LEDC PWM, Ethernet, TWAI®, Touch, USB OTG and etc.
-- Rich memory resources, including up to 520 KB internal RAM and can support external PSRAM
-- Support security functions, e.g., hardware encryption
+.. note::
 
-ESP series of SoC are designed with the 40nm technology, showing the best power and RF performance, versatility and reliability in a wide variety of application and power scenarios.
+   For specific specifications and functions of each series chip, please refer to `ESP Product Selector <https://products.espressif.com/>`__.
 
-.. Note::
 
-    The configuration varies by SoC series, please refer to `ESP Product Selector <http://products.espressif.com:8000/#/product-selector>`_ for details.
+How to Obtain and Use Components
+--------------------------------
 
+It is recommended to obtain ESP-IoT-Solution components through `ESP Component Registry <https://components.espressif.com/>`__.
 
-Setting up Development Environment
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+Taking the button component as an example, the steps to add dependencies are as follows:
 
-1. Get ESP-IDF
-*******************
+1. Execute in the project root directory:
 
-As ESP-IoT-Solution relies on ESP-IDF basic functions and build tools, please set up ESP-IDF development environment first following `ESP-IDF Installation Step by Step <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#get-started-get-prerequisites>`_. Please note that different versions of ESP-IoT-Solution may rely on different ESP-IDF versions, please refer to `ESP-IoT-Solution Versions`_ for specifications.
+    .. code-block:: bash
 
-2. Get ESP-IoT-Solution
-*****************************
+        idf.py add-dependency "espressif/button"
 
-For ``master`` version, please use the following command:
+2. Reference header files in code and call APIs, for example:
 
-.. code:: shell
+    .. code-block:: c
 
-    git clone --recursive https://github.com/espressif/esp-iot-solution
+        #include "iot_button.h"
+        // For specific API usage, please refer to component documentation
 
-For ``release/v1.1`` version, please use the following command:
+For more information on component manager usage, please refer to `ESP Registry Docs <https://docs.espressif.com/projects/idf-component-manager/en/latest/>`__.
 
-.. code:: shell
+How to Use Example Programs
+---------------------------
 
-    git clone -b release/v1.1 --recursive https://github.com/espressif/esp-iot-solution
+ESP-IoT-Solution provides rich example programs to help users get started quickly. Taking the ``button_power_save`` example:
 
-For other versions, please also use this command with ``release/v1.1`` replaced by your target branch name.
+1. Ensure that the ESP-IDF development environment setup has been completed and environment variables have been successfully configured
 
-Use ESP-IoT-Solution Components
-~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
+2. Download the ESP-IoT-Solution code repository:
 
-If you just want to use the components in ESP-IoT-Solution, we recommend you use it from the `ESP Component Registry <https://components.espressif.com/>`_. 
+    .. code-block:: bash
 
-The registered components in ESP-IoT-Solution are listed in :project_file:`README.md` , You can directly add the components from the Component Registry to your project by using the ``idf.py add-dependency`` command under your project's root directory. eg run ``idf.py add-dependency "espressif/usb_stream"`` to add the ``usb_stream``, the component will be downloaded automatically during the ``CMake`` step.
+        git clone https://github.com/espressif/esp-iot-solution.git
 
-Please refer to `IDF Component Manager <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-guides/tools/idf-component-manager.html>`_ for details.
+3. Enter the example directory or copy it to your working directory:
 
-Build and Download
-~~~~~~~~~~~~~~~~~~~~~~
+    .. code-block:: bash
 
-1. Set up the environment variables
-********************************************
+        cd examples/get-started/button_power_save
 
-The tools installed in above steps are not yet added to the PATH environment variables. To make the tools usable from the command line, please follow the following steps to add environment variables:
+    .. note::
 
-* Add ESP-IDF environment variables:
+        If you copy the example to another directory, due to file path changes, please delete all ``override_path`` configurations in ``main/idf_component.yml``.
 
-    For Windows system, please open the Command Prompt and run:
+4. Select target chip (such as ESP32, required when using for the first time or switching chips):
 
-    .. code:: shell
+    .. code-block:: bash
 
-        %userprofile%\esp\esp-idf\export.bat
+        idf.py set-target esp32
 
-    For Linux and macOS, please run:
+5. Configure project (optional):
 
-    .. code:: shell
+    .. code-block:: bash
 
-        . $HOME/esp/esp-idf/export.sh
-    
-    Please remember to replace the paths in above commands as your actual paths.
+        idf.py menuconfig
 
-* Add IOT_SOLUTION_PATH environment variables:
+6. Compile and flash to development board:
 
-    For Windows system, please open the Command Prompt and run:
+    .. code-block:: bash
 
-    .. code:: shell
+        idf.py build
+        idf.py -p <PORT> flash
 
-        set IOT_SOLUTION_PATH=C:\esp\esp-iot-solution
+7. Monitor output through serial port:
 
-    For Linux and macOS, please run:
+    .. code-block:: bash
 
-    .. code:: shell
+        idf.py -p <PORT> monitor
 
-        export IOT_SOLUTION_PATH=~/esp/esp-iot-solution
-
-.. Note::
-
-    The environment variables set by the above method are only valid in the current terminal. Please repeat above steps if you open a new terminal.
-
-2. Set build target
-***********************
-
-ESP-IDF supports multiple chips as ``esp32``, ``esp32s2`` and others, please set your target chip before building (the default target is ``esp32``). For example, you can set the build target as ``esp32s2``.
-
-.. code:: shell
-
-    idf.py set-target esp32s2
-
-For examples in ESP-IoT-Solution developed based on `Boards Component <./basic/boards.html>`_, you can go to ``Board Options -> Choose Target Board`` in ``menuconfig`` to choose a target board: 
-
-.. code:: shell
-
-    idf.py menuconfig
-
-3. Build and download the program
-***************************************
-
-Use the ``idf.py`` tool to build and download the program with:
-
-.. code:: shell
-
-    idf.py -p PORT build flash
-
-Please replace PORT with your board's port name. Serial ports have the following patterns in their names: Windows is like ``COMx``; Linux starting with ``/dev/ttyUSBx``; macOS usually is ``/dev/cu.``.
-
-4. Serial print log
-***********************
-
-Use the ``idf.py`` tool to see logs:
-
-.. code:: shell
-
-    idf.py -p PORT monitor
-
-Do not forget to replace PORT with your serial port name (``COMx`` for Windows; ``/dev/ttyUSBx`` for Linux; ``/dev/cu.`` for macOS).
-
-Related Documents
-~~~~~~~~~~~~~~~~~~~~~~~~~
-
-- `ESP-IDF Installation Step by Step <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html#get-started-get-prerequisites>`_
-- `ESP-IDF Get Started <https://docs.espressif.com/projects/esp-idf/en/latest/esp32/get-started/index.html>`_
-- `ESP Product Selector <http://products.espressif.com:8000/#/product-selector>`_
+For more examples, please see the ``examples/`` directory. For specific usage methods, please refer to the README files under each example.