From 7df1cad1d63e2b004dfc9bb838aea2b4d14298b0 Mon Sep 17 00:00:00 2001 From: Wang Fang Date: Fri, 22 Jan 2021 20:06:05 +0800 Subject: [PATCH] docs: This MR does the following updates: 1. Provided more information regarding I2S_COMM_FORMAT_STAND_PCM_SHORT and I2S_COMM_FORMAT_STAND_PCM_LONG 2. Added --output flag for partition table read instructions 3. Reordered the header files for esp-ble-mesh 4. Reordered the setup instructions for Ubuntu and CentOS --- components/hal/include/hal/i2s_types.h | 4 ++-- docs/en/api-guides/partition-tables.rst | 2 +- .../api-reference/bluetooth/esp-ble-mesh.rst | 10 +++++----- docs/en/conf.py | 4 ++-- docs/en/get-started/linux-setup.rst | 17 +++++++++-------- docs/zh_CN/api-guides/partition-tables.rst | 2 +- docs/zh_CN/conf.py | 4 ++-- docs/zh_CN/get-started/linux-setup.rst | 19 ++++++++++--------- 8 files changed, 32 insertions(+), 30 deletions(-) diff --git a/components/hal/include/hal/i2s_types.h b/components/hal/include/hal/i2s_types.h index 30d8c3de03..2b41b1b491 100644 --- a/components/hal/include/hal/i2s_types.h +++ b/components/hal/include/hal/i2s_types.h @@ -62,8 +62,8 @@ typedef enum { // In order to keep compatibility, remain the old definitions and introduce new definitions, I2S_COMM_FORMAT_STAND_I2S = 0X01, /*!< I2S communication I2S Philips standard, data launch at second BCK*/ I2S_COMM_FORMAT_STAND_MSB = 0X03, /*!< I2S communication MSB alignment standard, data launch at first BCK*/ - I2S_COMM_FORMAT_STAND_PCM_SHORT = 0x04, /*!< PCM Short standard*/ - I2S_COMM_FORMAT_STAND_PCM_LONG = 0x0C, /*!< PCM Long standard*/ + I2S_COMM_FORMAT_STAND_PCM_SHORT = 0x04, /*!< PCM Short standard, also known as DSP mode. The period of synchronization signal (WS) is 1 bck cycle.*/ + I2S_COMM_FORMAT_STAND_PCM_LONG = 0x0C, /*!< PCM Long standard. The period of synchronization signal (WS) is channel_bit*bck cycles.*/ I2S_COMM_FORMAT_STAND_MAX, /*!< standard max*/ //old definition will be removed in the future. diff --git a/docs/en/api-guides/partition-tables.rst b/docs/en/api-guides/partition-tables.rst index 53a6f71ccf..e3027038f5 100644 --- a/docs/en/api-guides/partition-tables.rst +++ b/docs/en/api-guides/partition-tables.rst @@ -260,7 +260,7 @@ The command-line interface of `parttool.py` has the following structure: parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage # Read partition with type 'data' and subtype 'spiffs' and save to file 'spiffs.bin' - parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs "spiffs.bin" + parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin" # Write to partition 'factory' the contents of a file named 'factory.bin' parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory "factory.bin" diff --git a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst b/docs/en/api-reference/bluetooth/esp-ble-mesh.rst index 62b5703b30..cbdce68731 100644 --- a/docs/en/api-reference/bluetooth/esp-ble-mesh.rst +++ b/docs/en/api-reference/bluetooth/esp-ble-mesh.rst @@ -126,29 +126,29 @@ Configuration Client/Server Models Health Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc Generic Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include-build-file:: inc/esp_ble_mesh_health_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_generic_model_api.inc Sensor Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc Time and Scenes Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include-build-file:: inc/esp_ble_mesh_sensor_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc Lighting Client/Server Models ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ -.. include-build-file:: inc/esp_ble_mesh_time_scene_model_api.inc +.. include-build-file:: inc/esp_ble_mesh_lighting_model_api.inc diff --git a/docs/en/conf.py b/docs/en/conf.py index cb77736dd3..eb43458dda 100644 --- a/docs/en/conf.py +++ b/docs/en/conf.py @@ -9,14 +9,14 @@ try: from conf_common import * # noqa: F403,F401 except ImportError: - import sys import os + import sys sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F403,F401 # General information about the project. project = u'ESP-IDF Programming Guide' -copyright = u'2016 - 2020, Espressif Systems (Shanghai) CO., LTD' +copyright = u'2016 - 2021, Espressif Systems (Shanghai) Co., Ltd' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/en/get-started/linux-setup.rst b/docs/en/get-started/linux-setup.rst index 1213b59b24..caa55964bf 100644 --- a/docs/en/get-started/linux-setup.rst +++ b/docs/en/get-started/linux-setup.rst @@ -7,24 +7,25 @@ Standard Setup of Toolchain for Linux Install Prerequisites ===================== -To compile with ESP-IDF you need to get the following packages: - -- CentOS 7:: - - sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx - -CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience. +To compile with ESP-IDF you need to get the following packages. The command to run depends on which distribution of Linux you are using: - Ubuntu and Debian:: sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 +- CentOS 7 & 8:: + + sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx + +CentOS 7 is still supported but CentOS version 8 is recommended for a better user experience. + - Arch:: sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja ccache dfu-util libusb .. note:: - CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake". + - CMake version 3.5 or newer is required for use with ESP-IDF. Older Linux distributions may require updating, enabling of a "backports" repository, or installing of a "cmake3" package rather than "cmake". + - If you do not see your Linux distribution in the above list then please check its documentation to find out which command to use for package installation. Additional Tips =============== diff --git a/docs/zh_CN/api-guides/partition-tables.rst b/docs/zh_CN/api-guides/partition-tables.rst index e6c49f9591..167dd14415 100644 --- a/docs/zh_CN/api-guides/partition-tables.rst +++ b/docs/zh_CN/api-guides/partition-tables.rst @@ -253,7 +253,7 @@ Python API parttool.py --port "/dev/ttyUSB1" erase_partition --partition-name=storage # 读取类型为 'data'、子类型为 'spiffs' 的分区，保存到 'spiffs.bin' 文件 - parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs "spiffs.bin" + parttool.py --port "/dev/ttyUSB1" read_partition --partition-type=data --partition-subtype=spiffs --output "spiffs.bin" # 将 'factory.bin' 文件中的内容写入到 'factory' 分区 parttool.py --port "/dev/ttyUSB1" write_partition --partition-name=factory "factory.bin" diff --git a/docs/zh_CN/conf.py b/docs/zh_CN/conf.py index 567585ffbd..a13d6d79f9 100644 --- a/docs/zh_CN/conf.py +++ b/docs/zh_CN/conf.py @@ -9,14 +9,14 @@ try: from conf_common import * # noqa: F403,F401 except ImportError: - import sys import os + import sys sys.path.insert(0, os.path.abspath('..')) from conf_common import * # noqa: F403,F401 # General information about the project. project = u'ESP-IDF 编程指南' -copyright = u'2016 - 2020 乐鑫信息科技（上海）股份有限公司' +copyright = u'2016 - 2021 乐鑫信息科技（上海）股份有限公司' # The language for content autogenerated by Sphinx. Refer to documentation # for a list of supported languages. diff --git a/docs/zh_CN/get-started/linux-setup.rst b/docs/zh_CN/get-started/linux-setup.rst index bcd9bc887a..8c5aed0342 100644 --- a/docs/zh_CN/get-started/linux-setup.rst +++ b/docs/zh_CN/get-started/linux-setup.rst @@ -7,24 +7,25 @@ Linux 平台工具链的标准设置 安装准备 ===================== -编译 ESP-IDF 需要以下软件包： - -- CentOS 7:: - - sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx - -目前仍然支持 CentOS 7，但为了更好的用户体验，建议使用 CentOS 8。 +编译 ESP-IDF 需要以下软件包。请根据使用的系统，选择合适的安装命令，如下所示： - Ubuntu 和 Debian:: sudo apt-get install git wget flex bison gperf python3 python3-pip python3-setuptools cmake ninja-build ccache libffi-dev libssl-dev dfu-util libusb-1.0-0 +- CentOS 7 & 8:: + + sudo yum -y update && sudo yum install git wget flex bison gperf python3 cmake ninja-build ccache dfu-util libusbx + +目前仍然支持 CentOS 7，但为了更好的用户体验，建议使用 CentOS 8。 + - Arch:: sudo pacman -S --needed gcc git make flex bison gperf python-pip cmake ninja ccache dfu-util libusb -.. 注解:: - 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早的 Linux 发行版可能需要升级自身的软件源仓库，或开启 backports 套件库，或安装 "cmake3" 软件包（不是安装 "cmake"）。 +.. note:: + - 使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早的 Linux 发行版可能需要升级自身的软件源仓库，或开启 backports 套件库，或安装 "cmake3" 软件包（不是安装 "cmake"）。 + - 如果上述列表中，并没有您使用的系统，请参考您所用系统的相关文档，查看安装软件包所用的命令。 其他提示 ===============