Included zh_CN version of Eclipse setup and PICO-KIT get started guides

This commit is contained in:
krzychb 2018-02-07 23:17:04 +01:00
parent c63d7a4b5e
commit 6a1b2c6ad0
3 changed files with 407 additions and 3 deletions

View file

@ -1 +1,80 @@
.. include:: ../../en/get-started/eclipse-setup-windows.rst
*****************************************************
Eclipse IDE 的创建和烧录指南Windows 平台)
*****************************************************
Windows 平台上的 Eclipse 配置略有不同,具体步骤请见下文。
*注意OS X 和 Linux 平台上的 Eclipse IDE 配置,请见 :doc:`Eclipse IDE page <eclipse-setup>`。*
安装 Eclipse IDE
==================
Windows 平台的 Eclipse 安装步骤与其他平台相同,请见 :ref:`Installing Eclipse IDE <eclipse-install-steps>`
.. _eclipse-windows-setup:
Windows 平台上的 Eclipse 配置
================================
点击安装 Eclipse IDE并按照下列步骤操作
导入新项目
-------------
* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此在使用 Eclipse 前,您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时,您可以使用 GitHub 中的 idf-template 项目模版,或从 esp-idf 子目录中选择一个 example。
* 运行 Eclipse选择 “File” -> “Import...”。
* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”然后点击 “Next”。
* 跳转至下个界面 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意,这里应填入 ESP-IDF 项目的路径,而非 ESP-IDF 的路径(稍后再填写)。此外,您指定的目标路径中应包含名为 “Makefile”项目 Makefile的文件。
* 在同一页面上,在 “Toolchain for Indexer Settings” 下取消选中 “Show only available toolchains that support this platform”。
* 在出现的扩展列表中,选择 “Cygwin GCC”。然后点击 “Finish”。
*注意:您可能看到有关“无法找到 Cygwin GCC 工具链”的警告。这种情况并不影响安装,我们只需重新配置 Eclipse并找到我们的工具链即可。*
项目属性
----------
* 新项目将出现在 “Project Explorer” 下。请右键选择该项目并在菜单中选择 “Properties”。
* 点击 “C/C++ Build” 属性页。
* 取消选中 “Use default build command”然后输入命令``python${IDF_PATH}/tools/windows/eclipse_make.py``,开始自定义新建。
* 点击 “C/C++ Build” 下的 “Environment” 属性页面。
* 选择 “Add...”,并在对应位置输入 ``BATCH_BUILD`` 和 ``1``
* 再次点击 “Add...”,输入名称 ``IDF_PATH``,并填写 ESP-IDF 的完整安装路径。``IDF_PATH`` 目录路径应使用正斜杠,而非反斜线,即 ``C:/Users/MyUser/Development/esp-idf``
* 选择 ``PATH`` 环境变量,删除默认值,并将其替换为 ``C:\msys32\usr\bin;C:\msys32\mingw32\bin;C:\msys32\opt\xtensa-esp32-elf\bin`` (如果您已经将 msys32 安装到其他目​​录,这里请自行调整)。
* 点击 “C/C++ General” -> “Preprocessor Include Paths, Macros, etc.” 属性页。
* 点击 “Providers” 选项卡。
* 从 “Providers” 列表中选择 “CDT GCC Built-in Compiler Settings Cygwin”。进入 “Command to get compiler specs” 目录下,用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``text${COMMAND}``,最终完整的 ``Command to get compiler specs`` 应为 ``xtensa-esp32-elf-gcc${FLAGS}-E-P-v-dD"${INPUTS}``
* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”然后在 Compiler 命令模式的起始位置输入 ``xtensa-esp32-elf-``,并用括号把剩余部分扩起来。最终的完整 Compiler 命令模式应为 ``xtensa-esp32-elf-((g?cc)|([gc]\+\+)|(clang))``
在 Eclipse IDE 中创建项目
---------------------------
Windows 平台的 Eclipse 项目创建步骤与其他平台相同,请见 :ref:`Building in Eclipse <eclipse-build-project>`
技术细节
=========
**以下内容仅供 Windows 平台专家或非常感兴趣的开发者阅读。**
Windows 平台的 Eclipse 介绍到此结束,下方将主要将介绍一些关键操作的原理,助您了解更多 Eclipse 的背景信息。
* 首先xtensa-esp32-elf-gcc 交叉编译器 *并非* Cygwin 工具链,但我们会在 Eclipse 中指定其为 Cygwin 工具链。主要原因在于msys2 需要使用 Cygwin并支持 Unix 风格的路径,即 ``type/c/blah``,而非 ``c:/blah`` 或 ``c:\\blah``。特别需要说明的是,``xtensa-esp32-elf-gcc`` 会“告知” Eclipse 的 ``built-in compiler settings`` 功能,其内置 “include” 目录全部位于 ``/usr/`` 路径下,这也是 Eclipse 唯一可以解析的 ``Unix/Cygwin`` 样式路径。通过在 Eclipse 中指定 ``xtensa-esp32-elf-gcc`` 交叉编译器为 Cygwin 编译器,可以让 Eclipse 使用 cygpath 实用程序直接内部解析路径。
* 在解析 ESP-IDF 的 make 结果时也经常会出现同样的问题。Eclipse 可以解析 make 的结果,查找头文件目录,但是无法脱离 cygpath直接解析包含 ``/c/blah`` 格式的目录。``Eclipse Build Output Parser`` 将利用该机制确认是否调用 cygpath但由于未知原因目前 ESP-IDF 配置并不会触发该功能。出于这个原因,我们会使用 ``eclipse_make.py`` 包装脚本调用 make然后使用 cygpath 处理 Eclipse 的结果。

