Crash_Override/OVMS3-idf
1
0
Fork 0
Code Issues Pull requests Projects Releases Wiki Activity

Restored back original 'zh_CN' version files and updated links between versions

Browse source
This commit is contained in:
krzychb 2018-02-03 22:12:13 +01:00
parent 097adc3a33
commit 40bc387bae
26 changed files with 631 additions and 100 deletions
Show stats Download patch file Download diff file Expand all files Collapse all files

15
docs/README.md
View file

@ -1,11 +1,18 @@
# Documentation Source Folder
This folder contains source files of [ESP-IDF documentation](https://esp-idf.readthedocs.io/).
This folder contains source files of **ESP-IDF documentation** avialable in [English](https://esp-idf.readthedocs.io/en/latest/) and [中文](https://esp-idf.readthedocs.io/zh_CN/latest/).
The sources do not render well in GitHub and some information is not visible at all.
Use actual documentation generated instantly on each commit:
Use actual documentation generated within about 20 minutes on each commit:
* Main server: https://esp-idf.readthedocs.io/ or http://esp-idf.rtfd.io/
* Mirror: https://dl.espressif.com/doc/esp-idf/latest/
## English
* Main server: https://esp-idf.readthedocs.io/en/latest/ or http://esp-idf.readthedocs.io/en/latest/
* Mirror: https://espressif-docs.readthedocs-hosted.com/projects/esp-idf/en/latest/
* Latest docs mirror: https://dl.espressif.com/doc/esp-idf/latest/
## 中文
* Main server: https://esp-idf.readthedocs.io/zh_CN/latest/ or http://esp-idf.readthedocs.io/zh_CN/latest/
* Mirror: https://espressif-docs.readthedocs-hosted.com/projects/esp-idf/zh_CN/latest/

2
docs/en/about.rst
View file

@ -5,7 +5,7 @@ This is documentation of `ESP-IDF <https://github.com/espressif/esp-idf>`_, the
The ESP32 is 2.4 GHz Wi-Fi and Bluetooth combo, 32 bit dual core chip with 600 DMIPS processing power.
.. figure:: _static/about-doc.png
.. figure:: ../_static/about-doc.png
:align: center
:alt: Espressif IoT Integrated Development Framework
:figclass: align-center

2
docs/en/api-guides/app_trace.rst
View file

@ -15,7 +15,7 @@ Developers can use this library to send application specific state of execution
Tracing components when working over JTAG interface are shown in the figure below.
.. figure:: ../_static/app_trace-overview.jpg
.. figure:: ../../_static/app_trace-overview.jpg
:align: center
:alt: Tracing Components when Working Over JTAG
:figclass: align-center

6
docs/en/api-guides/freertos-smp.rst
View file

@ -208,7 +208,7 @@ where each element of the array is a linked list. Each linked list is of type
Ready state. The following diagram illustrates the ``pxReadyTasksList``
structure.
.. figure:: ../_static/freertos-ready-task-list.png
.. figure:: ../../_static/freertos-ready-task-list.png
:align: center
:alt: Vanilla FreeRTOS Ready Task List Structure
@ -226,7 +226,7 @@ calls the scheduler, it is able to look at the ``xCoreID`` member of each TCB
in the list to determine if a task is allowed to run on calling the core. The
ESP-IDF FreeRTOS ``pxReadyTasksList`` is illustrated below.
.. figure:: ../_static/freertos-ready-task-list-smp.png
.. figure:: ../../_static/freertos-ready-task-list-smp.png
:align: center
:alt: ESP-IDF FreeRTOS Ready Task List Structure
@ -246,7 +246,7 @@ the previous scheduler call from the other core would not be considered on the
current scheduler call. This issue is demonstrated in the following
illustration.
.. figure:: ../_static/freertos-ready-task-list-smp-pxIndex.png
.. figure:: ../../_static/freertos-ready-task-list-smp-pxIndex.png
:align: center
:alt: ESP-IDF pxIndex Behavior

2
docs/en/api-guides/jtag-debugging/configure-wrover.rst
View file

@ -47,7 +47,7 @@ Windows
5. Check the list of devices that should contain two WROVER specific USB entries: "Dual RS232-HS (Interface 0)" and "Dual RS232-HS (Interface 1)". The driver name would be "FTDIBUS (vxxxx)" and USB ID: 0403 6010.
.. figure:: ../../_static/jtag-usb-configuration-zadig.jpg
.. figure:: ../../../_static/jtag-usb-configuration-zadig.jpg
:align: center
:alt: Configuration of JTAG USB driver in Zadig tool
:figclass: align-center

24
docs/en/api-guides/jtag-debugging/debugging-examples.rst
View file

@ -12,7 +12,7 @@ Eclipse
Verify if your target is ready and loaded with :example:`get-started/blink` example. Configure and start debugger following steps in section :ref:`jtag-debugging-using-debugger-eclipse`. Pick up where target was left by debugger, i.e. having the application halted at breakpoint established at ``app_main()``.
.. figure:: ../../_static/debug-perspective.jpg
.. figure:: ../../../_static/debug-perspective.jpg
:align: center
:alt: Debug Perspective in Eclipse
:figclass: align-center
@ -39,7 +39,7 @@ Navigating though the code, call stack and threads
When the target is halted, debugger shows the list of threads in "Debug" window. The line of code where program halted is highlighted in another window below, as shown on the following picture. The LED stops blinking.
.. figure:: ../../_static/debugging-target-halted.jpg
.. figure:: ../../../_static/debugging-target-halted.jpg
:align: center
:alt: Target halted during debugging
:figclass: align-center
@ -50,7 +50,7 @@ Specific thread where the program halted is expanded showing the call stack. It
By expanding threads you can navigate throughout the application. Expand Thread #5 that contains much longer call stack. You will see there, besides function calls, numbers like ``0x4000000c``. They represent addresses of binary code not provided in source form.
.. figure:: ../../_static/debugging-navigate-through-the-stack.jpg
.. figure:: ../../../_static/debugging-navigate-through-the-stack.jpg
:align: center
:alt: Navigate through the call stack
:figclass: align-center
@ -71,7 +71,7 @@ When debugging, we would like to be able to stop the application at critical lin
Let's establish two breakpoints when the state of LED changes. Basing on code listing above, this happens at lines 33 and 36. To do so, hold the "Control" on the keyboard and double clink on number ``33`` in file ``blink.c`` file. A dialog will open where you can confirm your selection by pressing "OK" button. If you do not like to see the dialog just double click the line number. Set another breakpoint in line 36.
.. figure:: ../../_static/debugging-setting-breakpoint.jpg
.. figure:: ../../../_static/debugging-setting-breakpoint.jpg
:align: center
:alt: Setting a breakpoint
:figclass: align-center
@ -80,7 +80,7 @@ Let's establish two breakpoints when the state of LED changes. Basing on code li
Information how many breakpoints are set and where is shown in window "Breakpoints" on top right. Click "Show Breakpoints Supported by Selected Target" to refresh this list. Besides the two just set breakpoints the list may contain temporary breakpoint at function ``app_main()`` established at debugger start. As maximum two breakpoints are allowed (see :ref:`jtag-debugging-tip-breakpoints`), you need to delete it, or debugging will fail.
.. figure:: ../../_static/debugging-three-breakpoints-set.jpg
.. figure:: ../../../_static/debugging-three-breakpoints-set.jpg
:align: center
:alt: Three breakpoints are set / maximum two are allowed
:figclass: align-center
@ -103,7 +103,7 @@ When debugging, you may resume application and enter code waiting for some event
To check it, delete all breakpoints and click "Resume". Then click "Suspend". Application will be halted at some random point and LED will stop blinking. Debugger will expand tread and highlight the line of code where application halted.
.. figure:: ../../_static/debugging-target-halted-manually.jpg
.. figure:: ../../../_static/debugging-target-halted-manually.jpg
:align: center
:alt: Target halted manually
:figclass: align-center
@ -124,7 +124,7 @@ Before being able to demonstrate this functionality, using information discussed
Resume program by entering pressing F8 and let it halt. Now press "Step Over (F6)", one by one couple of times, to see how debugger is stepping one program line at a time.
.. figure:: ../../_static/debugging-step-over.jpg
.. figure:: ../../../_static/debugging-step-over.jpg
:align: center
:alt: Stepping through the code with "Step Over (F6)"
:figclass: align-center
@ -133,7 +133,7 @@ Resume program by entering pressing F8 and let it halt. Now press "Step Over (F6
If you press "Step Into (F5)" instead, then debugger will step inside subroutine calls.
.. figure:: ../../_static/debugging-step-into.jpg
.. figure:: ../../../_static/debugging-step-into.jpg
:align: center
:alt: Stepping through the code with "Step Into (F5)"
:figclass: align-center
@ -158,7 +158,7 @@ Being in the same ``blink.c`` project as before, set two breakpoints right after
Now resume program by pressing F8 and observe "Monitor" tab.
.. figure:: ../../_static/debugging-memory-location-on.jpg
.. figure:: ../../../_static/debugging-memory-location-on.jpg
:align: center
:alt: Observing memory location 0x3FF44004 changing one bit to ON"
:figclass: align-center
@ -167,7 +167,7 @@ Now resume program by pressing F8 and observe "Monitor" tab.
You should see one bit being flipped over at memory location ``0x3FF44004`` (and LED changing the state) each time F8 is pressed.
.. figure:: ../../_static/debugging-memory-location-off.jpg
.. figure:: ../../../_static/debugging-memory-location-off.jpg
:align: center
:alt: Observing memory location 0x3FF44004 changing one bit to ON"
:figclass: align-center
@ -192,7 +192,7 @@ In next step, in the window with "Breakpoints", click the "Expressions" tab. If
Resume program execution by pressing F8. Each time the program is halted you will see ``i`` value being incremented.
.. figure:: ../../_static/debugging-watch-variable.jpg
.. figure:: ../../../_static/debugging-watch-variable.jpg
:align: center
:alt: Watching program variable "i"
:figclass: align-center
@ -210,7 +210,7 @@ Setting conditional breakpoints
Here comes more interesting part. You may set a breakpoint to halt the program execution, if certain condition is satisfied. Right click on the breakpoint to open a context menu and select "Breakpoint Properties". Change the selection under "Type:" to "Hardware" and enter a "Condition:" like ``i == 2``.
.. figure:: ../../_static/debugging-setting-conditional-breakpoint.jpg
.. figure:: ../../../_static/debugging-setting-conditional-breakpoint.jpg
:align: center
:alt: Setting a conditional breakpoint
:figclass: align-center

8
docs/en/api-guides/jtag-debugging/index.rst
View file

@ -48,7 +48,7 @@ How it Works?
The key software and hardware to perform debugging of ESP32 with OpenOCD over JTAG (Joint Test Action Group) interface is presented below and includes **xtensa-esp32-elf-gdb debugger**, **OpenOCD on chip debugger** and **JTAG adapter** connected to **ESP32** target.
.. figure:: ../../_static/jtag-debugging-overview.jpg
.. figure:: ../../../_static/jtag-debugging-overview.jpg
:align: center
:alt: JTAG debugging - overview diagram
:figclass: align-center
@ -100,13 +100,13 @@ Pick up your OS below and follow provided instructions to setup OpenOCD.
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
.. |windows-logo| image:: ../../../_static/windows-logo.png
:target: ../jtag-debugging/setup-openocd-windows.html
.. |linux-logo| image:: ../../_static/linux-logo.png
.. |linux-logo| image:: ../../../_static/linux-logo.png
:target: ../jtag-debugging/setup-openocd-linux.html
.. |macos-logo| image:: ../../_static/macos-logo.png
.. |macos-logo| image:: ../../../_static/macos-logo.png
:target: ../jtag-debugging/setup-openocd-macos.html
.. _Windows: ../jtag-debugging/setup-openocd-windows.html

8
docs/en/api-guides/jtag-debugging/using-debugger.rst
View file

@ -28,7 +28,7 @@ Once installation is complete, configure debugging session following steps below
A sample window with settings entered in points 1 - 5 is shown below.
.. figure:: ../../_static/hw-debugging-main-tab.jpg
.. figure:: ../../../_static/hw-debugging-main-tab.jpg
:align: center
:alt: Configuration of GDB Hardware Debugging - Main tab
:figclass: align-center
@ -41,7 +41,7 @@ Once installation is complete, configure debugging session following steps below
Configuration entered in points 6 and 7 is shown on the following picture.
.. figure:: ../../_static/hw-debugging-debugger-tab.jpg
.. figure:: ../../../_static/hw-debugging-debugger-tab.jpg
:align: center
:alt: Configuration of GDB Hardware Debugging - Debugger tab
:figclass: align-center
@ -67,7 +67,7 @@ Once installation is complete, configure debugging session following steps below
Configuration described in points 8 - 11 is shown below.
.. figure:: ../../_static/hw-debugging-startup-tab.jpg
.. figure:: ../../../_static/hw-debugging-startup-tab.jpg
:align: center
:alt: Configuration of GDB Hardware Debugging - Startup tab
:figclass: align-center
@ -80,7 +80,7 @@ Once installation is complete, configure debugging session following steps below
Once all 1 - 12 configuration steps are satisfied, the new Eclipse perspective called "Debug" will open as shown on example picture below.
.. figure:: ../../_static/debug-perspective.jpg
.. figure:: ../../../_static/debug-perspective.jpg
:align: center
:alt: Debug Perspective in Eclipse
:figclass: align-center

2
docs/en/api-reference/peripherals/ledc.rst
View file

@ -22,7 +22,7 @@ Getting LEDC to work on specific channel in either :ref:`high or low speed mode
In an optional step it is also possible to set up an interrupt on the fade end.
.. figure:: ../../_static/ledc-api-settings.jpg
.. figure:: ../../../_static/ledc-api-settings.jpg
:align: center
:alt: Key Settings of LED PWM Controller's API
:figclass: align-center

8
docs/en/api-reference/peripherals/rmt.rst
View file

@ -23,13 +23,13 @@ The signal, which consists of a series of pulses, is generated by RMT's transmit
a [style=none, width=100, label="{11,high,7,low},\n{5,high,5,low},\n..."]
b [label="Waveform\nGenerator"]
c [style=none, label="", background="_static/rmt-waveform.png"]
c [style=none, label="", background="../_static/rmt-waveform.png"]
d [shape=beginpoint, label="mod"]
e [style=none, width=60, height=40, label="Carrier\nenable"]
f [label="Carrier\nGenerator"]
g [style=none, label="", background="_static/rmt-carrier.png"]
g [style=none, label="", background="../_static/rmt-carrier.png"]
h [shape=none]
o [style=none, label="", background="_static/rmt-waveform-modulated.png"]
o [style=none, label="", background="../_static/rmt-waveform-modulated.png"]
group {
label = Input
@ -63,7 +63,7 @@ The reverse operation is performed by the receiver, where a series of pulses is
e -- f;
f -> b [folded];
a [style=none, label="", background="_static/rmt-waveform.png"]
a [style=none, label="", background="../_static/rmt-waveform.png"]
b [label=Filter]
c [label="Edge\nDetect"]
d [style=none, width=100, label="{11,high,7,low},\n{5,high,5,low},\n..."]

2
docs/en/api-reference/peripherals/touch_pad.rst
View file

@ -77,7 +77,7 @@ The following summarizes available measurement parameters and corresponding 'set
Relationship between voltage range (high / low reference voltages), speed (slope) and measure time is shown on figure below.
.. figure:: ../../_static/touch_pad-measurement-parameters.jpg
.. figure:: ../../../_static/touch_pad-measurement-parameters.jpg
:align: center
:alt: Touch Pad - relationship between measurement parameters
:figclass: align-center

10
docs/en/contribute/documenting-code.rst
View file

@ -17,7 +17,7 @@ Doxygen is phrasing the code, extracting the commands together with subsequent t
Typical comment block, that contains documentation of a function, looks like below.
.. image:: ../_static/doc-code-documentation-inline.png
.. image:: ../../_static/doc-code-documentation-inline.png
:align: center
:alt: Sample inline code documentation
@ -31,7 +31,7 @@ The ultimate goal is to ensure that all the code is consistently documented, so
With these tools the above piece of code renders like below:
.. image:: ../_static/doc-code-documentation-rendered.png
.. image:: ../../_static/doc-code-documentation-rendered.png
:align: center
:alt: Sample inline code after rendering
@ -47,19 +47,19 @@ When writing code for this repository, please follow guidelines below.
3. Do not add a data type before parameter or any other characters besides spaces. All spaces and line breaks are compressed into a single space. If you like to break a line, then break it twice.
.. image:: ../_static/doc-code-function.png
.. image:: ../../_static/doc-code-function.png
:align: center
:alt: Sample function documented inline and after rendering
4. If function has void input or does not return any value, then skip ``@param`` or ``@return``
.. image:: ../_static/doc-code-void-function.png
.. image:: ../../_static/doc-code-void-function.png
:align: center
:alt: Sample void function documented inline and after rendering
5. When documenting a ``define`` as well as members of a ``struct`` or ``enum``, place specific comment like below after each member.
.. image:: ../_static/doc-code-member.png
.. image:: ../../_static/doc-code-member.png
:align: center
:alt: Sample of member documentation inline and after rendering

8
docs/en/get-started/establish-serial-connection.rst
View file

@ -25,14 +25,14 @@ Check the list of identified COM ports in the Windows Device Manager. Disconnect
Figures below show serial port for ESP32 DevKitC and ESP32 WROVER KIT
.. figure:: ../_static/esp32-devkitc-in-device-manager.png
.. figure:: ../../_static/esp32-devkitc-in-device-manager.png
:align: center
:alt: USB to UART bridge of ESP32-DevKitC in Windows Device Manager
:figclass: align-center
USB to UART bridge of ESP32-DevKitC in Windows Device Manager
.. figure:: ../_static/esp32-wrover-kit-in-device-manager.png
.. figure:: ../../_static/esp32-wrover-kit-in-device-manager.png
:align: center
:alt: Two USB Serial Ports of ESP-WROVER-KIT in Windows Device Manager
:figclass: align-center
@ -73,14 +73,14 @@ Now verify that the serial connection is operational. You can do this using a se
Run terminal, set identified serial port, baud rate = 115200, data bits = 8, stop bits = 1, and parity = N. Below are example screen shots of setting the port and such transmission parameters (in short described as 115200-8-1-N) on Windows and Linux. Remember to select exactly the same serial port you have identified in steps above.
.. figure:: ../_static/putty-settings-windows.png
.. figure:: ../../_static/putty-settings-windows.png
:align: center
:alt: Setting Serial Communication in PuTTY on Windows
:figclass: align-center
Setting Serial Communication in PuTTY on Windows
.. figure:: ../_static/putty-settings-linux.png
.. figure:: ../../_static/putty-settings-linux.png
:align: center
:alt: Setting Serial Communication in PuTTY on Linux
:figclass: align-center

2
docs/en/get-started/get-started-devkitc-v2.rst
View file

@ -36,7 +36,7 @@ I/O
.. _get-started-esp32-devkitc-v2-board-front:
.. figure:: ../_static/esp32-devkitc-v2-functional-overview.png
.. figure:: ../../_static/esp32-devkitc-v2-functional-overview.png
:align: center
:alt: ESP32-DevKitC V2 board layout
:figclass: align-center

4
docs/en/get-started/get-started-devkitc.rst
View file

@ -53,7 +53,7 @@ I/O
.. _get-started-esp32-devkitc-board-front:
.. figure:: ../_static/esp32-devkitc-functional-overview.jpg
.. figure:: ../../_static/esp32-devkitc-functional-overview.jpg
:align: center
:alt: ESP32-DevKitC V4 with ESP-WROOM-32 module soldered
:figclass: align-center
@ -91,7 +91,7 @@ To start development of applications, proceed to section :doc:`index`, that will
Board Dimensions
----------------
.. figure:: ../_static/esp32-devkitc-dimensions-back.jpg
.. figure:: ../../_static/esp32-devkitc-dimensions-back.jpg
:align: center
:alt: ESP32 DevKitC board dimensions - back
:figclass: align-center

2
docs/en/get-started/get-started-pico-kit-v3.rst
View file

@ -36,7 +36,7 @@ EN Button
BOOT Button
Holding down the Boot button and pressing the EN button initiates the firmware download mode. Then user can download firmware through the serial port.
.. figure:: ../_static/esp32-pico-kit-v3-layout.jpg
.. figure:: ../../_static/esp32-pico-kit-v3-layout.jpg
:align: center
:alt: ESP32-PICO-KIT V3 board layout
:figclass: align-center

8
docs/en/get-started/get-started-pico-kit.rst
View file

@ -29,7 +29,7 @@ For easy interfacing, all the IO signals and system power on ESP32-PICO-D4 are l
The board dimensions are 52 x 20.3 x 10 mm (2.1" x 0.8" x 0.4"), see section `Board Dimensions`_. An overview functional block diagram is shown below.
.. figure:: ../_static/esp32-pico-kit-v4-functional-block-diagram.png
.. figure:: ../../_static/esp32-pico-kit-v4-functional-block-diagram.png
:align: center
:alt: ESP32-PICO-KIT V4 functional block diagram
:figclass: align-center
@ -61,7 +61,7 @@ EN Button
.. _get-started-pico-kit-v4-board-front:
.. figure:: ../_static/esp32-pico-kit-v4-layout.jpg
.. figure:: ../../_static/esp32-pico-kit-v4-layout.jpg
:align: center
:alt: ESP32-PICO-KIT V4 board layout
:figclass: align-center
@ -182,14 +182,14 @@ No. Name Type Function
Board Dimensions
----------------
.. figure:: ../_static/esp32-pico-kit-v4-dimensions-back.jpg
.. 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 dimensions - back
.. figure:: ../_static/esp32-pico-kit-v4-dimensions-side.jpg
.. figure:: ../../_static/esp32-pico-kit-v4-dimensions-side.jpg
:align: center
:alt: ESP32-PICO-KIT V4 dimensions - side
:figclass: align-center

20
docs/en/get-started/get-started-wrover-kit-v2.rst
View file

@ -29,7 +29,7 @@ Functionality Overview
Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
.. figure:: ../_static/esp32-wrover-kit-block-diagram.png
.. figure:: ../../_static/esp32-wrover-kit-block-diagram.png
:align: center
:alt: ESP-WROVER-KIT block diagram
:figclass: align-center
@ -89,7 +89,7 @@ Micro SD Card
LCD
ESP-WROVER-KIT supports mounting and interfacing a 3.2” SPI (standard 4-wire Serial Peripheral Interface) LCD, as shown on figure :ref:`esp-wrover-kit-v2-board-back`.
.. figure:: ../_static/esp-wrover-kit-v2-layout-front.png
.. figure:: ../../_static/esp-wrover-kit-v2-layout-front.png
:align: center
:alt: ESP-WROVER-KIT board layout - front
:figclass: align-center
@ -98,7 +98,7 @@ LCD
.. _esp-wrover-kit-v2-board-back:
.. figure:: ../_static/esp-wrover-kit-v2-layout-back.png
.. figure:: ../../_static/esp-wrover-kit-v2-layout-back.png
:align: center
:alt: ESP-WROVER-KIT board layout - back
:figclass: align-center
@ -180,12 +180,12 @@ Related Documents
* :doc:`../hw-reference/index`
.. |jp1-sd_io2| image:: ../_static/wrover-jp1-sd_io2.png
.. |jp1-both| image:: ../_static/wrover-jp1-both.png
.. |jp7-ext_5v| image:: ../_static/wrover-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../_static/wrover-jp7-usb_5v.png
.. |jp8| image:: ../_static/wrover-jp8.png
.. |jp11-rx-tx| image:: ../_static/wrover-jp11-tx-rx.png
.. |jp14| image:: ../_static/wrover-jp14.png
.. |jp1-sd_io2| image:: ../../_static/wrover-jp1-sd_io2.png
.. |jp1-both| image:: ../../_static/wrover-jp1-both.png
.. |jp7-ext_5v| image:: ../../_static/wrover-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../../_static/wrover-jp7-usb_5v.png
.. |jp8| image:: ../../_static/wrover-jp8.png
.. |jp11-rx-tx| image:: ../../_static/wrover-jp11-tx-rx.png
.. |jp14| image:: ../../_static/wrover-jp14.png
.. _ESP-WROVER-KIT V2 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-2.pdf

20
docs/en/get-started/get-started-wrover-kit.rst
View file

@ -29,7 +29,7 @@ Functionality Overview
Block diagram below presents main components of ESP-WROVER-KIT and interconnections between components.
.. figure:: ../_static/esp32-wrover-kit-block-diagram.png
.. figure:: ../../_static/esp32-wrover-kit-block-diagram.png
:align: center
:alt: ESP-WROVER-KIT block diagram
:figclass: align-center
@ -90,7 +90,7 @@ LCD
.. _get-started-esp-wrover-kit-board-front:
.. figure:: ../_static/esp32-wrover-kit-layout-front.jpg
.. figure:: ../../_static/esp32-wrover-kit-layout-front.jpg
:align: center
:alt: ESP-WROVER-KIT board layout - front
:figclass: align-center
@ -99,7 +99,7 @@ LCD
.. _get-started-esp-wrover-kit-board-back:
.. figure:: ../_static/esp32-wrover-kit-layout-back.jpg
.. figure:: ../../_static/esp32-wrover-kit-layout-back.jpg
:align: center
:alt: ESP-WROVER-KIT board layout - back
:figclass: align-center
@ -399,13 +399,13 @@ Related Documents
* :doc:`../hw-reference/index`
.. |jp1-sd_io2| image:: ../_static/wrover-jp1-sd_io2.png
.. |jp1-both| image:: ../_static/wrover-jp1-both.png
.. |jp7-ext_5v| image:: ../_static/wrover-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../_static/wrover-jp7-usb_5v.png
.. |jp8| image:: ../_static/wrover-jp8.png
.. |jp11-rx-tx| image:: ../_static/wrover-jp11-tx-rx.png
.. |jp14| image:: ../_static/wrover-jp14.png
.. |jp1-sd_io2| image:: ../../_static/wrover-jp1-sd_io2.png
.. |jp1-both| image:: ../../_static/wrover-jp1-both.png
.. |jp7-ext_5v| image:: ../../_static/wrover-jp7-ext_5v.png
.. |jp7-usb_5v| image:: ../../_static/wrover-jp7-usb_5v.png
.. |jp8| image:: ../../_static/wrover-jp8.png
.. |jp11-rx-tx| image:: ../../_static/wrover-jp11-tx-rx.png
.. |jp14| image:: ../../_static/wrover-jp14.png
.. _ESP-WROVER-KIT V3 schematic: https://dl.espressif.com/dl/schematics/ESP-WROVER-KIT_SCH-3.pdf

10
docs/en/get-started/index.rst
View file

@ -24,7 +24,7 @@ To develop applications for ESP32 you need:
* A text editor to write programs (**Projects**) in C, e.g. `Eclipse <https://www.eclipse.org/>`_
* The **ESP32** board itself and a **USB cable** to connect it to the **PC**
.. figure:: ../_static/what-you-need.png
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
@ -84,13 +84,13 @@ The quickest way to start development with ESP32 is by installing a prebuilt too
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../_static/windows-logo.png
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started/windows-setup.html
.. |linux-logo| image:: ../_static/linux-logo.png
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started/linux-setup.html
.. |macos-logo| image:: ../_static/macos-logo.png
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started/macos-setup.html
.. _Windows: ../get-started/windows-setup.html
@ -175,7 +175,7 @@ Being in terminal window, go to directory of ``hello_world`` application by typi
If previous steps have been done correctly, the following menu will be displayed:
.. figure:: ../_static/project-configuration.png
.. figure:: ../../_static/project-configuration.png
:align: center
:alt: Project configuration - Home window
:figclass: align-center

2
docs/en/get-started/windows-setup.rst
View file

@ -23,7 +23,7 @@ Check it Out
Open a MSYS2 MINGW32 terminal window by running ``C:\msys32\mingw32.exe``. The environment in this window is a bash shell.
.. figure:: ../_static/msys2-terminal-window.png
.. figure:: ../../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center

33
docs/en/index.rst
View file

@ -3,33 +3,33 @@ ESP-IDF Programming Guide
This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip.
+------------------+------------------+------------------+
| |Get Started|_ | |API Reference|_ | |H/W Reference|_ |
+------------------+------------------+------------------+
| `Get Started`_ | `API Reference`_ | `H/W Reference`_ |
+------------------+------------------+------------------+
| |API Guides|_ | |Contribute|_ | |Resources|_ |
+------------------+------------------+------------------+
| `API Guides`_ | `Contribute`_ | `Resources`_ |
+------------------+------------------+------------------+
================== ================== ==================
|Get Started|_ |API Reference|_ |H/W Reference|_
------------------ ------------------ ------------------
`Get Started`_ `API Reference`_ `H/W Reference`_
------------------ ------------------ ------------------
|API Guides|_ |Contribute|_ |Resources|_
------------------ ------------------ ------------------
`API Guides`_ `Contribute`_ `Resources`_
================== ================== ==================
.. |Get Started| image:: _static/get-started.gif
.. |Get Started| image:: ../_static/get-started.gif
.. _Get Started: get-started/index.html
.. |API Reference| image:: _static/api-reference.gif
.. |API Reference| image:: ../_static/api-reference.gif
.. _API Reference: api-reference/index.html
.. |H/W Reference| image:: _static/hw-reference.gif
.. |H/W Reference| image:: ../_static/hw-reference.gif
.. _H/W Reference: hw-reference/index.html
.. |Api Guides| image:: _static/api-guides.gif
.. |Api Guides| image:: ../_static/api-guides.gif
.. _Api Guides: api-guides/index.html
.. |Contribute| image:: _static/contribute.gif
.. |Contribute| image:: ../_static/contribute.gif
.. _Contribute: contribute/index.html
.. |Resources| image:: _static/resources.gif
.. |Resources| image:: ../_static/resources.gif
.. _Resources: resources.html
@ -37,7 +37,6 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
:hidden:
Get Started <get-started/index>
快速入门 <get-started/index-cn>
API Reference <api-reference/index>
H/W Reference <hw-reference/index>
API Guides <api-guides/index>
@ -45,5 +44,5 @@ This is the documentation for Espressif IoT Development Framework (`esp-idf <htt
Resources <resources>
Copyrights <COPYRIGHT>
About <about>
* :ref:`genindex`

325
docs/zh_CN/get-started/index.rst
View file

@ -1 +1,324 @@
.. include:: ../../en/get-started/index.rst
***********
快速入门
***********
本文档旨在指导用户创建 ESP32 的软件环境。本文将通过一个简单的例子来说明如何使用 ESP-IDF (Espressif IoT Development Framework)，包括配置、编译、下载固件到开发板等步骤。
概述
======
ESP32 是一套 Wi-Fi (2.4 GHz) 和蓝牙 (4.2) 双模解决方案，集成了高性能的 CPU 内核、超低功耗协处理器和丰富的外设。ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、稳定性、通用性和可靠性，适用于各种应用和不同功耗需求。
乐鑫为用户提供完整的软、硬件资源进行 ESP32 设备的开发。乐鑫所研发的软件开发环境 ESP-IDF 能够帮助用户快速开发物联网 (IoT) 应用，满足用户对于 Wi-Fi、蓝牙、低功耗等性能的需求。
准备工作
=========
开发 ESP32 应用程序需要准备：
* **电脑**：安装 Windows、Linux 或者 Mac 操作系统
* **工具链**：用于编译 ESP32 **应用程序**
* **ESP-IDF**：包含 ESP32 API 和用于操作 **工具链** 的脚本
* **文本编辑器**：编写 C 语言程序，例如 `Eclipse <http://www.eclipse.org/>`_
* **ESP32 开发板** 和将其连接到 **电脑** 的 **USB 线**
.. figure:: ../../_static/what-you-need.png
:align: center
:alt: Development of applications for ESP32
:figclass: align-center
开发应用程序
开发环境的准备工作包括以下三部分：
1. 设置 **工具链**
2. 从 GitHub 上获取 **ESP-IDF**
3. 安装和配置 **Eclipse**
如果你偏好使用其它编辑器，可以跳过最后一步。
环境设置好后，就可以开始开发应用程序了。整个过程可以概括为如下四步：
1. 配置 **工程** 并编写代码
2. 编译 **工程** 并链接成一个 **应用程序**
3. 烧写 **应用程序** 到 **ESP32**
4. 监视/调试 **应用程序**
下文将全程指导你操作完成这些步骤。
开发板指南
==========
如果你有下列任一 ESP32 开发板，请点击对应的链接，对照指南进行操作就可以让你的板子跑起来。
.. toctree::
:maxdepth: 1
ESP32 DevKitC <../get-started/get-started-devkitc>
ESP-WROVER-KIT <../get-started/get-started-wrover-kit>
ESP32-PICO-KIT <../get-started/get-started-pico-kit>
如果你使用其它开发板，请查看下面的内容。
.. _get-started-setup-toolchain:
设置工具链
===============
用 ESP32 进行开发最快的方法是安装预编译的工具链。请根据你的操作系点击对应的链接，并按照链接中的指导进行安装。
.. toctree::
:hidden:
Windows <../get-started/windows-setup>
Linux <../get-started/linux-setup>
MacOS <../get-started/macos-setup>
+-------------------+-------------------+-------------------+
| |windows-logo| | |linux-logo| | |macos-logo| |
+-------------------+-------------------+-------------------+
| `Windows`_ | `Linux`_ | `Mac OS`_ |
+-------------------+-------------------+-------------------+
.. |windows-logo| image:: ../../_static/windows-logo.png
:target: ../get-started/windows-setup.html
.. |linux-logo| image:: ../../_static/linux-logo.png
:target: ../get-started/linux-setup.html
.. |macos-logo| image:: ../../_static/macos-logo.png
:target: ../get-started/macos-setup.html
.. _Windows: ../get-started/windows-setup.html
.. _Linux: ../get-started/linux-setup.html
.. _Mac OS: ../get-started/macos-setup.html
.. note::
我们使用 ``~/esp`` 目录来安装预编译的工具链、ESP-IDF 和示例程序。你也可以使用其它目录，但是需要注意调整相应的指令。
你可以安装预编译的工具链或者自定义你的环境，这完全取决于个人经验和偏好。如果你要自定义环境，请参考 :ref:`get-started-customized-setup`。
工具链设置完成后，就可以 :ref:`get-started-get-esp-idf` 了。
.. _get-started-get-esp-idf:
获取 ESP-IDF
=================
.. highlight:: bash
工具链（包括用于编译和构建应用程序的程序）安装完后，你还需要 ESP32 相关的 API/库。API/库在 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_ 中。要获取这些 API/库，打开一个终端，进入某个你希望存放 ESP-IDF 的目录，然后 ``git clone`` 以下指令： ::
cd ~/esp
git clone --recursive https://github.com/espressif/esp-idf.git
ESP-IDF 将会被下载到 ``~/esp/esp-idf``。
.. note::
注意这里有个 ``--recursive`` 选项。如果你克隆 ESP-IDF 时没有带这个选项，你还需要运行额外的命令来获取子模块： ::
cd ~/esp/esp-idf
git submodule update --init
.. _get-started-setup-path:
设置 ESP-IDF 路径
=====================
工具链程序使用环境变量 ``IDF_PATH`` 来访问 ESP-IDF。这个变量应该设置在你的 PC 中，否则工程将不能编译。你可以在每次 PC 重启时手工设置，也可以通过在用户配置文件中定义 ``IDF_PATH`` 变量来永久性设置。要永久性设置，请参考 :doc:`add-idf_path-to-profile` 文档中 :ref:`Windows <add-idf_path-to-profile-windows>` 或 :ref:`Linux and MacOS <add-idf_path-to-profile-linux-macos>` 相关的指导进行操作。
.. _get-started-start-project:
创建一个工程
===============
现在可以开始创建 ESP32 应用程序了。为了快速开始，我们这里以 IDF 的 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程为例进行说明。
将 :example:`get-started/hello_world` 拷贝到 ``~/esp`` 目录： ::
cd ~/esp
cp -r $IDF_PATH/examples/get-started/hello_world
ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照上面的方法进行创建。
.. important::
esp-idf 构建系统不支持在路径中存在空格。
.. _get-started-connect:
连接
=======
还有几个步骤就完成了。在继续后续操作前，先将 ESP32 开发板连接到 PC，然后检查串口号，看看它能否正常通信。如果你不知道如何操作，请查看 Establish Serial Connection with ESP32 中的相关指导。请注意一下端口号，我们在下一步中会用到。
.. _get-started-configure:
配置
=========
在终端窗口中，输入 ``cd ~/esp/hello_world`` 进入 ``hello_world`` 所在目录，然后启动工程配置工具 ``menuconfig``： ::
cd ~/esp/hello_world
make menuconfig
如果之前的步骤都正确，则会显示下面的菜单：
.. figure:: ../../_static/project-configuration.png
:align: center
:alt: Project configuration - Home window
:figclass: align-center
工程配置 - 主窗口
在菜单中，进入 ``Serial flasher config`` > ``Default serial port`` 配置串口（工程将会加载到该串口上）。输入回车确认选择，选择 ``< Save >`` 保存配置，然后选择 ``< Exit >`` 退出应用程序。
.. note::
在 Windows 系统中，端口号的名称类似 COM1，在 MacOS 中以 ``/dev/cu.`` 开始，而在 Linux 系统中，以 ``/dev/tty`` 开始。
（详细内容可以参考章节 :doc:`establish-serial-connection`。）
下面是一些使用 ``menuconfig`` 的小技巧：
* 使用 up & down 组合键在菜单中上下移动
* 使用 Enter 键进入一个子菜单，Escape 键退出子菜单或退出整个菜单
* 输入 ``?`` 查看帮助信息，Enter 键退出帮助屏幕
* 使用空格键或 ``Y`` 和 ``N`` 键来使能 (Yes) 和禁止 (No) 带有复选框 "``[*]``" 的配置项
* 当光标在某个配置项上面高亮时，输入 ``?`` 可以直接查看该项的帮助信息
* 输入 ``/`` 搜索配置项
.. note::
如果你是 **Arch Linux** 用户，需要进入 ``SDK tool configuration`` 将 ``Python 2 interpreter`` 从 ``python`` 修改为 ``python2``。
.. _get-started-build-flash:
编译和烧写
===============
现在可以编译和烧写应用程序了，执行指令： ::
make flash
这条命令会编译应用程序和所有的 ESP-IDF 组件，生成 bootloader、分区表和应用程序 bin 文件，并将这些 bin 文件烧写到 ESP32 板子上。
.. highlight:: none
::
esptool.py v2.0-beta2
Flashing binaries to serial port /dev/ttyUSB0 (app at offset 0x10000)...
esptool.py v2.0-beta2
Connecting........___
Uploading stub...
Running stub...
Stub running...
Changing baud rate to 921600
Changed.
Attaching SPI flash...
Configuring flash size...
Auto-detected Flash size: 4MB
Flash params set to 0x0220
Compressed 11616 bytes to 6695...
Wrote 11616 bytes (6695 compressed) at 0x00001000 in 0.1 seconds (effective 920.5 kbit/s)...
Hash of data verified.
Compressed 408096 bytes to 171625...
Wrote 408096 bytes (171625 compressed) at 0x00010000 in 3.9 seconds (effective 847.3 kbit/s)...
Hash of data verified.
Compressed 3072 bytes to 82...
Wrote 3072 bytes (82 compressed) at 0x00008000 in 0.0 seconds (effective 8297.4 kbit/s)...
Hash of data verified.
Leaving...
Hard resetting...
如果没有任何问题，在编译过程结束后将能看到类似上面的消息。最后，板子将会复位，应用程序 "hello_world" 开始启动。
如果你想使用 Eclipse IDE 而不是运行 ``make``，请参考 :doc:`Eclipse guide <eclipse-setup>`。
.. _get-started-build-monitor:
监视器
=======
如果要查看 "hello_world" 程序是否真的在运行，输入命令 ``make monitor``。这个命令会启动 IDF Monitor 程序： ::
$ make monitor
MONITOR
--- idf_monitor on /dev/ttyUSB0 115200 ---
--- Quit: Ctrl+] | Menu: Ctrl+T | Help: Ctrl+T followed by Ctrl+H ---
ets Jun 8 2016 00:22:57
rst:0x1 (POWERON_RESET),boot:0x13 (SPI_FAST_FLASH_BOOT)
ets Jun 8 2016 00:22:57
...
在启动消息和诊断消息后，你就能看到 "Hello world!" 程序所打印的消息： ::
...
Hello world!
Restarting in 10 seconds...
I (211) cpu_start: Starting scheduler on APP CPU.
Restarting in 9 seconds...
Restarting in 8 seconds...
Restarting in 7 seconds...
要退出监视器，请使用快捷键 ``Ctrl+]``。
.. note::
如果串口打印的不是上面显示的消息而是类似下面的乱码： ::
e<><65><EFBFBD>)(Xn@<40>y.!<21><>(<28>PW+)<29><>Hn9a؅/9<>!<21>t5<74><35>P<EFBFBD>~<7E>k<EFBFBD><6B>e<EFBFBD>ea<65>5<EFBFBD>jA
~zY<7A><59>Y(1<>,1<15><> e<><65><EFBFBD>)(Xn@<40>y.!Dr<44>zY(<28>jpi<70>|<7C>+z5Ymvp
或者监视器程序启动失败，那么可能你的开发板用的是 26 MHz 晶振，而 ESP-IDF 默认的是 40 MHz 晶振。请退出监视器，回到 :ref:`配置 <get-started-configure>`，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 改为 26 MHz，然后再次 :ref:`编译和烧写 <get-started-build-flash>`。请在 ``make menuconfig`` 的 Component config --> ESP32-specific --> Main XTAL frequency 中配置。
要一次性执行 ``make flash`` 和 ``make monitor``，输入 ``make flash monitor``。参考文档 :doc:`IDF Monitor <idf-monitor>` 里的快捷键和更多内容。
你已完成 ESP32 的入门！
现在你可以尝试其他的示例工程 :idf:`examples`，或者直接开发自己的应用程序。
更新 ESP-IDF
=============
使用 ESP-IDF 一段时间后，你可能想要进行升级来获得新的性能或者对 bug 进行修复。最简单的更新方式是删除已有的 ``esp-idf`` 文件夹然后再克隆一个，即重复 :ref:`get-started-get-esp-idf` 里的操作。
另外一种方法是只更新有改动的部分，如果你不容易登陆 GitHub，那么这种方法比较合适。执行以下命令： ::
cd ~/esp/esp-idf
git pull
git submodule update --init --recursive
``git pull`` 指令是从 ESP-IDF 仓库中获取合并更新。``git submodule update --init --recursive`` 用来更新现有的子模块或拷贝新的子模块。在 GitHub 上，子模块链接到其他仓库，所以需要这个额外的指令来下载到你的电脑里。
如果你想使用某一版本的 ESP-IDF，比如 `v2.1` 版本，请执行以下指令： ::
cd ~/esp
git clone https://github.com/espressif/esp-idf.git esp-idf-v2.1
cd esp-idf-v2.1/
git checkout v2.1
git submodule update --init --recursive
然后 :doc:`add-idf_path-to-profile`，这样工具链脚本就能够知道这一版本的 ESP-IDF 的具体位置。
相关文档
=================
.. toctree::
:maxdepth: 1
../get-started/add-idf_path-to-profile
../get-started/establish-serial-connection
../get-started/make-project
../get-started/eclipse-setup
../get-started/idf-monitor
../get-started/toolchain-setup-scratch

95
docs/zh_CN/get-started/linux-setup.rst
View file

@ -1 +1,94 @@
.. include:: ../../en/get-started/linux-setup.rst
*****************************
Linux 平台工具链的标准设置
*****************************
安装前提
=====================
编译 ESP-IDF 需要以下软件包：
- CentOS 7::
sudo yum install git wget make ncurses-devel flex bison gperf python pyserial
- Ubuntu and Debian::
sudo apt-get install git wget make libncurses-dev flex bison gperf python python-serial
- Arch::
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial
工具链的设置
===============
Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
- 64-bit Linux：
https://dl.espressif.com/dl/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
- 32-bit Linux：
https://dl.espressif.com/dl/xtensa-esp32-elf-linux32-1.22.0-80-g6c4433a-5.2.0.tar.gz
1. 下载完成后，将它解压到 ``~/esp`` 目录： ::
mkdir -p ~/esp
cd ~/esp
tar -xzf ~/Downloads/xtensa-esp32-elf-linux64-1.22.0-80-g6c4433a-5.2.0.tar.gz
.. _setup-linux-toolchain-add-it-to-path:
2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中： ::
export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"
或者你也可以给上面的命令创建一个别名。这样做的好处是，你只在需要使用它的时候才获取工具链。将下面这行代码添加到 ``~/.profile`` 文件中即可： ::
alias get_esp32='export PATH="$PATH:$HOME/esp/xtensa-esp32-elf/bin"'
然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
.. note::
如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile`` 。
3. 退出并重新登录以使 ``.profile`` 更改生效。 运行以下命令来检查 ``PATH`` 设置是否正确： ::
printenv PATH
检查一下字符串的末尾是否包含类似的工具链的路径： ::
$ printenv PATH
/home/user-name/bin:/home/user-name/.local/bin:/usr/local/sbin:/usr/local/bin:/usr/sbin:/usr/bin:/sbin:/bin:/usr/games:/usr/local/games:/snap/bin:/home/user-name/esp/xtensa-esp32-elf/bin
除了 ``/home/user-name``，应该有具体的安装的主路径。
权限问题 /dev/ttyUSB0
------------------------------
某些 Linux 版本可能在烧写 ESP32 时会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。 :ref:`可以通过将当前用户添加到拨出组来解决<linux-dialout-group>`。
Arch Linux 用户
----------------
在 Arch 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。在 AUR_ 中向下兼容的库文件，可用于本地和 lib32 的配置：
- https://aur.archlinux.org/packages/ncurses5-compat-libs/
- https://aur.archlinux.org/packages/lib32-ncurses5-compat-libs/
在安装这些软件包之前，你可能需要将作者的公钥添加到你的钥匙圈中，上面链接中的“Comments”部分有所叙述。
或者，你也可以使用 crosstool-NG 编译一个链接 ncurses 6 的 gdb。
后续步骤
==========
要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf` 一节。
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository

64
docs/zh_CN/get-started/windows-setup.rst
View file

@ -1 +1,63 @@
.. include:: ../../en/get-started/windows-setup.rst
***************************************
Windows 平台工具链的标准设置
***************************************
引言
============
Windows 没有内置的 "make" 环境，因此如果要安装工具链，你需要一个 GNU 兼容环境。我们这里使用 MSYS2_ 来提供该环境。你不需要一直使用这个环境（你可以使用 :doc:`Eclipse <eclipse-setup>` 或其它前端工具），但是它是在后台运行的。
工具链的设置
===============
快速设置的方法是从 dl.espressif.com 下载集成在一起的工具链和 MSYS2 压缩文件：
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20180110.zip
将 zip 压缩文件解压到 ``C:\`` (或其它路径，这里假设是 ``C:\``)，它会使用预先准备的环境创建一个 ``msys32`` 目录。
检出
============
运行 ``C:\msys32\mingw32.exe`` 打开一个 MSYS2 的终端窗口。该窗口的环境是一个 bash shell。
.. figure:: ../../_static/msys2-terminal-window.png
:align: center
:alt: MSYS2 MINGW32 shell window
:figclass: align-center
MSYS2 终端窗口
后续步骤将会使用这个窗口来为 ESP32 设置开发环境。
后续步骤
==========
要继续设置开发环境，请参考 :ref:`get-started-get-esp-idf` 一节。
更新环境
========================
当 IDF 更新时，有时需要新的工具链，或者将新的需求添加到 Windows MSYS2 环境中。要将旧版本的预编译环境中的数据移动到新版本：
- 把旧的 MSYS2 环境（即 ``C:\msys32``）移动/重命名为不同的目录（即 ``C:\msys32_old``）。
- 按照前文所述步骤下载新的预编译环境。
- 将新的 MSYS2 环境解压缩到 ``C:\msys32`` （或其他位置）。
- 找到旧的 ``C:\msys32_old\home`` 目录并把它移到 ``C:\msys32``。
- 如果你不再需要 ``C:\msys32_old`` 可以将它删除。
你可以在系统上拥有独立的不同的 MSYS2 环境，前提是在不同的目录中。
或者，:ref:`你也可以更新现有的环境而不是下载新环境 <updating-existing-windows-environment>`，但是这样更复杂。
相关文档
=================
.. toctree::
:maxdepth: 1
windows-setup-scratch
.. _MSYS2: https://msys2.github.io/

49
docs/zh_CN/index.rst
View file

@ -1 +1,48 @@
.. include:: ../en/index.rst
ESP-IDF Programming Guide
=========================
This is the documentation for Espressif IoT Development Framework (`esp-idf <https://github.com/espressif/esp-idf>`_). ESP-IDF is the official development framework for the `ESP32 <https://espressif.com/en/products/hardware/esp32/overview>`_ chip.
================== ================== ==================
|快速入门|_ |API Reference|_ |H/W Reference|_
------------------ ------------------ ------------------
`快速入门`_ `API Reference`_ `H/W Reference`_
------------------ ------------------ ------------------
|API Guides|_ |Contribute|_ |Resources|_
------------------ ------------------ ------------------
`API Guides`_ `Contribute`_ `Resources`_
================== ================== ==================
.. |快速入门| image:: ../_static/get-started.gif
.. _快速入门: get-started/index.html
.. |API Reference| image:: ../_static/api-reference.gif
.. _API Reference: api-reference/index.html
.. |H/W Reference| image:: ../_static/hw-reference.gif
.. _H/W Reference: hw-reference/index.html
.. |Api Guides| image:: ../_static/api-guides.gif
.. _Api Guides: api-guides/index.html
.. |Contribute| image:: ../_static/contribute.gif
.. _Contribute: contribute/index.html
.. |Resources| image:: ../_static/resources.gif
.. _Resources: resources.html
.. toctree::
:hidden:
快速入门 <get-started/index>
API Reference <api-reference/index>
H/W Reference <hw-reference/index>
API Guides <api-guides/index>
Contribute <contribute/index>
Resources <resources>
Copyrights <COPYRIGHT>
About <about>
* :ref:`genindex`