View file

@ -1 +1,108 @@
.. include:: ../../en/get-started/eclipse-setup.rst
****************************
Eclipse IDE 的创建和烧录指南
****************************
.. _eclipse-install-steps:
安装 Eclipse IDE
================
Eclipse IDE 是一个可视化的集成开发环境,可用于编写、编译和调试 ESP-IDF 项目。
* 首先,请在您的平台上安装相应的 ESP-IDF具体步骤请参考适用于 Windows、OS X 和 Linux 的相应安装步骤。
* 我们建议,您应首先使用命令行创建一个项目,大致熟悉项目的创建流程。此外,您还需要使用命令行 (``make menuconfig``) 对您的 ESP-IDF 项目进行配置。目前Eclipse 尚不支持对 ESP-IDF 项目进行配置。
* 下载相应版本的 Eclipse Installer 至您的平台,点击 eclipse.org_。
* 运行 Eclipse Installer选择 “Eclipse for C/C++ Development”有的版本也可能显示为 CDT
Windows 用户
============
Eclipse IDE 的 Windows 用户,请参考 :ref: `Windows 用户的 Eclipse IDE 使用指南 <eclipse-windows-setup>`
配置 Eclipse IDE
=================
请打开安装好的 Eclipse IDE并按照以下步骤进行操作
导入新项目
----------
* Eclipse IDE 需使用 ESP-IDF 的 Makefile 功能。因此,在使用 Eclipse 前,您需要先创建一个 ESP-IDF 项目。在创建 ESP-IDF 项目时,您可以使用 GitHub 中的 idf-template 项目模版,或从 esp-idf 子目录中选择一个 example。
* 运行 Eclipse选择 “File” -> “Import...”。
* 在弹出的对话框中选择 “C/C++” -> “Existing Code as Makefile Project”然后点击 “Next”。
* 跳转至下个界面,在 “Existing Code Location” 位置输入您的 IDF 项目的路径。注意,这里应输入 ESP-IDF 项目的路径,而非 ESP-IDF 本身的路径(这个稍后再填)。此外,您指定的目标路径中应包含名为 ``Makefile`` (项目 Makefile的文件。
* 在本界面,找到 “Toolchain for Indexer Settings”选择 “Cross GCC”最后点击 “Finish”。
项目属性
--------
* 新项目将出现在 “Project Explorer” 下。请右键选择该项目,并在菜单中选择 “Properties”。
* 点击 “C/C++ Build” 下的 “Environment” 属性页,选择 “Add...”,并在对应位置输入 “BATCH_BUILD” 和 “1”。
* 再次点击 “Add...”,并在 “IDF_PATH” 中输入 ESP-IDF 所在的完整安装路径。
* 选择 “PATH” 环境变量,不要改变默认值。如果 IDF 设置中的 Xtensa 工具链尚不在 “PATH” 列表中,则应将该路径增加至列表 (``something/xtensa-esp32-elf/bin``)。
* 在 macOS 平台上,增加一个 “PYTHONPATH” 环境变量,并将其设置为 ``/Library/Frameworks/Python.framework/Versions/2.7/lib/python2.7/site-packages`` 保证预先安装的系统 Python 可以覆盖 Eclipse 内置的任何 Python。
* 前往 “C/C++ General” -> “Preprocessor Include Paths” 属性页面。
* 点击 “Providers” 选项卡。从 “Providers” 列表中选择 “CDT Cross GCC Built-in Compiler Settings”。进入 “Command to get compiler specs” 目录,用 ``xtensa-esp32-elf-gcc`` 替换行首的 ``text${COMMAND}``,最终的完整 “Command to get compiler specs” 应为 ``xtensa-esp32-elf-gcc ${FLAGS} -E -P -v -dD "${INPUTS}"``
* 从 “Providers” 列表中选择 “CDT GCC Build Output Parser”然后在 Compiler 命令模式的起始位置输入 ``xtensa-esp32-elf-``,最终的完整编译器命令应为 ``xtensa-esp32-elf-(g?cc)|([gc]\+\+)|(clang)``
.. _eclipse-build-project:
在 Eclipse IDE 中创建项目
--------------------------
在首次创建项目前Eclipse IDE 可能会显示大量有关未定义值的错误和警告,主要原因在于项目编译过程中所需的一些源文件是在 ESP-IDF 项目新建过程中自动生成的。因此,这些错误和警告将在 ESP-IDF 项目生成完成后消失。
* 点击 “OK”关闭 Eclipse IDE 中的 “Properties” 对话框。
* 在 Eclipse IDE 界面外,打开命令管理器。进入项目目录,并通过 ``make menuconfig`` 命令对您的 ESP-IDF 项目进行配置。现阶段Eclipse 还不能完成这一步操作。
* 如果您跳过了最开始的配置步骤ESP-IDF 将在命令行中提示应进行配置 - 但由于 Eclipse 暂时不支持相关功能,因此该项目将挂起或失败。*
* 返回 Eclipse IDE 界面中,选择 “Project” -> “Build” 建立您的项目。
**提示**:如果您已经在 Eclipse IDE 环境外创建了项目,则可能需要选择 “Project” -> “Clean before choosing Project” -> “Build”允许 Eclipse 查看所有源文件的编译器参数,并借此确定头文件包含路径。
在 Eclipse IDE 中烧录项目
--------------------------
您可以将 ``make flash`` 目标放在 Eclipse 项目中,使用 Eclipse UI 中的 ``esptool.py`` 进行烧录:
* 打开 “Project Explorer”并右击您的项目请注意右击项目本身而非项目下的子文件否则 Eclipse 可能无法找到正确的 ``Makefile``)。
* 从菜单中选择 “Make Targets” -> “Create”。
* 输入 “flash” 为目标名称,其他选项使用默认值。
* 选择 “Project” -> “Make Target” -> “Build (快捷键Shift + F9创建自定义烧录目标用于编辑、烧录项目。
注意,您将需要通过 ``make menuconfig``,设置串行端口和其他烧录选项。``make menuconfig`` 仍需通过命令操作(请见平台的对应指南)。
如有必要,请按照相同步骤添加 ``bootloader````partition_table``
相关文档
--------
.. toctree::
:maxdepth: 1
eclipse-setup-windows
.. _eclipse.org: https://www.eclipse.org/

View file

@ -1 +1,219 @@
.. include:: ../../en/get-started/get-started-pico-kit.rst
ESP32-PICO-KIT V4 入门指南
============================
用户指南介绍了如何开始使用 ESP32-PICO-KIT V4 迷你开发板。有关 ESP32-PICO-KIT 其他版本的内容,请见 :doc:`../hw-reference/index`
准备工作
--------
* 1 × :ref:`ESP32-PICO-KIT V4 迷你开发板 <get-started-pico-kit-v4-board-front>`
* 1 × USB A/Micro USB B 电缆
* 1 × PCWindows、Linux 或 Mac OS 操作系统)
如果您希望直接开始使用 ESP32-PICO-KIT请见章节 `应用程序开发`_.
简介
----
ESP32-PICO-KIT V4 是一款来自`乐鑫 <https://espressif.com>`_,其内核采用了具有完整 Wi-Fi 和蓝牙功能的 ESP32 系 SIP 模组 ESP32-PICO-D4。与其他 ESP32 系模组相比ESP32-PICO-D4 模组已将 40 MHz 晶体振荡器、4 MB flash、滤波电容及射频匹配链路等所有外围器件无缝集成进封装内无需外围元器件即可工作。这将大大降低了用户额外采购元器件的数量和成本及额外组装测试的复杂度。
ESP32-PICO-KIT V4 集成了一个 USB-UART 桥接电路,可连接至 PC 的 USB 端口进行下载和调试。
为了便于连接ESP32-PICO-D4 上的所有 IO 信号和系统电源管脚均通过开发板两侧的排针(每侧 20 个 x 0.1 英寸引出。为了方便在微型面包板上的使用ESP32-PICO-KIT V4 开发板每侧的 20 个管脚中,有 17 个引出了排针,另外 3 个靠近天线的管脚不引出,可供用户最后焊接使用。
.. note::
每排未引出排针的 3 个管脚已连接至 ESP32-PICO-D4 SIP 模组的内置 flash 模块。更多信息,请见 `相关文档`_ 中的模组技术规格书。
ESP32-PICO-KIT V4 开发板的尺寸为 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"),具体请见 `开发板尺寸`_ 章节。本迷你开发板的功能框图如下图所示。
.. figure:: ../../_static/esp32-pico-kit-v4-functional-block-diagram.png
:align: center
:alt: ESP32-PICO-KIT V4 functional block diagram
:figclass: align-center
ESP32-PICO-KIT V4 功能框图
功能说明
--------
ESP32-PICO-KIT V4 开发板的关键元件、接口及控制方式如下文所示。
ESP32-PICO-D4
标准 ESP32-PICO-D4 模组,已焊接至 ESP32-PICO-KIT V4 开发板,具备 ESP32 芯片的完整功能仅需连接天线、LC 匹配电路、耦合电容和 EN 信号上拉电阻即可正常工作。
LDO
5V-to-3.3V 低压差稳压器
USB-UART 桥
单芯片 USB-UART 桥,可提供高达 1 Mbps 的传输速率。
Micro USB 接口
USB 接口,可用作电路板的供电电源及连接 PC 端的通信接口。
5V LED 电源指示灯
当开发板通电后USB 或外部 5V该指示灯将亮起。更多信息请见 `相关文档`_ 技术规格书中的原理图。
I/O
I/O ESP32-PICO-D4 上的所有管脚均通过开发板的排针引出。用户可以对 ESP32 进行编程,实现 PWM、ADC、DAC、I2C、I2S、SPI 等多种功能。更多信息,请见章节 `管脚说明`_
BOOT 键
长按 BOOT 键,并按下 EN 键进入固件下载模式,通过串口下载固件。
EN 键
复位键,可重置系统。
.. _get-started-pico-kit-v4-board-front:
.. figure:: ../../_static/esp32-pico-kit-v4-layout.jpg
:align: center
:alt: ESP32-PICO-KIT V4 board layout
:figclass: align-center
ESP32-PICO-KIT V4 开发板布局
电源选项
--------
ESP32-PICO-KIT V4 支持以下几种供电模式:
1. Micro USB 接口供电(默认)
2. 5V/GND 管脚供电
3. 3V3/GND 管脚供电
.. warning::
上述供电模式不可同时使用,否则可能会损坏电路板和/或电源。
应用程序开发
------------
在 ESP32-PICO-KIT V4 上电前,请首先确认电路板完好无损。
有关应用程序开发的具体步骤,请见章节 :doc:`index`
* :ref:`设置 Toolchain <get-started-setup-toolchain>`,用 C 语言开发应用
* :ref:`连接 <get-started-connect>` 模组至 PC并确认访问状态
* :ref:`构建并向 ESP32 烧录 example <get-started-build-flash>`
* 即刻 :ref:`监测 <get-started-build-monitor>` 应用程序的动作
管脚说明
--------
下表提供了介绍了开发板 I/O 管脚的**名称****功能**,具体布局与 `相关文档`_ 中的原理图一致。请参考 :ref:`get-started-pico-kit-v4-board-front`
Header J2
"""""""""
====== ================= ====== ======================================================
编号 名称 类型 功能
====== ================= ====== ======================================================
1 FLASH_SD1 (FSD1) I/O | GPIO8, SD_DATA1, SPID, HS1_DATA1 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2CTS
2 FLASH_SD3 (FSD3) I/O | GPIO7, SD_DATA0, SPIQ, HS1_DATA0 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2RTS
3 FLASH_CLK (FCLK) I/O | GPIO11, SD_CMD, SPICS0, HS1_CMD :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U1RTS
4 IO21 I/O | GPIO21, VSPIHD, EMAC_TX_EN
5 IO22 I/O | GPIO22, VSPIWP, U0RTS, EMAC_TXD1
6 IO19 I/O | GPIO19, VSPIQ, U0CTS, EMAC_TXD0
7 IO23 I/O | GPIO23, VSPID, HS1_STROBE
8 IO18 I/O | GPIO18, VSPICLK, HS1_DATA7
9 IO5 I/O | GPIO5, VSPICS0, HS1_DATA6, EMAC_RX_CLK
10 IO10 I/O | GPIO10, SD_DATA3, SPIWP, HS1_DATA3, U1TXD
11 IO9 I/O | GPIO9, SD_DATA2, SPIHD, HS1_DATA2, U1RXD
12 RXD0 I/O | GPIO3, U0RXD :ref:`(4) <get-started-pico-kit-v4-pin-notes>` , CLK_OUT2
13 TXD0 I/O | GPIO1, U0TXD :ref:`(4) <get-started-pico-kit-v4-pin-notes>` , CLK_OUT3, EMAC_RXD2
14 IO35 I | ADC1_CH7, RTC_GPIO5
15 IO34 I | ADC1_CH6, RTC_GPIO4
16 IO38 I | GPIO38, ADC1_CH2, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes>` , RTC_GPIO2
17 IO37 I | GPIO37, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH1, RTC_GPIO1
18 EN I | CHIP_PU
19 GND P | Ground
20 VDD33 (3V3) P | 3.3V 电源
====== ================= ====== ======================================================
Header J3
"""""""""
====== ================= ====== ======================================================
编号 名称 类型 功能
====== ================= ====== ======================================================
1 FLASH_CS (FCS) I/O | GPIO16, HS1_DATA4 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2RXD, EMAC_CLK_OUT
2 FLASH_SD0 (FSD0) I/O | GPIO17, HS1_DATA5 :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U2TXD, EMAC_CLK_OUT_180
3 FLASH_SD2 (FSD2) I/O | GPIO6, SD_CLK, SPICLK, HS1_CLK :ref:`(1) <get-started-pico-kit-v4-pin-notes>` , U1CTS
4 SENSOR_VP (FSVP) I | GPIO36, ADC1_CH0, ADC_PRE_AMP :ref:`(2a) <get-started-pico-kit-v4-pin-notes>` , RTC_GPIO0
5 SENSOR_VN (FSVN) I | GPIO39, ADC1_CH3, ADC_PRE_AMP :ref:`(2b) <get-started-pico-kit-v4-pin-notes>` , RTC_GPIO3
6 IO25 I/O | GPIO25, DAC_1, ADC2_CH8, RTC_GPIO6, EMAC_RXD0
7 IO26 I/O | GPIO26, DAC_2, ADC2_CH9, RTC_GPIO7, EMAC_RXD1
8 IO32 I/O | 32K_XP :ref:`(3a) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH4, TOUCH9, RTC_GPIO9
9 IO33 I/O | 32K_XN :ref:`(3b) <get-started-pico-kit-v4-pin-notes>` , ADC1_CH5, TOUCH8, RTC_GPIO8
10 IO27 I/O | GPIO27, ADC2_CH7, TOUCH7, RTC_GPIO17
| EMAC_RX_DV
11 IO14 I/O | ADC2_CH6, TOUCH6, RTC_GPIO16, MTMS, HSPICLK,
| HS2_CLK, SD_CLK, EMAC_TXD2
12 IO12 I/O | ADC2_CH5, TOUCH5, RTC_GPIO15, MTDI :ref:`(5) <get-started-pico-kit-v4-pin-notes>` , HSPIQ,
| HS2_DATA2, SD_DATA2, EMAC_TXD3
13 IO13 I/O | ADC2_CH4, TOUCH4, RTC_GPIO14, MTCK, HSPID,
| HS2_DATA3, SD_DATA3, EMAC_RX_ER
14 IO15 I/O | ADC2_CH3, TOUCH3, RTC_GPIO13, MTDO, HSPICS0
| HS2_CMD, SD_CMD, EMAC_RXD3
15 IO2 I/O | ADC2_CH2, TOUCH2, RTC_GPIO12, HSPIWP,
| HS2_DATA0, SD_DATA0
16 IO4 I/O | ADC2_CH0, TOUCH0, RTC_GPIO10, HSPIHD,
| HS2_DATA1, SD_DATA1, EMAC_TX_ER
17 IO0 I/O | ADC2_CH1, TOUCH1, RTC_GPIO11, CLK_OUT1
| EMAC_TX_CLK
18 VDD33 (3V3) P | 3.3V 电源
19 GND P | Ground
20 EXT_5V (5V) P | 5V 电源
====== ================= ====== ======================================================
.. _get-started-pico-kit-v4-pin-notes:
**Notes to** `管脚说明`_
1. 该管脚已连接至 ESP32-PICO-D4 的内置 flash 管脚。
2. 当用作 ADC_PRE_AMP 时,请在以下位置增加 270 pF 电容:(a) SENSOR_VP 和 IO37 之间;(b) SENSOR_VN 和 IO38 之间。
3. 32.768 kHz 晶振:(a) 输入;(b) 输出。
4. 该管脚已连接至开发板的 USB 桥芯片。
5. ESP32-PICO-KIT 内置 SPI flash 的工作电压为 3.3V。因此strapping 管脚 MTDI 在模组重启过程中应保持低电平。
开发板尺寸
----------
.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-back.jpg
:align: center
:alt: ESP32-PICO-KIT V4 dimensions - back
:figclass: align-center
ESP32-PICO-KIT V4 尺寸图 - 背面
.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-side.jpg
:align: center
:alt: ESP32-PICO-KIT V4 dimensions - side
:figclass: align-center
ESP32-PICO-KIT V4 尺寸图 - 侧面
相关文档
-----------------
* `ESP32-PICO-KIT V4 原理图 <https://dl.espressif.com/dl/schematics/esp32-pico-kit-v4_schematic.pdf>`_ (PDF)
* `ESP32-PICO-D4 技术规格书 <http://espressif.com/sites/default/files/documentation/esp32-pico-d4_datasheet_en.pdf>`_ (PDF)
* :doc:`../hw-reference/index`
.. toctree::
:hidden:
get-started-pico-kit-v3