Merge branch 'master' into feature/esp32s2beta_merge
This commit is contained in:
Angus Gratton
Angus Gratton
63
docs/_static/diagrams/ring-buffer/ring_buffer_send_acquire_complete.diag
vendored
Normal file
63
docs/_static/diagrams/ring-buffer/ring_buffer_send_acquire_complete.diag
vendored
Normal file
@@ -0,0 +1,63 @@
|
||||
#Diagram demonstrating reading and returning an item in a No-Split/Allow-Split ring buffer
|
||||
#Buffer of 128 bytes, with 4 items of 16, 20, 8 and 24 bytes. First 3 items are read and returned
|
||||
|
||||
packetdiag ring_buffer_send_acquire_complete {
|
||||
node_width = 6
|
||||
node_height = 24
|
||||
default_fontsize = 12
|
||||
colwidth = 128
|
||||
|
||||
#Initial
|
||||
0-7: 8 [color = lightblue];
|
||||
8-23: 16 Available [color = lightyellow];
|
||||
24-127: Free
|
||||
|
||||
#Acquire item 1, 2, 3
|
||||
128-135: 8 [color = lightblue];
|
||||
136-151: 16 Available [color = lightyellow];
|
||||
152-179: 20 Acquired [color = lightgrey];
|
||||
180-195: 8 Acquired [color = lightgrey];
|
||||
196-227: 24 Acquired [color = lightgrey];
|
||||
228-255: 28 Free
|
||||
|
||||
#Complete item 2
|
||||
256-263: 8 [color = lightblue];
|
||||
264-279: 16 Available [color = lightyellow];
|
||||
280-307: 20 Acquired [color = lightgrey];
|
||||
308-315: 8 [color = pink];
|
||||
316-323: 8 Completed [color = pink];
|
||||
324-355: 24 Acquired [color = lightgrey];
|
||||
356-383: 28 Free
|
||||
|
||||
#Complete item 3
|
||||
384-391: 8 [color = lightblue];
|
||||
392-407: 16 Available [color = lightyellow];
|
||||
408-435: 20 Acquired [color = lightgrey];
|
||||
436-443: 8 [color = pink];
|
||||
444-451: 8 Completed [color = pink];
|
||||
452-459: 8 [color = pink];
|
||||
460-483: 24 Completed [color = pink];
|
||||
484-511: 28 Free
|
||||
|
||||
#Complete item 1
|
||||
512-519: 8 [color = lightblue];
|
||||
520-535: 16 Available [color = lightyellow];
|
||||
536-543: 8 [color = pink];
|
||||
544-563: 20 Completed [color = pink];
|
||||
564-571: 8 [color = pink];
|
||||
572-579: 8 Completed [color = pink];
|
||||
580-587: 8 [color = pink];
|
||||
588-611: 24 Completed [color = pink];
|
||||
612-639: 28 Free
|
||||
|
||||
#Return item 3
|
||||
640-647: 8 [color = lightblue];
|
||||
648-663: 16 Available [color = lightyellow];
|
||||
664-671: 8 [color = lightblue];
|
||||
672-691: 20 Available [color = lightyellow];
|
||||
692-699: 8 [color = lightblue];
|
||||
700-707: 8 Available [color = lightyellow];
|
||||
708-715: 8 [color = lightblue];
|
||||
716-739: 24 Available [color = lightyellow];
|
||||
740-767: 28 Free
|
||||
}
|
||||
@@ -1168,7 +1168,7 @@ can be used with CMake commands that support generator expressions.
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
idf_component_set_property(property val [APPEND])
|
||||
idf_component_set_property(component property val [APPEND])
|
||||
|
||||
Set a specified *component*'s :ref:`component property<cmake-component-properties>`, *property* with value *val*. Specifying *APPEND* will append the specified value to the current
|
||||
value of the property. If the property does not previously exist or it is currently empty, the specified value becomes
|
||||
|
||||
@@ -40,6 +40,8 @@ For easy interaction with IDF Monitor, use the keyboard shortcuts given in the t
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+H (or H) | Display all keyboard shortcuts | |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
| - Ctrl+X (or X) | Exit the program | |
|
||||
+-------------------+--------------------------------------------------------+------------------------------------------------------------------------------------------------------------------------------------------------------------------+
|
||||
|
||||
Any keys pressed, other than ``Ctrl-]`` and ``Ctrl-T``, will be sent through the serial port.
|
||||
|
||||
|
||||
@@ -23,14 +23,17 @@ Ring Buffers
|
||||
The ESP-IDF FreeRTOS ring buffer is a strictly FIFO buffer that supports arbitrarily sized items.
|
||||
Ring buffers are a more memory efficient alternative to FreeRTOS queues in situations where the
|
||||
size of items is variable. The capacity of a ring buffer is not measured by the number of items
|
||||
it can store, but rather by the amount of memory used for storing items. Items are sent to
|
||||
ring buffers by copy, however for efficiency reasons **items are retrieved by reference**. As a
|
||||
result, all retrieved items **must also be returned** in order for them to be removed from
|
||||
the ring buffer completely. The ring buffers are split into the three following types:
|
||||
it can store, but rather by the amount of memory used for storing items. You may apply for a
|
||||
piece of memory on the ring buffer to send an item, or just use the API to copy your data and send
|
||||
(according to the send API you call). For efficiency reasons,
|
||||
**items are always retrieved from the ring buffer by reference**. As a result, all retrieved
|
||||
items *must also be returned* in order for them to be removed from the ring buffer completely.
|
||||
The ring buffers are split into the three following types:
|
||||
|
||||
**No-Split** buffers will guarantee that an item is stored in contiguous memory and will not
|
||||
**No-Split** buffers will guarantee that an item is stored in contiguous memory and will not
|
||||
attempt to split an item under any circumstances. Use no-split buffers when items must occupy
|
||||
contiguous memory.
|
||||
contiguous memory. *Only this buffer type allows you getting the data item address and writting
|
||||
to the item by yourself.*
|
||||
|
||||
**Allow-Split** buffers will allow an item to be split when wrapping around if doing so will allow
|
||||
the item to be stored. Allow-split buffers are more memory efficient than no-split buffers but
|
||||
@@ -42,7 +45,8 @@ do not need to be maintained (e.g. a byte stream).
|
||||
|
||||
.. note::
|
||||
No-split/allow-split buffers will always store items at 32-bit aligned addresses. Therefore when
|
||||
retrieving an item, the item pointer is guaranteed to be 32-bit aligned.
|
||||
retrieving an item, the item pointer is guaranteed to be 32-bit aligned. This is useful
|
||||
especially when you need to send some data to the DMA.
|
||||
|
||||
.. note::
|
||||
Each item stored in no-split/allow-split buffers will **require an additional 8 bytes for a header**.
|
||||
@@ -76,6 +80,46 @@ and :cpp:func:`xRingbufferSend` to create a ring buffer then send an item to it.
|
||||
printf("Failed to send item\n");
|
||||
}
|
||||
|
||||
The following example demonstrates the usage of :cpp:func:`xRingbufferSendAcquire` and
|
||||
:cpp:func:`xRingbufferSendComplete` instead of :cpp:func:`xRingbufferSend` to apply for the
|
||||
memory on the ring buffer (of type `RINGBUF_TYPE_NOSPLIT`) and then send an item to it. This way
|
||||
adds one more step, but allows getting the address of the memory to write to, and writing to the
|
||||
memory yourself.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
#include "freertos/ringbuf.h"
|
||||
#include "soc/lldesc.h"
|
||||
|
||||
typedef struct {
|
||||
lldesc_t dma_desc;
|
||||
uint8_t buf[1];
|
||||
} dma_item_t;
|
||||
|
||||
#define DMA_ITEM_SIZE(N) (sizeof(lldesc_t)+(((N)+3)&(~3)))
|
||||
|
||||
...
|
||||
|
||||
//Retrieve space for DMA descriptor and corresponding data buffer
|
||||
//This has to be done with SendAcquire, or the address may be different when copy
|
||||
dma_item_t item;
|
||||
UBaseType_t res = xRingbufferSendAcquire(buf_handle,
|
||||
&item, DMA_ITEM_SIZE(buffer_size), pdMS_TO_TICKS(1000));
|
||||
if (res != pdTRUE) {
|
||||
printf("Failed to acquire memory for item\n");
|
||||
}
|
||||
item->dma_desc = (lldesc_t) {
|
||||
.size = buffer_size,
|
||||
.length = buffer_size,
|
||||
.eof = 0,
|
||||
.owner = 1,
|
||||
.buf = &item->buf,
|
||||
};
|
||||
//Actually send to the ring buffer for consumer to use
|
||||
res = xRingbufferSendComplete(buf_handle, &item);
|
||||
if (res != pdTRUE) {
|
||||
printf("Failed to send item\n");
|
||||
}
|
||||
|
||||
The following example demonstrates retrieving and returning an item from a **no-split ring buffer**
|
||||
using :cpp:func:`xRingbufferReceive` and :cpp:func:`vRingbufferReturnItem`
|
||||
@@ -83,7 +127,7 @@ using :cpp:func:`xRingbufferReceive` and :cpp:func:`vRingbufferReturnItem`
|
||||
.. code-block:: c
|
||||
|
||||
...
|
||||
|
||||
|
||||
//Receive an item from no-split ring buffer
|
||||
size_t item_size;
|
||||
char *item = (char *)xRingbufferReceive(buf_handle, &item_size, pdMS_TO_TICKS(1000));
|
||||
@@ -162,23 +206,23 @@ using :cpp:func:`xRingbufferReceiveUpTo` and :cpp:func:`vRingbufferReturnItem`
|
||||
|
||||
|
||||
For ISR safe versions of the functions used above, call :cpp:func:`xRingbufferSendFromISR`, :cpp:func:`xRingbufferReceiveFromISR`,
|
||||
:cpp:func:`xRingbufferReceiveSplitFromISR`, :cpp:func:`xRingbufferReceiveUpToFromISR`, and :cpp:func:`vRingbufferReturnItemFromISR`
|
||||
:cpp:func:`xRingbufferReceiveSplitFromISR`, :cpp:func:`xRingbufferReceiveUpToFromISR`, and :cpp:func:`vRingbufferReturnItemFromISR`
|
||||
|
||||
|
||||
Sending to Ring Buffer
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
The following diagrams illustrate the differences between no-split/allow-split buffers
|
||||
and byte buffers with regards to sending items/data. The diagrams assume that three
|
||||
The following diagrams illustrate the differences between no-split/allow-split buffers
|
||||
and byte buffers with regards to sending items/data. The diagrams assume that three
|
||||
items of sizes **18, 3, and 27 bytes** are sent respectively to a **buffer of 128 bytes**.
|
||||
|
||||
.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_send_non_byte_buf.diag
|
||||
:caption: Sending items to no-split/allow-split ring buffers
|
||||
:align: center
|
||||
|
||||
For no-split/allow-split buffers, a header of 8 bytes precedes every data item. Furthermore, the space
|
||||
For no-split/allow-split buffers, a header of 8 bytes precedes every data item. Furthermore, the space
|
||||
occupied by each item is **rounded up to the nearest 32-bit aligned size** in order to maintain overall
|
||||
32-bit alignment. However the true size of the item is recorded inside the header which will be
|
||||
32-bit alignment. However the true size of the item is recorded inside the header which will be
|
||||
returned when the item is retrieved.
|
||||
|
||||
Referring to the diagram above, the 18, 3, and 27 byte items are **rounded up to 20, 4, and 28 bytes**
|
||||
@@ -188,12 +232,42 @@ respectively. An 8 byte header is then added in front of each item.
|
||||
:caption: Sending items to byte buffers
|
||||
:align: center
|
||||
|
||||
Byte buffers treat data as a sequence of bytes and does not incur any overhead
|
||||
Byte buffers treat data as a sequence of bytes and does not incur any overhead
|
||||
(no headers). As a result, all data sent to a byte buffer is merged into a single item.
|
||||
|
||||
Referring to the diagram above, the 18, 3, and 27 byte items are sequentially written to the
|
||||
byte buffer and **merged into a single item of 48 bytes**.
|
||||
|
||||
Using SendAcquire and SendComplete
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
Items in no-split buffers are acquired (by SendAcquire) in strict FIFO order and must be sent to
|
||||
the buffer by SendComplete for the data to be accessible by the consumer. Multiple items can be
|
||||
sent or acquired without calling SendComplete, and the items do not necessarily need to be
|
||||
completed in the order they were acquired. However the receiving of data items must occur in FIFO
|
||||
order, therefore not calling SendComplete the earliest acquired item will prevent the subsequent
|
||||
items from being received.
|
||||
|
||||
The following diagrams illustrate what will happen when SendAcquire/SendComplete don't happen in
|
||||
the same order. At the beginning, there is already an data item of 16 bytes sent to the ring
|
||||
buffer. Then SendAcquire is called to acquire space of 20, 8, 24 bytes on the ring buffer.
|
||||
|
||||
.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_send_acquire_complete.diag
|
||||
:caption: SendAcquire/SendComplete items in no-split ring buffers
|
||||
:align: center
|
||||
|
||||
After that, we fill (use) the buffers, and send them to the ring buffer by SendComplete in the
|
||||
order of 8, 24, 20. When 8 bytes and 24 bytes data are sent, the consumer still can only get the
|
||||
16 bytes data item. Due to the usage if 20 bytes item is not complete, it's not available, nor
|
||||
the following data items.
|
||||
|
||||
When the 20 bytes item is finally completed, all the 3 data items can be received now, in the
|
||||
order of 20, 8, 24 bytes, right after the 16 bytes item existing in the buffer at the beginning.
|
||||
|
||||
Allow-split/byte buffers do not allow using SendAcquire/SendComplete since acquired buffers are
|
||||
required to be complete (not wrapped).
|
||||
|
||||
|
||||
Wrap around
|
||||
^^^^^^^^^^^
|
||||
|
||||
@@ -207,15 +281,15 @@ with **56 bytes of free space that wraps around** and a sent item of **28 bytes*
|
||||
|
||||
No-split buffers will **only store an item in continuous free space and will not split
|
||||
an item under any circumstances**. When the free space at the tail of the buffer is insufficient
|
||||
to completely store the item and its header, the free space at the tail will be **marked as dummy data**.
|
||||
to completely store the item and its header, the free space at the tail will be **marked as dummy data**.
|
||||
The buffer will then wrap around and store the item in the free space at the head of the buffer.
|
||||
|
||||
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is
|
||||
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is
|
||||
insufficient to store the 28 byte item. Therefore the 16 bytes is marked as dummy data and
|
||||
the item is written to the free space at the head of the buffer instead.
|
||||
|
||||
.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_allow_split.diag
|
||||
:caption: Wrap around in allow-split buffers
|
||||
:caption: Wrap around in allow-split buffers
|
||||
:align: center
|
||||
|
||||
Allow-split buffers will attempt to **split the item into two parts** when the free space at the tail
|
||||
@@ -232,17 +306,17 @@ as two parts to the buffer.
|
||||
parts of a split item in a thread safe manner.
|
||||
|
||||
.. packetdiag:: ../../../_static/diagrams/ring-buffer/ring_buffer_wrap_byte_buf.diag
|
||||
:caption: Wrap around in byte buffers
|
||||
:caption: Wrap around in byte buffers
|
||||
:align: center
|
||||
|
||||
Byte buffers will **store as much data as possible into the free space at the tail of buffer**. The remaining
|
||||
Byte buffers will **store as much data as possible into the free space at the tail of buffer**. The remaining
|
||||
data will then be stored in the free space at the head of the buffer. No overhead is incurred when wrapping
|
||||
around in byte buffers.
|
||||
|
||||
Referring to the diagram above, the 16 bytes of free space at the tail of the buffer is insufficient to
|
||||
completely store the 28 bytes of data. Therefore the 16 bytes of free space is filled with data, and the
|
||||
remaining 12 bytes are written to the free space at the head of the buffer. The buffer now contains
|
||||
data in two separate continuous parts, and each part continuous will be treated as a separate item by the
|
||||
data in two separate continuous parts, and each part continuous will be treated as a separate item by the
|
||||
byte buffer.
|
||||
|
||||
Retrieving/Returning
|
||||
@@ -255,10 +329,10 @@ byte buffers in retrieving and returning data.
|
||||
:caption: Retrieving/Returning items in no-split/allow-split ring buffers
|
||||
:align: center
|
||||
|
||||
Items in no-split/allow-split buffers are **retrieved in strict FIFO order** and **must be returned**
|
||||
for the occupied space to be freed. Multiple items can be retrieved before returning, and the items
|
||||
Items in no-split/allow-split buffers are **retrieved in strict FIFO order** and **must be returned**
|
||||
for the occupied space to be freed. Multiple items can be retrieved before returning, and the items
|
||||
do not necessarily need to be returned in the order they were retrieved. However the freeing of space
|
||||
must occur in FIFO order, therefore not returning the earliest retrieved item will prevent the space
|
||||
must occur in FIFO order, therefore not returning the earliest retrieved item will prevent the space
|
||||
of subsequent items from being freed.
|
||||
|
||||
Referring to the diagram above, the **16, 20, and 8 byte items are retrieved in FIFO order**. However the items
|
||||
@@ -270,13 +344,13 @@ are not returned in they were retrieved (20, 8, 16). As such, the space is not f
|
||||
:align: center
|
||||
|
||||
Byte buffers **do not allow multiple retrievals before returning** (every retrieval must be followed by a return
|
||||
before another retrieval is permitted). When using :cpp:func:`xRingbufferReceive` or
|
||||
before another retrieval is permitted). When using :cpp:func:`xRingbufferReceive` or
|
||||
:cpp:func:`xRingbufferReceiveFromISR`, all continuous stored data will be retrieved. :cpp:func:`xRingbufferReceiveUpTo`
|
||||
or :cpp:func:`xRingbufferReceiveUpToFromISR` can be used to restrict the maximum number of bytes retrieved. Since
|
||||
every retrieval must be followed by a return, the space will be freed as soon as the data is returned.
|
||||
|
||||
Referring to the diagram above, the 38 bytes of continuous stored data at the tail of the buffer is retrieved,
|
||||
returned, and freed. The next call to :cpp:func:`xRingbufferReceive` or :cpp:func:`xRingbufferReceiveFromISR`
|
||||
Referring to the diagram above, the 38 bytes of continuous stored data at the tail of the buffer is retrieved,
|
||||
returned, and freed. The next call to :cpp:func:`xRingbufferReceive` or :cpp:func:`xRingbufferReceiveFromISR`
|
||||
then wraps around and does the same to the 30 bytes of continuous stored data at the head of the buffer.
|
||||
|
||||
Ring Buffers with Queue Sets
|
||||
@@ -331,7 +405,7 @@ The :cpp:func:`xRingbufferCreateStatic` can be used to create ring buffers with
|
||||
- The ring buffer's data structure of type :cpp:type:`StaticRingbuffer_t`
|
||||
- The ring buffer's storage area of size ``xBufferSize``. Note that ``xBufferSize`` must be 32-bit aligned for no-split/allow-split buffers.
|
||||
|
||||
The manner in which these blocks are allocated will depend on the users requirements (e.g. all blocks being statically declared, or dynamically allocated with specific capabilities such as external RAM).
|
||||
The manner in which these blocks are allocated will depend on the users requirements (e.g. all blocks being statically declared, or dynamically allocated with specific capabilities such as external RAM).
|
||||
|
||||
.. note::
|
||||
The :ref:`CONFIG_FREERTOS_SUPPORT_STATIC_ALLOCATION` option must be enabled in `menuconfig` for statically allocated ring buffers to be available.
|
||||
@@ -375,20 +449,20 @@ Ring Buffer API Reference
|
||||
.. note::
|
||||
Ideally, ring buffers can be used with multiple tasks in an SMP fashion where the **highest
|
||||
priority task will always be serviced first.** However due to the usage of binary semaphores
|
||||
in the ring buffer's underlying implementation, priority inversion may occur under very
|
||||
in the ring buffer's underlying implementation, priority inversion may occur under very
|
||||
specific circumstances.
|
||||
|
||||
The ring buffer governs sending by a binary semaphore which is given whenever space is
|
||||
The ring buffer governs sending by a binary semaphore which is given whenever space is
|
||||
freed on the ring buffer. The highest priority task waiting to send will repeatedly take
|
||||
the semaphore until sufficient free space becomes available or until it times out. Ideally
|
||||
this should prevent any lower priority tasks from being serviced as the semaphore should
|
||||
always be given to the highest priority task.
|
||||
|
||||
However in between iterations of acquiring the semaphore, there is a **gap in the critical
|
||||
section** which may permit another task (on the other core or with an even higher priority) to
|
||||
section** which may permit another task (on the other core or with an even higher priority) to
|
||||
free some space on the ring buffer and as a result give the semaphore. Therefore the semaphore
|
||||
will be given before the highest priority task can re-acquire the semaphore. This will result
|
||||
in the **semaphore being acquired by the second highest priority task** waiting to send, hence
|
||||
in the **semaphore being acquired by the second highest priority task** waiting to send, hence
|
||||
causing priority inversion.
|
||||
|
||||
This side effect will not affect ring buffer performance drastically given if the number
|
||||
@@ -403,9 +477,9 @@ Ring Buffer API Reference
|
||||
Hooks
|
||||
-----
|
||||
|
||||
FreeRTOS consists of Idle Hooks and Tick Hooks which allow for application
|
||||
specific functionality to be added to the Idle Task and Tick Interrupt.
|
||||
ESP-IDF provides its own Idle and Tick Hook API in addition to the hooks
|
||||
FreeRTOS consists of Idle Hooks and Tick Hooks which allow for application
|
||||
specific functionality to be added to the Idle Task and Tick Interrupt.
|
||||
ESP-IDF provides its own Idle and Tick Hook API in addition to the hooks
|
||||
provided by Vanilla FreeRTOS. ESP-IDF hooks have the added benefit of
|
||||
being run time configurable and asymmetrical.
|
||||
|
||||
@@ -416,9 +490,9 @@ Idle and Tick Hooks in vanilla FreeRTOS are implemented by the user
|
||||
defining the functions ``vApplicationIdleHook()`` and ``vApplicationTickHook()``
|
||||
respectively somewhere in the application. Vanilla FreeRTOS will run the user
|
||||
defined Idle Hook and Tick Hook on every iteration of the Idle Task and Tick
|
||||
Interrupt respectively.
|
||||
Interrupt respectively.
|
||||
|
||||
Vanilla FreeRTOS hooks are referred to as **Legacy Hooks** in ESP-IDF FreeRTOS.
|
||||
Vanilla FreeRTOS hooks are referred to as **Legacy Hooks** in ESP-IDF FreeRTOS.
|
||||
To enable legacy hooks, :ref:`CONFIG_FREERTOS_LEGACY_HOOKS` should be enabled
|
||||
in :doc:`project configuration menu </api-reference/kconfig>`.
|
||||
|
||||
@@ -433,9 +507,9 @@ Due to the the dual core nature of the ESP32, it may be necessary for some
|
||||
applications to have separate hooks for each core. Furthermore, it may
|
||||
be necessary for the Idle Tasks or Tick Interrupts to execute multiple hooks
|
||||
that are configurable at run time. Therefore the ESP-IDF provides it's own hooks
|
||||
API in addition to the legacy hooks provided by Vanilla FreeRTOS.
|
||||
API in addition to the legacy hooks provided by Vanilla FreeRTOS.
|
||||
|
||||
The ESP-IDF tick/idle hooks are registered at run time, and each tick/idle hook
|
||||
The ESP-IDF tick/idle hooks are registered at run time, and each tick/idle hook
|
||||
must be registered to a specific CPU. When the idle task runs/tick Interrupt
|
||||
occurs on a particular CPU, the CPU will run each of its registered idle/tick hooks
|
||||
in turn.
|
||||
|
||||
@@ -2,7 +2,7 @@ Espressif IoT Development Framework Style Guide
|
||||
===============================================
|
||||
|
||||
|
||||
About this guide
|
||||
About This Guide
|
||||
----------------
|
||||
|
||||
Purpose of this style guide is to encourage use of common coding practices within the ESP-IDF.
|
||||
@@ -13,7 +13,7 @@ We try to keep rules simple enough, which means that they can not cover all pote
|
||||
|
||||
When doing modifications to third-party code used in ESP-IDF, follow the way that particular project is written. That will help propose useful changes for merging into upstream project.
|
||||
|
||||
C code formatting
|
||||
C Code Formatting
|
||||
-----------------
|
||||
|
||||
Indentation
|
||||
@@ -21,7 +21,7 @@ Indentation
|
||||
|
||||
Use 4 spaces for each indentation level. Don't use tabs for indentation. Configure the editor to emit 4 spaces each time you press tab key.
|
||||
|
||||
Vertical space
|
||||
Vertical Space
|
||||
^^^^^^^^^^^^^^
|
||||
|
||||
Place one empty line between functions. Don't begin or end a function with an empty line.
|
||||
@@ -43,7 +43,9 @@ Place one empty line between functions. Don't begin or end a function with an em
|
||||
}
|
||||
}
|
||||
|
||||
Horizontal space
|
||||
The maximum line length is 120 characters as long as it doesn't seriously affect the readability.
|
||||
|
||||
Horizontal Space
|
||||
^^^^^^^^^^^^^^^^
|
||||
|
||||
Always add single space after conditional and loop keywords::
|
||||
@@ -173,7 +175,7 @@ If you accidentally have some commits in your branch that add LF endings, you ca
|
||||
|
||||
For updating a single commit, it's possible to run ``dos2unix FILENAME`` and then run ``git commit --amend``
|
||||
|
||||
Formatting your code
|
||||
Formatting Your Code
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
You can use ``astyle`` program to format your code according to the above recommendations.
|
||||
@@ -185,6 +187,106 @@ To re-format a file, run::
|
||||
tools/format.sh components/my_component/file.c
|
||||
|
||||
|
||||
C++ Code Formatting
|
||||
-------------------
|
||||
|
||||
The same rules as for C apply. Where they are not enough, apply the following rules.
|
||||
|
||||
File Naming
|
||||
^^^^^^^^^^^^
|
||||
C++ Header files have the extension ``.h``. C++ source files have the extension ``.cpp``, which is important for the compiler to distiguish them from normal C source files.
|
||||
|
||||
Naming
|
||||
^^^^^^
|
||||
|
||||
* **Class and struct** names shall be written in ``CamelCase`` with a capital letter as beginning. Member variables and methods shall be in ``snake_case``.
|
||||
* **Namespaces** shall be in lower ``snake_case``.
|
||||
* **Templates** are specified in the line above the function declaration.
|
||||
|
||||
Member Order in Classes
|
||||
^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
First put the public members, then the protected, then private ones. Omit public, protected or private sections without any members.
|
||||
|
||||
Spacing
|
||||
^^^^^^^
|
||||
|
||||
* Don't indent inside namespaces.
|
||||
* Put ``public``, ``protected`` and ``private`` labels at the same indentation level as the corresponding ``class`` label.
|
||||
|
||||
Simple Example
|
||||
^^^^^^^^^^^^^^^
|
||||
::
|
||||
|
||||
// file spaceship.h
|
||||
#ifndef SPACESHIP_H_
|
||||
#define SPACESHIP_H_
|
||||
#include <cstdlib>
|
||||
|
||||
namespace spaceships {
|
||||
|
||||
class SpaceShip {
|
||||
public:
|
||||
SpaceShip(size_t crew);
|
||||
size_t get_crew_size() const;
|
||||
|
||||
private:
|
||||
const size_t crew;
|
||||
};
|
||||
|
||||
class SpaceShuttle : public SpaceShip {
|
||||
public:
|
||||
SpaceShuttle();
|
||||
};
|
||||
|
||||
class Sojuz : public SpaceShip {
|
||||
public:
|
||||
Sojuz();
|
||||
};
|
||||
|
||||
template <typename T>
|
||||
class CargoShip {
|
||||
public:
|
||||
CargoShip(const T &cargo);
|
||||
|
||||
private:
|
||||
T cargo;
|
||||
};
|
||||
|
||||
} // namespace spaceships
|
||||
|
||||
#endif // SPACESHIP_H_
|
||||
|
||||
// file spaceship.cpp
|
||||
#include "spaceship.h"
|
||||
|
||||
namespace spaceships {
|
||||
|
||||
// Putting the curly braces in the same line for constructors is OK if it only initializes
|
||||
// values in the initializer list
|
||||
SpaceShip::SpaceShip(size_t crew) : crew(crew) { }
|
||||
|
||||
size_t SpaceShip::get_crew_size() const
|
||||
{
|
||||
return crew;
|
||||
}
|
||||
|
||||
SpaceShuttle::SpaceShuttle() : SpaceShip(7)
|
||||
{
|
||||
// doing further initialization
|
||||
}
|
||||
|
||||
Sojuz::Sojuz() : SpaceShip(3)
|
||||
{
|
||||
// doing further initialization
|
||||
}
|
||||
|
||||
template <typename T>
|
||||
CargoShip<T>::CargoShip(const T &cargo) : cargo(cargo) { }
|
||||
|
||||
} // namespace spaceships
|
||||
|
||||
|
||||
CMake Code Style
|
||||
----------------
|
||||
|
||||
@@ -198,7 +300,7 @@ CMake Code Style
|
||||
- For globally scoped variables, use uppercase (``WITH_UNDERSCORES``).
|
||||
- Otherwise follow the defaults of the cmake-lint_ project.
|
||||
|
||||
Configuring the code style for a project using EditorConfig
|
||||
Configuring the Code Style for a Project Using EditorConfig
|
||||
-----------------------------------------------------------
|
||||
|
||||
EditorConfig helps developers define and maintain consistent coding styles between different editors and IDEs. The EditorConfig project consists of a file format for defining coding styles and a collection of text editor plugins that enable editors to read the file format and adhere to defined styles. EditorConfig files are easily readable and they work nicely with version control systems.
|
||||
@@ -206,7 +308,7 @@ EditorConfig helps developers define and maintain consistent coding styles betwe
|
||||
For more information, see `EditorConfig <http://editorconfig.org>`_ Website.
|
||||
|
||||
|
||||
Documenting code
|
||||
Documenting Code
|
||||
----------------
|
||||
|
||||
Please see the guide here: :doc:`documenting-code`.
|
||||
@@ -230,7 +332,7 @@ Structure
|
||||
To be written.
|
||||
|
||||
|
||||
Language features
|
||||
Language Features
|
||||
-----------------
|
||||
|
||||
To be written.
|
||||
|
||||
@@ -20,6 +20,10 @@ https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611
|
||||
|
||||
Unzip the zip file to ``C:\`` (or some other location, but this guide assumes ``C:\``) and it will create an ``msys32`` directory with a pre-prepared environment.
|
||||
|
||||
.. important::
|
||||
|
||||
If another toolchain location is used (different than the default `C:\msys32`), please ensure that the path where the all-in-one toolchain gets unzipped is a plain ASCII, contains no spaces, symlinks or accents.
|
||||
|
||||
|
||||
Check it Out
|
||||
============
|
||||
|
||||
@@ -1,3 +0,0 @@
|
||||
:orphan:
|
||||
|
||||
.. Remove this file when the Chinese translation of getting started guide is updated
|
||||
@@ -1,73 +0,0 @@
|
||||
在用户配置文件中添加 IDF_PATH 和 idf.py PATH
|
||||
==========================================================================================================
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
|
||||
使用基于 CMake 的构建系统和 idf.py 工具，用户需修改两处系统环境变量：
|
||||
|
||||
- ``IDF_PATH`` 需设置为含有 ESP-IDF 目录的路径
|
||||
- 系统 ``PATH`` 变量需包括含有 ``idf.py`` 工具 （属于 ESP-IDF 一部分）的目录
|
||||
|
||||
为确保系统重启后仍保存之前的变量设置，请参照以下说明将变量设置添加到用户配置文件中。
|
||||
|
||||
.. note:: 使用 IDE 工具的情况下，你可以选择在 IDE 项目环境中设置环境变量，而不使用如下命令行。
|
||||
|
||||
.. note:: 如果你从未用过 ``idf.py`` 命令行工具，而是直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``PATH`` 变量，只需设置 ``IDF_PATH`` 变量。不过，你也可以两个都设置。
|
||||
|
||||
.. note:: 如果你只用过 ``idf.py`` 命令行工具，从未直接运行 cmake 或通过 IDE 工具运行 cmake，则无需设置 ``IDF_PATH`` 变量。``idf.py`` 会搜索自身包含的目录，如果没有发现 ``IDF_PATH``，则会自行进行有关设置。
|
||||
|
||||
.. _add-paths-to-profile-windows:
|
||||
|
||||
Windows 操作系统
|
||||
-----------------------------------
|
||||
|
||||
在 Windows 10 操作系统下设置环境变量，用户应在开始菜单下搜索 "Edit Environment Variables"。
|
||||
|
||||
在较早版本的 Windows 操作系统下设置环境变量，用户应打开系统控制面板，选择“高级”，找到环境变量按钮。
|
||||
|
||||
你可以为本台电脑上的“所有用户”或“当前用户”设置环境变量，这取决于其他用户是否也需要使用 ESP-IDF。
|
||||
|
||||
- 点击 ``New...`` （新建...） 添加名为 ``IDF_PATH`` 的新系统变量，具体设置为包含 ESP-IDF 的目录，例如，``C:\Users\user-name\esp\esp-idf``。
|
||||
- 找到 ``Path`` 环境变量，双击进行编辑。在末尾添加 ``;%IDF_PATH%\tools``，这样你就可以通过 Windows 命令窗口运行 ``idf.py`` 等其他工具了。
|
||||
|
||||
如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。
|
||||
|
||||
|
||||
.. _add-idf_path-to-profile-linux-macos:
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
------------------------------------
|
||||
|
||||
要设置 ``IDF_PATH``，并在 PATH 中添加 ``idf.py``，请将以下两行代码添加至你的 ``~/.profile`` 文件中::
|
||||
|
||||
export IDF_PATH=~/esp/esp-idf
|
||||
export PATH="$IDF_PATH/tools:$PATH"
|
||||
|
||||
.. note::
|
||||
|
||||
``~/.profile`` 表示在你的电脑用户主目录中，后缀为 ``.profile`` 的文件。(``~`` 为 shell 中的缩写)。
|
||||
|
||||
请退出，并重新登录使更改生效。
|
||||
|
||||
.. note::
|
||||
|
||||
并非所有 shell 都使用 ``.profile``，但是如果同时存在 ``/bin/bash`` 和 ``.bash_profile``，请更新此配置文件。如果存在 ``zsh``，请更新 ``.zprofile``。其他 shell 可能使用其他配置文件（详询有关 shell 的文档）。
|
||||
|
||||
运行以下命令来检查 ``IDF_PATH`` 设置是否正确::
|
||||
|
||||
printenv IDF_PATH
|
||||
|
||||
此处应打印出此前在 ``~/.profile`` 文件中输入（或手动设置）的路径。
|
||||
|
||||
为确认 ``idf.py`` 目前是否在 ``PATH`` 中，你可以运行以下命令::
|
||||
|
||||
which idf.py
|
||||
|
||||
这里，应打印出类似 ``${IDF_PATH}/tools/idf.py`` 的路径。
|
||||
|
||||
如果不想修改 ``IDF_PATH`` 或 ``PATH``，你可以在每次重启或退出后在终端中手动输入::
|
||||
|
||||
export IDF_PATH=~/esp/esp-idf
|
||||
export PATH="$IDF_PATH/tools:$PATH"
|
||||
|
||||
如果你在安装 ESP32 硬件开发的软件环境时，从 :ref:`get-started-setup-path` 小节跳到了这里，请返回 :ref:`get-started-start-project` 小节开始阅读。
|
||||
@@ -4,6 +4,8 @@ Eclipse IDE 创建和烧录指南
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
有关基于 CMake-based 构建系统和 Eclipse CDT，进行 Eclipse 设置的相关文档即将发布。
|
||||
ESP-IDF V4.0 将默认采用基于 CMake 的编译系统。
|
||||
|
||||
.. _eclipse.org: https://www.eclipse.org/
|
||||
对此，我们还推出了针对 CMake 编译系统的新 ESP-IDF Eclipse 插件。具体操作，请见 `ESP-IDF Eclipse 插件 <https://github.com/espressif/idf-eclipse-plugin/blob/master/README.md>`。
|
||||
|
||||
如您仍需要对传统 GNU Make 编译系统的 Eclipse 支持，请前往 :doc:`传统 GNU Make 编译系统入门指南 </get-started-legacy/index>`，查看 :doc:`使用 Eclipse IDE 进行编译与烧录 </get-started-legacy/eclipse-setup>` 章节。
|
||||
@@ -1,22 +1,20 @@
|
||||
*******************
|
||||
快速入门（CMake）
|
||||
*******************
|
||||
***********
|
||||
快速入门
|
||||
***********
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，
|
||||
|
||||
通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。
|
||||
本文档旨在指导用户搭建 ESP32 硬件开发的软件环境，通过一个简单的示例展示如何使用 ESP-IDF (Espressif IoT Development Framework) 配置菜单，并编译、下载固件至 ESP32 开发板等步骤。
|
||||
|
||||
.. include:: /_build/inc/version-note.inc
|
||||
|
||||
概述
|
||||
====
|
||||
============
|
||||
|
||||
ESP32 SoC 芯片支持以下功能：
|
||||
|
||||
* 2.4 GHz Wi-Fi
|
||||
* 蓝牙 4.2 标准
|
||||
* 蓝牙 4.2
|
||||
* 高性能双核
|
||||
* 超低功耗协处理器
|
||||
* 多种外设
|
||||
@@ -26,18 +24,18 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
||||
乐鑫为用户提供完整的软、硬件资源，进行 ESP32 硬件设备的开发。其中，乐鑫的软件开发环境 ESP-IDF 旨在协助用户快速开发物联网 (IoT) 应用，可满足用户对 Wi-Fi、蓝牙、低功耗等方面的要求。
|
||||
|
||||
准备工作
|
||||
========
|
||||
=============
|
||||
|
||||
硬件：
|
||||
|
||||
* 一款 **ESP32** 开发板
|
||||
* **USB 数据线** （USB A/Micro USB B）
|
||||
* **USB 数据线** (A 转 Micro-B)
|
||||
* PC（Windows、Linux 或 Mac OS）
|
||||
|
||||
软件：
|
||||
|
||||
* 设置 **工具链**，用于编译 ESP32 代码；
|
||||
* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**；
|
||||
* **编译工具** —— CMake 和 Ninja 编译工具，用于编译 ESP32 **应用程序**；
|
||||
* 获取 **ESP-IDF** 软件开发框架。该框架已经基本包含 ESP32 使用的 API（软件库和源代码）和运行 **工具链** 的脚本；
|
||||
* 安装 C 语言编程（**工程**）的 **文本编辑器**，例如 `Eclipse <https://www.eclipse.org/>`_。
|
||||
|
||||
@@ -51,7 +49,7 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
||||
|
||||
|
||||
开发板简介
|
||||
==========
|
||||
===========================
|
||||
|
||||
请点击下方连接，了解有关具体开发板的详细信息。
|
||||
|
||||
@@ -67,17 +65,17 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
||||
.. _get-started-step-by-step:
|
||||
|
||||
详细安装步骤
|
||||
==============
|
||||
=========================
|
||||
|
||||
请根据下方详细步骤，完成安装过程。
|
||||
|
||||
设置开发环境
|
||||
~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
* :ref:`get-started-setup-toolchain`
|
||||
* :ref:`get-started-get-prerequisites` （:doc:`Windows <windows-setup>` 、:doc:`Linux <linux-setup>` 和 :doc:`macOS <macos-setup>`）
|
||||
* :ref:`get-started-get-esp-idf`
|
||||
* :ref:`get-started-setup-path`
|
||||
* :ref:`get-started-get-packages`
|
||||
* :ref:`get-started-set-up-tools`
|
||||
* :ref:`get-started-set-up-env`
|
||||
|
||||
创建您的第一个工程
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
@@ -90,14 +88,12 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
||||
* :ref:`get-started-build-monitor`
|
||||
|
||||
|
||||
.. _get-started-setup-toolchain:
|
||||
.. _get-started-get-prerequisites:
|
||||
|
||||
第一步：设置工具链
|
||||
====================
|
||||
第一步：安装准备
|
||||
=============================
|
||||
|
||||
工具链指一套用于编译代码和应用程序的程序。
|
||||
|
||||
为了加快开发进度，您可以直接使用乐鑫提供的预制工具链。请根据您的操作系统，点击下方对应的链接，并按照链接中的指导进行安装。
|
||||
在正式开始创建工程前，请先完成工具的安装，具体步骤见下：
|
||||
|
||||
.. toctree::
|
||||
:hidden:
|
||||
@@ -125,27 +121,22 @@ ESP32 采用 40 nm 工艺制成，具有最佳的功耗性能、射频性能、
|
||||
.. _Linux: ../get-started/linux-setup.html
|
||||
.. _Mac OS: ../get-started/macos-setup.html
|
||||
|
||||
.. _get-started-get-esp-idf:
|
||||
|
||||
|
||||
第二步：获取 ESP-IDF
|
||||
=================================
|
||||
|
||||
在围绕 ESP32 构建应用程序之前，请先获取乐鑫提供的软件库文件 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
|
||||
|
||||
获取 ESP-IDF 的本地副本：打开终端，切换到您要保存 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。针对不同操作系统的详细步骤，请见下文。
|
||||
|
||||
.. note::
|
||||
|
||||
在本文档中，Linux 和 MacOS 操作系统中 ESP-IDF 的默认安装路径为 ``~/esp``；Windows 操作系统的默认路径为 ``%userprofile%\esp``。您也可以将 ESP-IDF 安装在任何其他路径下，但请注意在使用命令行时进行相应替换。注意，ESP-IDF 不支持带有空格的路径。
|
||||
|
||||
此外， 您也可以根据自身经验和实际需求，对环境进行个性化设置，而非使用预制工具链。此时，请前往 :ref:`工具链的个性化设置<get-started-customized-setup>` 章节获取更多信息。
|
||||
|
||||
|
||||
.. _get-started-get-esp-idf:
|
||||
.. _get-started-set-up-tools:
|
||||
|
||||
第二步：获取 ESP-IDF
|
||||
===========================
|
||||
|
||||
除了工具链，您还需要供 ESP32 使用的 API（软件库和源代码），具体请见 `ESP-IDF 仓库 <https://github.com/espressif/esp-idf>`_。
|
||||
|
||||
请将 ESP-IDF 下载到您的本地。
|
||||
|
||||
获取本地副本：打开终端，切换到你要存放 ESP-IDF 的工作目录，使用 ``git clone`` 命令克隆远程仓库。
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
打开终端，后运行以下命令：
|
||||
|
||||
@@ -156,71 +147,103 @@ ESP-IDF 将下载至 ``~/esp/esp-idf``。
|
||||
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
|
||||
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
|
||||
较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
|
||||
|
||||
请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
|
||||
|
||||
打开命令提示符，后运行以下命令：
|
||||
|
||||
.. include:: /_build/inc/git-clone-windows.inc
|
||||
|
||||
ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
|
||||
除了安装必要工具外，第一步中介绍的 :ref:`get-started-windows-tools-installer` 也能同时下载 ESP-IDF 本地副本。
|
||||
|
||||
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
|
||||
|
||||
.. include:: /_build/inc/git-clone-notes.inc
|
||||
除了使用 ESP-IDF 工具安装器，您也可以参考 :ref:`指南 <get-esp-idf-windows-command-line>` 手动下载 ESP-IDF。
|
||||
|
||||
.. note::
|
||||
.. _get-started-set-up-tools:
|
||||
|
||||
在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块： ::
|
||||
|
||||
cd esp-idf
|
||||
git submodule update --init
|
||||
|
||||
.. _get-started-setup-path:
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
第三步：设置环境变量
|
||||
===========================
|
||||
|
||||
请在您的 PC 上设置以下环境变量，否则无法编译工程。
|
||||
|
||||
- ``IDF_PATH`` 应设置为 ESP-IDF 根目录的路径。
|
||||
- ``PATH`` 应包括同一 ``IDF_PATH`` 目录下的 ``tools`` 目录路径。
|
||||
|
||||
您可以在每次重启会话时手动设置，也可以在用户配置中进行永久设置，具体请前往 :doc:`add-idf_path-to-profile` 章节，查看 :ref:`Windows <add-paths-to-profile-windows>` 、:ref:`Linux 及 MacOS <add-idf_path-to-profile-linux-macos>` 操作系统的具体设置方式。
|
||||
|
||||
|
||||
.. _get-started-get-packages:
|
||||
|
||||
第四步：安装 Python 软件包
|
||||
第三步：设置工具
|
||||
=================================
|
||||
|
||||
ESP-IDF 所需的 Python 软件包位于 ``IDF_PATH/requirements.txt`` 中。您可以运行以下命令进行安装： ::
|
||||
除了 ESP-IDF 本身，您还需要安装 ESP-IDF 使用的各种工具，比如编译器、调试器、Python 包等。
|
||||
|
||||
python -m pip install --user -r $IDF_PATH/requirements.txt
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. note::
|
||||
请根据第一步中对 Windows (:ref:`get-started-windows-tools-installer`) 的介绍，安装所有必需工具。
|
||||
|
||||
请注意查询您所使用的 Python 解释器的版本（运行命令 ``python --version``），并根据查询结果将上方命令中的 ``python`` 替换为 ``python2``, ``python2.7``，例如：
|
||||
除了使用 ESP-IDF 工具安装器，您也可以通过 **命令提示符** 窗口手动安装这些工具。具体步骤见下：
|
||||
|
||||
``python2.7 -m pip install --user -r $IDF_PATH/requirements.txt``
|
||||
.. code-block:: batch
|
||||
|
||||
cd %userprofile%\esp\esp-idf
|
||||
install.bat
|
||||
|
||||
或使用 Windows PowerShell
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
cd ~/esp/esp-idf
|
||||
./install.ps1
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp/esp-idf
|
||||
./install.sh
|
||||
|
||||
自定义工具安装路径
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
本步骤中介绍的脚本将 ESP-IDF 所需的编译工具默认安装在用户根文件夹中，即 Linux 和 MacOS 系统中的 ``$HOME/.espressif`` 和 Windows 系统的 ``%USERPROFILE%\.espressif``。此外，您可以可以将工具安装到其他目录中，但请在运行安装脚本前，重新设置环境变量 ``IDF_TOOLS_PATH``。注意，请确保您的用户已经具备了读写该路径的权限。
|
||||
|
||||
如果修改了 ``IDF_TOOLS_PATH`` 变量，请确保该变量在每次执行“安装脚本” (``install.bat``、``install.ps1`` 或 ``install.sh``) 和导出脚本 (``export.bat``、``export.ps1`` 或 ``export.sh``) 均保持一致。
|
||||
|
||||
.. _get-started-set-up-env:
|
||||
|
||||
第四步：设置环境变量
|
||||
=======================================
|
||||
|
||||
此时，您刚刚安装的工具尚未添加至 PATH 环境变量，无法通过“命令窗口”使用这些工具。因此，必须设置一些环境变量，这可以通过 ESP-IDF 提供的另一个脚本完成。
|
||||
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
Windows 安装器（:ref:`get-started-windows-tools-installer` ）可在“开始”菜单创建一个 "ESP-IDF Command Prompt" 快捷方式。该快捷方式可以打开命令提示符窗口，并设置所有环境变量。您可以点击该快捷方式，然后继续下一步。
|
||||
|
||||
此外，如果您希望在当下命令提示符窗口使用 ESP-IDF，请使用下方代码：
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
%userprofile%\esp\esp-idf\export.bat
|
||||
|
||||
或使用 Windows PowerShell
|
||||
|
||||
.. code-block:: powershell
|
||||
|
||||
.$HOME/esp/esp-idf/export.ps1
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
请在您需要运行 ESP-IDF 的“命令提示符”窗口运行以下命令：
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
. $HOME/esp/esp-idf/export.sh
|
||||
|
||||
注意，命令开始的 "." 与路径之间应有一个空格！
|
||||
|
||||
此外，您也可以将这行代码增加至您的 ``.profile`` 或 ``.bash_profile`` 脚本中，这样您就可以在任何命令窗口使用 ESP-IDF 工具了。
|
||||
|
||||
.. _get-started-start-project:
|
||||
|
||||
第五步：开始创建工程
|
||||
=======================
|
||||
========================================
|
||||
|
||||
现在，您可以开始准备开发 ESP32 应用程序了。您可以从 ESP-IDF 中 :idf:`examples` 目录下的 :example:`get-started/hello_world` 工程开始。
|
||||
|
||||
将 :example:`get-started/hello_world` 复制至您本地的 ``~/esp`` 目录下：
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
@@ -228,7 +251,7 @@ Linux 和 MacOS 操作系统
|
||||
cp -r $IDF_PATH/examples/get-started/hello_world .
|
||||
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
@@ -244,7 +267,7 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
|
||||
.. _get-started-connect:
|
||||
|
||||
第六步：连接设备
|
||||
======================
|
||||
==========================================
|
||||
|
||||
现在，请将您的 ESP32 开发板连接到 PC，并查看开发板使用的串口。
|
||||
|
||||
@@ -264,34 +287,28 @@ ESP-IDF 的 :idf:`examples` 目录下有一系列示例工程，都可以按照
|
||||
.. _get-started-configure:
|
||||
|
||||
第七步：配置
|
||||
=================
|
||||
=========================
|
||||
|
||||
请进入 :ref:`get-started-start-project` 中提到的 ``hello_world`` 目录，并运行工程配置工具 ``menuconfig``。
|
||||
|
||||
Linux 和 MacOS 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: bash
|
||||
|
||||
cd ~/esp/hello_world
|
||||
idf.py menuconfig
|
||||
|
||||
如果您的默认 Python 版本为 3.0 以上，可能需要运行 ``python2 idf.py`` 。
|
||||
如果您的默认 Python 版本为 3.0 及以上，可能需要运行 ``python2 $(which idf.py) menuconfig``。
|
||||
|
||||
Windows 操作系统
|
||||
~~~~~~~~~~~~~~~~~~~~~
|
||||
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~
|
||||
|
||||
.. code-block:: batch
|
||||
|
||||
cd %userprofile%\esp\hello_world
|
||||
idf.py menuconfig
|
||||
|
||||
Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2 关联起来。如果其他程序（比如 Visual Studio Python 工具）曾关联了其他版本 Python，则 ``idf.py`` 可能无法正常运行（文件将在 Visual Studio 中打开）。这种情况下，您可以选择每次都运行一遍 ``C:\Python27\python idf.py``，或更改 Windows 的 ``.py`` 关联文件设置。
|
||||
|
||||
.. note::
|
||||
|
||||
如果出现 ``idf.py not found（无法找到 idf.py）`` 错误，请确保 ``PATH`` 环境变量设置无误，具体请参考 :ref:`get-started-setup-path`。如果 ``tools`` 目录下没有 ``idf.py`` 文件，请确保 CMake 预览的分支正确无误，具体请参考 :ref:`get-started-get-esp-idf`。
|
||||
|
||||
如果之前的步骤都正确，则会显示下面的菜单：
|
||||
|
||||
.. figure:: ../../_static/project-configuration.png
|
||||
@@ -299,17 +316,17 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
:alt: 工程配置 — 主窗口
|
||||
:figclass: align-center
|
||||
|
||||
工程配置 — 主窗口
|
||||
工程配置 — 主窗口
|
||||
|
||||
``menuconfig`` 工具的常见操作见下。
|
||||
|
||||
* ``上下箭头``：移动
|
||||
* 上下箭头：移动
|
||||
* ``回车``：进入子菜单
|
||||
* ``ESC 键``：返回上级菜单或退出
|
||||
* ``英文问号``：调出帮助菜单（退出帮助菜单，请按回车键）。
|
||||
* ``空格``、``Y 键``或``N 键``：使能/禁用 ``[*]`` 配置选项
|
||||
* ``英文问号``：调出有关高亮选项的帮助菜单
|
||||
* ``/ 键``：寻找配置项目
|
||||
* ``空格``或 ``Y 键``：选择 ``[*]`` 配置选项；``N 键``：禁用 ``[*]`` 配置选项
|
||||
* ``英文问号`` （查询配置选项）：调出有关该选项的帮助菜单
|
||||
* ``/ 键``：寻找配置工程
|
||||
|
||||
.. attention::
|
||||
|
||||
@@ -318,7 +335,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
.. _get-started-build:
|
||||
|
||||
第八步：编译工程
|
||||
==================
|
||||
=========================
|
||||
|
||||
请使用以下命令，编译烧录工程：::
|
||||
|
||||
@@ -328,23 +345,23 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
|
||||
.. code-block:: none
|
||||
|
||||
$ idf.py build
|
||||
Running cmake in directory /path/to/hello_world/build
|
||||
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
|
||||
Warn about uninitialized values.
|
||||
-- Found Git: /usr/bin/git (found version "2.17.0")
|
||||
-- Building empty aws_iot component due to configuration
|
||||
-- Component names: ...
|
||||
-- Component paths: ...
|
||||
|
||||
... (more lines of build system output)
|
||||
|
||||
[527/527] Generating hello-world.bin
|
||||
esptool.py v2.3.1
|
||||
|
||||
Project build complete. To flash, run this command:
|
||||
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
|
||||
or run 'idf.py -p PORT flash'
|
||||
$ idf.py build
|
||||
Running cmake in directory /path/to/hello_world/build
|
||||
Executing "cmake -G Ninja --warn-uninitialized /path/to/hello_world"...
|
||||
Warn about uninitialized values.
|
||||
-- Found Git:/usr/bin/git (found version "2.17.0")
|
||||
-- Building empty aws_iot component due to configuration
|
||||
-- Component names: ...
|
||||
-- Component paths: ...
|
||||
|
||||
... (more lines of build system output)
|
||||
|
||||
[527/527] Generating hello-world.bin
|
||||
esptool.py v2.3.1
|
||||
|
||||
Project build complete. To flash, run this command:
|
||||
../../../components/esptool_py/esptool/esptool.py -p (PORT) -b 921600 write_flash --flash_mode dio --flash_size detect --flash_freq 40m 0x10000 build/hello-world.bin build 0x1000 build/bootloader/bootloader.bin 0x8000 build/partition_table/partition-table.bin
|
||||
or run 'idf.py -p PORT flash'
|
||||
|
||||
如果一切正常，编译完成后将生成 .bin 文件。
|
||||
|
||||
@@ -352,15 +369,15 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
.. _get-started-flash:
|
||||
|
||||
第九步：烧录到设备
|
||||
====================
|
||||
=============================
|
||||
|
||||
请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板： ::
|
||||
请使用以下命令，将刚刚生成的二进制文件烧录至您的 ESP32 开发板：
|
||||
|
||||
idf.py -p PORT [-b BAUD] flash
|
||||
``idf.py -p PORT [-b BAUD] flash``
|
||||
|
||||
请将 PORT 替换为 ESP32 开发板的串口名称，具体可见 :ref:`get-started-connect`。
|
||||
|
||||
您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
|
||||
您还可以将 BAUD 替换为您希望的烧录波特率。默认波特率为 ``460800``。
|
||||
|
||||
更多有关 idf.py 参数的详情，请见 :ref:`idf.py`。
|
||||
|
||||
@@ -409,11 +426,11 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
.. _get-started-build-monitor:
|
||||
|
||||
第十步：监视器
|
||||
==================
|
||||
======================
|
||||
|
||||
您可以使用 ``make monitor`` 命令，监视 “hello_world” 的运行情况。注意，不要忘记将 PORT 替换为您的串口名称。
|
||||
|
||||
运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动： ::
|
||||
运行该命令后，:doc:`IDF 监视器 <../api-guides/tools/idf-monitor>` 应用程序将启动：::
|
||||
|
||||
$ idf.py -p /dev/ttyUSB0 monitor
|
||||
Running idf_monitor in directory [...]/esp/hello_world/build
|
||||
@@ -440,17 +457,17 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
|
||||
您可使用快捷键 ``Ctrl+]``，退出 IDF 监视器。
|
||||
|
||||
如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板选用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。
|
||||
如果 IDF 监视器在烧录后很快发生错误，或打印信息全是乱码（见下），很有可能是因为您的开发板采用了 26 MHz 晶振，而 ESP-IDF 默认支持大多数开发板使用的 40 MHz 晶振。
|
||||
|
||||
.. figure:: ../../_static/get-started-garbled-output.png
|
||||
:align: center
|
||||
:alt: 乱码输出
|
||||
:figclass: align-center
|
||||
|
||||
此时，请您：
|
||||
此时，您可以：
|
||||
|
||||
1. 退出监视器。
|
||||
2. 打开 :ref:`menuconfig <get-started-configure>`，
|
||||
2. 打开 :ref:`menuconfig <get-started-configure>`。
|
||||
3. 进入 ``Component config`` --> ``ESP32-specific`` --> ``Main XTAL frequency`` 进行配置，将 :ref:`CONFIG_ESP32_XTAL_FREQ_SEL` 设置为 26 MHz。
|
||||
4. 然后，请重新 :ref:`编译和烧录 <get-started-flash>` 应用程序。
|
||||
|
||||
@@ -458,7 +475,7 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
|
||||
您也可以运行以下命令，一次性执行构建、烧录和监视过程：
|
||||
|
||||
``idf.py -p PORT flash monitor``
|
||||
``idf.py -p PORT flash monitor``
|
||||
|
||||
此外，
|
||||
|
||||
@@ -470,21 +487,22 @@ Python 2.7 安装程序将尝试配置 Windows，将 ``.py`` 文件与 Python 2
|
||||
现在，您可以尝试一些其他 :idf:`examples`，或者直接开发自己的应用程序。
|
||||
|
||||
更新 ESP-IDF
|
||||
=================
|
||||
================
|
||||
|
||||
乐鑫会不时推出更新版本的 ESP-IDF，修复 bug 或提出新的特性。因此，您在使用时，也应注意更新您本地的版本。最简单的方法是：直接删除您本地的 ``esp-idf`` 文件夹，然后按照 :ref:`get-started-get-esp-idf` 中的指示，重新完成克隆。
|
||||
|
||||
如果您希望将 ESP-IDF 克隆到新的路径下，请务必 :doc:`重新设置 IDF_PATH <add-idf_path-to-profile>`。否则，工具链将无法找到 ESP-IDF。
|
||||
|
||||
此外，您可以仅更新变更部分。具体方式，请前往 :ref:`更新 <updating>` 章节查看。
|
||||
|
||||
注意，更新完成后，请执行 ``install.sh`` （Windows 系统中为 ``install.bat``）脚本，避免新版 ESP-IDF 所需的工具也有所更新。具体请参考 :ref:`get-started-set-up-tools`。
|
||||
|
||||
一旦重新安装好工具，请使用“导出脚本”更新环境，具体请参考 :ref:`get-started-set-up-env`。
|
||||
|
||||
相关文档
|
||||
===========
|
||||
=================
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
|
||||
add-idf_path-to-profile
|
||||
establish-serial-connection
|
||||
eclipse-setup
|
||||
../api-guides/tools/idf-monitor
|
||||
|
||||
@@ -4,7 +4,7 @@
|
||||
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从乐鑫官网直接下载已编译好的二进制工具链外，你还可以按照本文介绍，从头开始设置你自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
|
||||
除了从乐鑫官网直接下载已编译好的二进制工具链外，您还可以按照本文介绍，从头开始设置自己的工具链。如需快速使用已编译好的二进制工具链，可回到 :doc:`linux-setup` 章节。
|
||||
|
||||
安装准备
|
||||
=====================
|
||||
@@ -23,39 +23,38 @@
|
||||
|
||||
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
|
||||
|
||||
|
||||
.. note::
|
||||
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
|
||||
|
||||
从源代码编译工具链
|
||||
=================================
|
||||
|
||||
- 安装依赖：
|
||||
安装依赖项：
|
||||
|
||||
- CentOS 7::
|
||||
- CentOS 7::
|
||||
|
||||
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
|
||||
sudo yum install gawk gperf grep gettext ncurses-devel python python-devel automake bison flex texinfo help2man libtool make
|
||||
|
||||
- Ubuntu pre-16.04::
|
||||
- Ubuntu pre-16.04::
|
||||
|
||||
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
|
||||
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool make
|
||||
|
||||
- Ubuntu 16.04 及以上::
|
||||
- Ubuntu 16.04 或以上 ::
|
||||
|
||||
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
|
||||
sudo apt-get install gawk gperf grep gettext python python-dev automake bison flex texinfo help2man libtool libtool-bin make
|
||||
|
||||
- Debian 9::
|
||||
- Debian 9::
|
||||
|
||||
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
|
||||
sudo apt-get install gawk gperf grep gettext libncurses-dev python python-dev automake bison flex texinfo help2man libtool libtool-bin make
|
||||
|
||||
- Arch::
|
||||
- Arch::
|
||||
|
||||
TODO
|
||||
TODO
|
||||
|
||||
创建工作目录，并进入该目录::
|
||||
|
||||
mkdir -p ~/esp
|
||||
cd ~/esp
|
||||
mkdir -p ~/esp
|
||||
cd ~/esp
|
||||
|
||||
下载并编译 ``crosstool-NG`` ：
|
||||
|
||||
@@ -67,7 +66,7 @@
|
||||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-esp32-elf
|
||||
|
||||
编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path>` 的介绍，将工具链添加到 ``PATH``。
|
||||
编译得到的工具链会被保存到 ``~/esp/crosstool-NG/builds/xtensa-esp32-elf``。请按照 :ref:`标准设置指南 <setup-linux-toolchain-add-it-to-path-legacy>` 的介绍，将工具链添加到 ``PATH``。
|
||||
|
||||
|
||||
后续步骤
|
||||
|
||||
@@ -1,10 +1,10 @@
|
||||
*******************************************************************
|
||||
*********************************************
|
||||
Linux 平台工具链的标准设置
|
||||
*******************************************************************
|
||||
*********************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装前提
|
||||
安装准备
|
||||
=====================
|
||||
|
||||
编译 ESP-IDF 需要以下软件包：
|
||||
@@ -15,94 +15,41 @@ Linux 平台工具链的标准设置
|
||||
|
||||
- Ubuntu 和 Debian::
|
||||
|
||||
sudo apt-get install git wget libncurses-dev flex bison gperf python python-click python-pip python-setuptools python-serial python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
|
||||
sudo apt-get install git wget libncurses-dev flex bison gperf python python-pip python-setuptools python-serial python-click python-cryptography python-future python-pyparsing python-pyelftools cmake ninja-build ccache
|
||||
|
||||
- Arch::
|
||||
|
||||
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
|
||||
sudo pacman -S --needed gcc git make ncurses flex bison gperf python2-pip python2-pyserial python2-click python2-cryptography python2-future python2-pyparsing python2-pyelftools cmake ninja ccache
|
||||
|
||||
.. note::
|
||||
使用 ESP-IDF 需要 CMake 3.5 或以上版本。较早版本的 Linux 可能需要升级才能向后移植仓库，或安装 "cmake3" 软件包，而不是安装 "cmake"。
|
||||
|
||||
工具链的设置
|
||||
=========================
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
Linux 版的 ESP32 工具链可以从 Espressif 的网站下载：
|
||||
|
||||
- 64 位 Linux：
|
||||
|
||||
|download_link_linux64|
|
||||
|
||||
- 32 位 Linux：
|
||||
|
||||
|download_link_linux32|
|
||||
|
||||
1. 下载完成后，将它解压到 ``~/esp`` 目录：
|
||||
|
||||
- for 64-bit Linux:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-linux64.inc
|
||||
|
||||
- for 32-bit Linux:
|
||||
|
||||
.. include:: /_build/inc/unpack-code-linux32.inc
|
||||
|
||||
.. _setup-linux-toolchain-add-it-to-path:
|
||||
|
||||
2. 工具链将会被解压到 ``~/esp/xtensa-esp32-elf/`` 目录。
|
||||
|
||||
要使用工具链，你还需要在 ``~/.profile`` 文件中更新环境变量 ``PATH``。要使 ``xtensa-esp32-elf`` 在所有的终端会话中都有效，需要将下面这一行代码添加到你的 ``~/.profile`` 文件中：::
|
||||
|
||||
export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"
|
||||
|
||||
或者，你也可以给上面的命令创建一个别名。这样做的好处是，你仅在需要时才获取工具链，将下面这行代码添加到 ``~/.profile`` 文件中即可::
|
||||
|
||||
alias get_esp32='export PATH="$HOME/esp/xtensa-esp32-elf/bin:$PATH"'
|
||||
|
||||
然后，当你需要使用工具链时，在命令行输入 ``get_esp32``，然后工具链会自动添加到你的 ``PATH`` 中。
|
||||
|
||||
.. note::
|
||||
|
||||
如果将 ``/bin/bash`` 设置为登录 shell，且同时存在 ``.bash_profile`` 和 ``.profile``，则更新 ``.bash_profile``。
|
||||
|
||||
3. 退出并重新登录以使 ``.profile`` 更改生效。运行以下命令来检查 ``PATH`` 设置是否正确::
|
||||
|
||||
printenv PATH
|
||||
|
||||
检查字符串的开头是否包含类似的工具链路径::
|
||||
|
||||
$ printenv PATH
|
||||
/home/user-name/esp/xtensa-esp32-elf/bin:/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``，应该有具体的安装的主路径。
|
||||
|
||||
其他提示
|
||||
===============
|
||||
|
||||
权限问题 /dev/ttyUSB0
|
||||
----------------------------------------------
|
||||
------------------------------------------------------------
|
||||
|
||||
使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group>`
|
||||
使用某些 Linux 版本向 ESP32 烧写固件时，可能会出现 ``Failed to open port /dev/ttyUSB0`` 错误消息。此时，可以将当前用户增加至 :ref:` Linux Dialout 组 <linux-dialout-group>`。
|
||||
|
||||
Arch Linux 用户
|
||||
--------------------------------
|
||||
ncurses 5 依赖项
|
||||
--------------------
|
||||
|
||||
在 Arch Linux 中运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但是 Arch 使用的是 ncurses 6。
|
||||
在 Linux 上运行预编译的 gdb (xtensa-esp32-elf-gdb) 需要 ncurses 5，但一些较新版本默认只提供 ncurses 6。
|
||||
|
||||
`AUR`_ 中存在向下兼容的库文件，可用于本地和 lib32 的配置：
|
||||
请查看对应版本信息，确认是否存在可用的 ncurses 5。此外，您也可以使用 crosstool-NG 编译一个链接到 ncurses 6 的 gdb。
|
||||
|
||||
Arch Linux 用户可在 AUR_ 中获得 native 和 lib32 配置的 ncurses 5 库：
|
||||
|
||||
- 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` 一节。
|
||||
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
|
||||
|
||||
|
||||
相关文档
|
||||
@@ -115,3 +62,4 @@ Arch Linux 用户
|
||||
|
||||
|
||||
.. _AUR: https://wiki.archlinux.org/index.php/Arch_User_Repository
|
||||
|
||||
|
||||
@@ -1,86 +1,87 @@
|
||||
*********************************************************************
|
||||
从零开始设置 Mac OS 环境下的工具链
|
||||
*********************************************************************
|
||||
***********************************************
|
||||
从零开始设置 MacOS 环境下的工具链
|
||||
***********************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
软件包管理器
|
||||
======================
|
||||
===============
|
||||
|
||||
从零开始设置工具链，你需要安装 MacPorts_ 或 homebrew_ 包管理器。或者，你也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
|
||||
从零开始设置工具链，您需要安装 MacPorts_ 或 homebrew_ 软件包管理器。或者，您也可以直接 :doc:`下载预编译的工具链 <macos-setup>`。
|
||||
|
||||
MacPorts_ 需要安装完整的 XCode 软件，而 homebrew_ 只需要安装 XCode 命令行工具即可。
|
||||
MacPorts 需要完整的 XCode 软件，而 homebrew 只需要安装 XCode 命令行工具即可。
|
||||
|
||||
.. _homebrew: https://brew.sh/
|
||||
.. _MacPorts: https://www.macports.org/install.php
|
||||
.. _homebrew: https://brew.sh/
|
||||
.. _MacPorts: https://www.macports.org/install.php
|
||||
|
||||
请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看在哪些情景下需要从头开始设置工具链。
|
||||
请参考 :ref:`工具链自定义设置 <get-started-customized-setup>` 章节，查看可能需要从头开始设置工具链的情况。
|
||||
|
||||
准备工作
|
||||
============================
|
||||
安装准备
|
||||
=====================
|
||||
|
||||
- 安装 pip::
|
||||
|
||||
sudo easy_install pip
|
||||
sudo easy_install pip
|
||||
|
||||
- 安装 pyserial::
|
||||
|
||||
pip install --user pyserial
|
||||
pip install --user pyserial
|
||||
|
||||
- 安装 CMake 和 Ninja 编译工具：
|
||||
|
||||
- 若使用 HomeBrew，你可以运行::
|
||||
- 若有 HomeBrew，您可以运行::
|
||||
|
||||
brew install cmake ninja
|
||||
brew install cmake ninja
|
||||
|
||||
- 若使用 MacPorts，你可以运行::
|
||||
- 若有 MacPorts，您可以运行::
|
||||
|
||||
sudo port install cmake ninja
|
||||
sudo port install cmake ninja
|
||||
|
||||
从源代码编译工具链
|
||||
========================================
|
||||
=================================
|
||||
|
||||
- 相关安装：
|
||||
安装依赖项：
|
||||
|
||||
- 对于 MacPorts::
|
||||
- 对于 MacPorts::
|
||||
|
||||
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
|
||||
sudo port install gsed gawk binutils gperf grep gettext wget libtool autoconf automake make
|
||||
|
||||
- 对于 homebrew::
|
||||
- 对于 homebrew::
|
||||
|
||||
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
|
||||
brew install gnu-sed gawk binutils gperftools gettext wget help2man libtool autoconf automake make
|
||||
|
||||
创建一个文件系统镜像（区分大小写）::
|
||||
|
||||
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
|
||||
hdiutil create ~/esp/crosstool.dmg -volname "ctng" -size 10g -fs "Case-sensitive HFS+"
|
||||
|
||||
挂载::
|
||||
|
||||
hdiutil mount ~/esp/crosstool.dmg
|
||||
hdiutil mount ~/esp/crosstool.dmg
|
||||
|
||||
创建指向你工作目录的符号链接::
|
||||
创建指向您工作目录的符号链接::
|
||||
|
||||
mkdir -p ~/esp
|
||||
ln -s /Volumes/ctng ~/esp/ctng-volume
|
||||
mkdir -p ~/esp
|
||||
ln -s /Volumes/ctng ~/esp/ctng-volume
|
||||
|
||||
前往新创建的目录：::
|
||||
前往新创建的目录 ::
|
||||
|
||||
cd ~/esp/ctng-volume
|
||||
cd ~/esp/ctng-volume
|
||||
|
||||
下载 ``crosstool-NG``，并开始编译：
|
||||
下载并编译 ``crosstool-NG``
|
||||
|
||||
.. include:: /_build/inc/scratch-build-code.inc
|
||||
|
||||
编译工具链：::
|
||||
编译工具链::
|
||||
|
||||
./ct-ng xtensa-esp32-elf
|
||||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-esp32-elf
|
||||
./ct-ng xtensa-esp32-elf
|
||||
./ct-ng build
|
||||
chmod -R u+w builds/xtensa-esp32-elf
|
||||
|
||||
编译后的工具链将保存在 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。根据 :ref:`Mac OS 下设置环境变量的标准方法 <setup-macos-toolchain-add-it-to-path>` 中的介绍，将工具链添加到 ``PATH`` 中。
|
||||
编译得到的工具链会被保存到 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf``。使用工具链前，请将 ``~/esp/ctng-volume/crosstool-NG/builds/xtensa-esp32-elf/bin`` 添加至 ``PATH`` 环境变量。
|
||||
|
||||
|
||||
后续步骤
|
||||
=================
|
||||
==========
|
||||
|
||||
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
|
||||
|
||||
继续设置开发环境，请前往 :ref:`获取 ESP-IDF <get-started-get-esp-idf>` 章节。
|
||||
|
||||
@@ -1,8 +1,8 @@
|
||||
******************************************************************
|
||||
在 Mac OS 上安装 ESP32 工具链
|
||||
******************************************************************
|
||||
**********************************************
|
||||
MacOS 平台工具链的标准设置
|
||||
**********************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
安装准备
|
||||
=====================
|
||||
@@ -19,64 +19,30 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
|
||||
|
||||
- 安装 CMake 和 Ninja 编译工具：
|
||||
|
||||
- 若有 HomeBrew_，你可以运行::
|
||||
- 若有 HomeBrew_，您可以运行::
|
||||
|
||||
brew install cmake ninja
|
||||
brew install cmake ninja
|
||||
|
||||
- 若有 MacPorts_，你可以运行::
|
||||
- 若有 MacPorts_，您可以运行::
|
||||
|
||||
sudo port install cmake ninja
|
||||
sudo port install cmake ninja
|
||||
|
||||
- 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。
|
||||
- 若以上均不适用，请访问 CMake_ 和 Ninja_ 主页，查询有关 Mac OS 平台的下载安装问题。
|
||||
|
||||
- 强烈建议同时安装 ccache_ 以达到更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
|
||||
- 强烈建议同时安装 ccache_ 以获得更快的编译速度。如有 HomeBrew_，可通过 MacPorts_ 上的 ``brew install ccache`` 或 ``sudo port install ccache`` 完成安装。
|
||||
|
||||
.. note::
|
||||
|
||||
如您在上述任何步骤中遇到以下错误::
|
||||
|
||||
如在任一步骤中出现以下报错信息::
|
||||
|
||||
``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at: /Library/Developer/CommandLineTools/usr/bin/xcrun``
|
||||
|
||||
你需要安装 XCode 命令行工具才能继续，具体可运行 ``xcode-select --install`` 进行安装。
|
||||
|
||||
安装工具链
|
||||
======================
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
下载 MacOS 版本的 ESP32 工具链，请前往乐鑫官网：
|
||||
|
||||
|download_link_osx|
|
||||
|
||||
完成下载后，请在 ``~/esp`` 目录下进行解压：
|
||||
|
||||
.. include:: /_build/inc/unpack-code-osx.inc
|
||||
|
||||
.. _setup-macos-toolchain-add-it-to-path:
|
||||
|
||||
此后，该工具链将解压至 ``~/esp/xtensa-esp32-elf/`` 目录。
|
||||
|
||||
为了开始使用工具链，你必须更新 ``~/.profile`` 文件中的 ``PATH`` 环境变量。为了让所有终端都可以使用 ``xtensa-esp32-elf``，请将下方命令增加至你的 ``~/.profile`` 文件：::
|
||||
|
||||
export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH
|
||||
|
||||
此外，你可以为以上命令增加一个别名。这样，你就可以仅在有需要时获取工具链。具体方式是在 ``~/.profile`` 文件中增加下方命令::
|
||||
|
||||
alias get_esp32="export PATH=$HOME/esp/xtensa-esp32-elf/bin:$PATH"
|
||||
|
||||
此时，你可以直接输入 ``get_esp32`` 命令，即可将工具链添加至你的 ``PATH``。
|
||||
|
||||
注意，这里需要退出并重新登陆，``.profile`` 更改才会生效。
|
||||
|
||||
此外，你可以使用以下命令，验证 ``PATH`` 是否设置正确::
|
||||
|
||||
printenv PATH
|
||||
``xcrun: error: invalid active developer path (/Library/Developer/CommandLineTools), missing xcrun at:/Library/Developer/CommandLineTools/usr/bin/xcrun``
|
||||
|
||||
则必须安装 XCode 命令行工具，具体可运行 ``xcode-select --install``。
|
||||
|
||||
后续步骤
|
||||
=================
|
||||
==========
|
||||
|
||||
前往 :ref:`get-started-get-esp-idf`，完成接下来的开发环境配置。
|
||||
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
|
||||
|
||||
相关文档
|
||||
=================
|
||||
@@ -91,3 +57,4 @@ ESP-IDF 将使用 Mac OS 上默认安装的 Python 版本。
|
||||
.. _ccache: https://ccache.samba.org/
|
||||
.. _homebrew: https://brew.sh/
|
||||
.. _MacPorts: https://www.macports.org/install.php
|
||||
|
||||
|
||||
@@ -1,17 +1,17 @@
|
||||
.. _get-started-customized-setup:
|
||||
|
||||
*********************************************************
|
||||
工具链自定义设置
|
||||
*********************************************************
|
||||
*************************************
|
||||
工具链的自定义设置
|
||||
*************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
除了从乐鑫官网（请见 :ref:`get-started-setup-toolchain`）下载二进制工具链外，你还可以自行编译工具链。
|
||||
除了从乐鑫官网（请见 :ref:`get-started-set-up-tools`）下载二进制工具链外，您还可以自行编译工具链。
|
||||
|
||||
如果没有特别需求，建议直接使用我们提供的预编译二进制工具链。不过，你也可能也会由于以下原因，编译你自己的工具链：
|
||||
如无特殊需求，建议直接使用我们提供的预编译二进制工具链。不过，您可以在以下情况考虑自行编译工具链：
|
||||
|
||||
- 需要定制工具链编译配置
|
||||
- 使用其他 GCC 版本（如 4.8.5）
|
||||
- 需要使用其他 GCC 版本（如 4.8.5）
|
||||
- 需要破解 gcc、newlib 或 libstdc++
|
||||
- 有相关兴趣或时间充裕
|
||||
- 不信任从网站下载的 bin 文件
|
||||
@@ -19,9 +19,10 @@
|
||||
如需自行编译工具链，请查看以下文档：
|
||||
|
||||
.. toctree::
|
||||
:maxdepth: 1
|
||||
:maxdepth: 1
|
||||
|
||||
windows-setup-scratch
|
||||
linux-setup-scratch
|
||||
macos-setup-scratch
|
||||
|
||||
windows-setup-scratch
|
||||
linux-setup-scratch
|
||||
macos-setup-scratch
|
||||
|
||||
|
||||
@@ -1,72 +1,99 @@
|
||||
******************************************************************
|
||||
********************************************
|
||||
从零开始设置 Windows 环境下的工具链
|
||||
******************************************************************
|
||||
********************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
本文就如何运行基于 CMake 构建系统中的 :doc:`ESP-IDF 工具安装器 <windows-setup>` 进行逐步详细说明。手动安装所有工具能更好地控制整个安装流程，同时也方便高阶用户进行自定义安装。
|
||||
除了使用 :doc:`ESP-IDF 工具安装器 <windows-setup>`，用户也可以手动设置 Windows 环境下的工具链，这也是本文的主要内容。手动安装工具可以更好地控制安装流程，同时也方便高阶用户进行自定义安装。
|
||||
|
||||
使用 ESP-IDF 工具安装器对工具链及其他工具进行快速标准设置，请参照 :doc:`windows-setup`。
|
||||
|
||||
.. note::
|
||||
基于 GNU Make 的构建系统要求 Windows 兼容 MSYS2_ Unix，基于 CMake 的构建系统则无此要求。
|
||||
|
||||
.. _get-esp-idf-windows-command-line:
|
||||
|
||||
获取 ESP-IDF
|
||||
=================
|
||||
|
||||
.. note::
|
||||
基于 GNU Make 的构建系统要求 Windows 兼容 `MSYS2`_ Unix。基于 CMake 的构建系统则无此要求。
|
||||
|
||||
较早版本 ESP-IDF 使用了 **MSYS2 bash 终端** 命令行。目前，基于 CMake 的编译系统可使用常见的 **Windows 命令窗口**，即本指南中使用的终端。
|
||||
|
||||
请注意，如果您使用基于 bash 的终端或 PowerShell 终端，一些命令语法将与下面描述有所不同。
|
||||
|
||||
打开命令提示符，运行以下命令：
|
||||
|
||||
.. include:: /_build/inc/git-clone-windows.inc
|
||||
|
||||
ESP-IDF 将下载至 ``%userprofile%\esp\esp-idf``。
|
||||
|
||||
请前往 :doc:`/versions`，查看 ESP-IDF 不同版本的具体适用场景。
|
||||
|
||||
.. include:: /_build/inc/git-clone-notes.inc
|
||||
|
||||
.. note::
|
||||
|
||||
在克隆远程仓库时，不要忘记加上 ``--recursive`` 选项。否则，请接着运行以下命令，获取所有子模块 ::
|
||||
|
||||
cd esp-idf
|
||||
git submodule update --init
|
||||
|
||||
|
||||
工具
|
||||
=====
|
||||
|
||||
cmake
|
||||
^^^^^
|
||||
cmake 工具
|
||||
^^^^^^^^^^
|
||||
|
||||
下载最新发布的 Windows 平台稳定版 `CMake`_，并运行安装器。
|
||||
|
||||
当安装器询问安装选项时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
|
||||
当安装器询问“安装选项”时，选择 "Add CMake to the system PATH for all users"（为所有用户的系统路径添加 CMake）或 "Add CMake to the system PATH for the current user"（为当前用户的系统路径添加 CMake）。
|
||||
|
||||
Ninja 编译工具
|
||||
^^^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
.. note::
|
||||
Ninja 目前仅为 64 位版本 Windows 提供 bin 文件。你也可以通过其他编译工具使用 CMake 和 ``idf.py``，如适用于 32 位 Windows 的 mingw-make，但是目前暂无关于此工具的说明文档。
|
||||
目前，Ninja 仅提供支持 64 位 Windows 版本的 bin 文件。您也可以配合其他编译工具在 32 位 Windows 版本中使用 CMake 和 ``idf.py`` ，比如 mingw-make。但是目前暂无关于此工具的说明文档。
|
||||
|
||||
从（`下载页面 <ninja-dl>`_）下载最新发布的 Windows 平台稳定版 `ninja`_。
|
||||
从（`下载页面 <ninja-dl_>`_）下载最新发布的 Windows 平台稳定版 ninja_。
|
||||
|
||||
适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。将其解压到目录，并 `添加到你的路径 <add-directory-windows-path>`_ （或者选择你的路径中已有的目录）。
|
||||
适用于 Windows 平台的 Ninja 下载文件是一个 .zip 文件，包含一个 ``ninja.exe`` 文件。您需要将该文件解压到目录，并 :ref:`添加到您的路径 <add-directory-windows-path>` （或者选择您路径中的已有目录）。
|
||||
|
||||
|
||||
Python 2.x
|
||||
^^^^^^^^^^
|
||||
|
||||
下载并运行适用于 Windows 安装器的最新版 `Python`_ 2.7。
|
||||
下载并运行适用于 Windows 安装器的最新版 Python_ 2.7。
|
||||
|
||||
Python 安装的“自定义”那一步提供了一份选项列表，最后一个选项是 "Add python.exe to Path"（添加 python.exe 到路径中），更改该选项，选择 "Will be installed"（将会安装）。
|
||||
Python 安装器的“自定义”菜单可为您提供一系列选项，最后一项为 "Add python.exe to Path"（添加 python.exe 到路径中）。请将该选项更改到 "Will be installed"（将会安装）。
|
||||
|
||||
Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并运行以下命令::
|
||||
Python 安装完成后，从 Windows 开始菜单中打开“命令提示符”窗口，并运行以下命令::
|
||||
|
||||
pip install --user pyserial
|
||||
pip install --user pyserial
|
||||
|
||||
适用于 IDF 的 MConf
|
||||
^^^^^^^^^^^^^^^^^^^^^^
|
||||
^^^^^^^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
从 `kconfig-frontends 发布页面 <mconf-idf>`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行一些自定义操作。
|
||||
从 `kconfig-frontends releases page`_ 下载配置工具 mconf-idf。此为 ``mconf`` 配置工具，可针对 ESP-IDF 进行少量自定义操作。
|
||||
|
||||
你需将此工具解压到目录，然后 `添加到你的路径 <add-directory-windows-path>`_。
|
||||
请将此工具解压到目录，并 :ref:`添加到您的路径 <add-directory-windows-path>`。
|
||||
|
||||
工具链设置
|
||||
===============
|
||||
|
||||
.. include:: /_build/inc/download-links.inc
|
||||
|
||||
下载预编译的 Windows 平台工具链：
|
||||
下载预编译的 Windows 工具链：
|
||||
|
||||
|download_link_win32|
|
||||
|
||||
解压压缩包文件到 ``C:\Program Files`` （或其他地址）。压缩包文件包含 ``xtensa-esp32-elf`` 目录。
|
||||
解压压缩包文件到 ``C:\Program Files`` （或其他位置）。压缩包文件包含一个 ``xtensa-esp32-elf`` 目录。
|
||||
|
||||
然后，须将该目录下的子目录 ``bin`` `添加到你的路径 <add-directory-windows-path>`_。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
|
||||
然后，请将该目录下的 ``bin`` 子目录 :ref:`添加到您的路径 <add-directory-windows-path>`。例如，``C:\Program Files\xtensa-esp32-elf\bin``。
|
||||
|
||||
.. note::
|
||||
|
||||
如果你已安装 MSYS2 环境（适用 "GNU Make" 构建系统），你可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
|
||||
如果您已安装 MSYS2 环境（适用 "GNU Make" 编译系统），则可以跳过下载那一步，直接添加目录 ``C:\msys32\opt\xtensa-esp32-elf\bin`` 到路径，因为 MSYS2 环境已包含工具链。
|
||||
|
||||
|
||||
.. _add-directory-windows-path:
|
||||
@@ -74,19 +101,24 @@ Python 安装完成后，打开 Windows 开始菜单下的 Command Prompt，并
|
||||
添加目录到路径
|
||||
========================
|
||||
|
||||
添加任何新目录到你的 Windows Path 环境变量：
|
||||
在 Windows 环境下，向 Path 环境变量增加任何新目录，请：
|
||||
|
||||
打开系统控制面板，找到环境变量对话框（对于 Windows 10，则在高级系统设置中查找对话框）。
|
||||
打开系统“控制面板”，找到环境变量对话框（Windows 10 用户请前往“高级系统设置”）。
|
||||
|
||||
双击 ``Path`` 变量（选择用户或系统路径，这取决于你是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
|
||||
双击 ``Path`` 变量（选择“用户”或“系统路径”，具体取决于您是否希望其他用户路径中也存在该目录)。在最后数值那里新添 ``;<new value>``。
|
||||
|
||||
|
||||
后续步骤
|
||||
================
|
||||
==========
|
||||
|
||||
要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
|
||||
继续设置开发环境，请前往 :ref:`get-started-get-esp-idf` 章节。
|
||||
|
||||
.. _cmake: https://cmake.org/download/
|
||||
.. _ninja: https://ninja-build.org/
|
||||
.. _ninja-dl: https://github.com/ninja-build/ninja/releases
|
||||
.. _Python: https://www.python.org/downloads/windows/
|
||||
.. _MSYS2: https://msys2.github.io/
|
||||
.. _kconfig-frontends releases page: https://github.com/espressif/kconfig-frontends/releases
|
||||
.. _Stable version: https://docs.espressif.com/projects/esp-idf/zh_CN/stable/
|
||||
|
||||
|
||||
|
||||
@@ -1,3 +1,41 @@
|
||||
:orphan:
|
||||
*************************************************
|
||||
在 Windows 环境下更新 ESP-IDF 工具
|
||||
*************************************************
|
||||
|
||||
.. _get-started-install_bat-windows:
|
||||
|
||||
使用脚本安装 ESP-IDF 工具
|
||||
====================================
|
||||
|
||||
请从 Windows “命令提示符”窗口，切换至 ESP-IDF 的安装目录。然后运行::
|
||||
|
||||
install.bat
|
||||
|
||||
对于 Powershell，请切换至 ESP-IDF 的安装目录。然后运行::
|
||||
|
||||
install.ps1
|
||||
|
||||
该命令可下载安装 ESP-IDF 所需的工具。如您已经安装了某个版本的工具，则该命令将无效。
|
||||
该工具的下载安装位置由 ESP-IDF 工具安装器的设置决定，默认情况下为： ``C:\Users\username\.espressif``。
|
||||
|
||||
.. _get-started-export_bat-windows:
|
||||
|
||||
使用“导出脚本”将 ESP-IDF 工具添加至 PATH
|
||||
=================================================================================
|
||||
|
||||
ESP-IDF 工具安装器将在“开始菜单”为 “ESP-IDF 命令提示符” 创建快捷方式。点击该快捷方式可打开 Windows 命令提示符窗口，您可在该窗口使用所有已安装的工具。
|
||||
|
||||
有些情况下，您正在使用的 ESP-IDF 版本可能并未创建命令提示符快捷方式，此时您可以根据下方步骤将 ESP-IDF 工具添加至 PATH。
|
||||
|
||||
首先，请打开需要使用 ESP-IDF 的命令提示符窗口，切换至 ESP-IDF 的安装路径，然后执行 ``export.bat``::
|
||||
|
||||
cd %userprofile%\esp\esp-idf
|
||||
export.bat
|
||||
|
||||
对于 Powershell 用户，请同样切换至 ESP-IDF 的安装路径，然后执行 ``export.ps1``::
|
||||
|
||||
cd ~/esp/esp-idf
|
||||
export.ps1
|
||||
|
||||
运行完成后，您就可以通过命令提示符使用 ESP-IDF 工具了。
|
||||
|
||||
.. Remove this file when the Chinese translation of getting started guide is updated
|
||||
|
||||
@@ -1,54 +1,52 @@
|
||||
**********************************************************
|
||||
***********************************************
|
||||
Windows 平台工具链的标准设置
|
||||
**********************************************************
|
||||
***********************************************
|
||||
|
||||
:link_to_translation:`en:[英文]`
|
||||
:link_to_translation:`en:[English]`
|
||||
|
||||
.. note::
|
||||
基于 CMake 的构建系统仅支持 64 位版本 Windows。
|
||||
目前，基于 CMake 的构建系统仅支持 64 位 Windows 版本。32 位 Windows 版本的用户可根据 :doc:`传统 GNU Make 构建系统<../get-started-legacy/windows-setup>` 中的介绍进行操作。
|
||||
|
||||
引言
|
||||
概述
|
||||
============
|
||||
|
||||
ESP-IDF 需要安装必要的工具，以编译 ESP32 固件，包括：Git，交叉编译器，以及 CMake 构建工具。本文将对这些工具一一说明。
|
||||
ESP-IDF 需要安装一些必备工具，才能围绕 ESP32 构建固件，包括 Python、Git、交叉编译器、menuconfig 工具、CMake和 Ninja 编译工具等。
|
||||
|
||||
在此入门指南中，我们通过命令提示符进行有关操作。不过，安装 ESP-IDF 后你还可以使用 :doc:`Eclipse <eclipse-setup>` 或支持 CMake 的图形化工具 IDE。
|
||||
在本入门指南中，我们通过 **命令提示符** 进行有关操作。不过，您在安装 ESP-IDF 后还可以使用 :doc:`Eclipse <eclipse-setup>` 或其他支持 CMake 的图形化工具 IDE。
|
||||
|
||||
https://dl.espressif.com/dl/esp32_win32_msys2_environment_and_toolchain-20190611.zip
|
||||
.. note::
|
||||
较早 ESP-IDF 版本使用 :doc:`传统 GNU Make 编译系统<../get-started-legacy/windows-setup>` 和 MSYS2_ Unix 兼容环境。但如今已非必需，用户可直接通过 Windows 命令提示符使用 ESP-IDF。
|
||||
|
||||
.. _get-started-windows-tools-installer:
|
||||
|
||||
ESP-IDF 工具安装器
|
||||
=======================
|
||||
|
||||
安装 ESP-IDF 必备工具最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
|
||||
要安装 ESP-IDF 必备工具，最简易的方式是下载 ESP-IDF 工具安装器，地址如下：
|
||||
|
||||
https://dl.espressif.com/dl/esp-idf-tools-setup-1.2.exe
|
||||
https://dl.espressif.com/dl/esp-idf-tools-setup-2.0.exe
|
||||
|
||||
安装器会自动安装 ESP32 Xtensa gcc 工具链，Ninja_ 编译工具，以及名为 mconf-idf_ 的配置工具。此外，如果你的电脑还未安装有关 CMake_ 和 Python_ 2.7 的安装器，它还可以下载和运行与之对应的安装器。
|
||||
本安装器可为您安装所需的交叉编译器、OpenOCD、cmake_ 和 Ninja_ 编译工具，以及一款 mconf-idf_ 配置工具。此外，本安装器还可在有需要时下载、运行 Python_ 3.7 和 `Git For Windows` 的安装器。
|
||||
|
||||
安装器默认更新 Windows ``Path`` 环境变量，因而上述工具也可在其他环境中运行。如果禁止该选项，则需自行设置 ESP-IDF 所使用的环境（终端或所选 IDE），并配置正确的路径。
|
||||
本安装器还可用于下载任意 ESP-IDF 发布版本。
|
||||
|
||||
请注意，此安装器仅针对 ESP-IDF 工具包，并不包括 ESP-IDF。
|
||||
使用命令提示符
|
||||
========================
|
||||
|
||||
安装 Git
|
||||
==============
|
||||
在后续步骤中，我们将使用 Windows 的命令提示符进行操作。
|
||||
|
||||
ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你将以命令行的模式使用它。你可以通过 `Git For Windows`_ 下载和安装 Windows 平台的命令行 Git 工具（包括 "Git Bash" 终端）。
|
||||
ESP-IDF 工具安装器可在“开始”菜单中，创建一个打开 ESP-IDF 命令提示符窗口的快捷方式。本快捷方式可以打开 Windows 命令提示符（即 cmd.exe），并运行 ``export.bat`` 脚本以设置各环境变量（比如 ``PATH``，``IDF_PATH`` 等）。此外，您可还以通过 Windows 命令提示符使用各种已经安装的工具。
|
||||
|
||||
如果你想使用其他图形化 Git 客户端，如 `Github Desktop`， 你可以自行安装，但需要对本《入门指南》中相应的 Git 命令进行转换，以便用于你所选的 Git 客户端。
|
||||
注意，本快捷方式仅适用 ESP-IDF 工具安装器中指定的 ESP-IDF 路径。如果您的电脑上存在多个 ESP-IDF（比如您需要不同的 ESP-IDF 版本）需要使用快捷方式，您可以：
|
||||
|
||||
使用终端
|
||||
================
|
||||
1. 为 ESP-IDF 工具安装器创建的快捷方式创建一个副本，并将新快捷方式的“当前路径”指定为您希望使用的 ESP-IDF 路径。
|
||||
|
||||
在本《入门指南》接下来的步骤说明中，我们将使用终端命令提示符进行有关操作。你也可以使用任何其他形式的命令提示符：
|
||||
|
||||
- 比如，Windows 开始菜单下内置的命令提示符。本文档中的所有 Windows 命令行指令均为 Windows 命令提示符中所使用的 "batch" 命令。
|
||||
- 你还可以使用 `Git for Windows`_ 中的 "Git Bash" 终端，其所使用的 "bash" 命令提示符语法与 Mac OS 或 Linux 的既定语法相同。安装此终端后，你可以在开始菜单下找到命令提示符窗口。
|
||||
- 如果你已安装 MSYS2_ （通过 ESP-IDF 之前版本），你还可以使用 MSYS 终端。
|
||||
2. 运行 ``cmd.exe``，并更新至您希望使用的 ESP-IDF 目录，然后运行 ``export.bat``。注意，这种方法要求 ``PATH`` 中存在 Python 和 Git。如果您在使用时遇到有关“找不到 Python 或 Git” 的错误信息，请使用第一种方法。
|
||||
|
||||
后续步骤
|
||||
==========
|
||||
|
||||
要继续设置开发环境，请参照 :ref:`get-started-get-esp-idf`。
|
||||
当 ESP-IDF 工具安装器安装完成后，则开发环境设置也到此结束。后续开发步骤，请前往 :ref:`get-started-start-project` 查看。
|
||||
|
||||
相关文档
|
||||
=================
|
||||
@@ -59,7 +57,7 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你
|
||||
:maxdepth: 1
|
||||
|
||||
windows-setup-scratch
|
||||
|
||||
windows-setup-update
|
||||
|
||||
.. _MSYS2: https://msys2.github.io/
|
||||
.. _cmake: https://cmake.org/download/
|
||||
@@ -68,3 +66,4 @@ ESP-IDF 工具安装器并不会安装 Git，因为快速入门指南默认你
|
||||
.. _Git for Windows: https://gitforwindows.org/
|
||||
.. _mconf-idf: https://github.com/espressif/kconfig-frontends/releases/
|
||||
.. _Github Desktop: https://desktop.github.com/
|
||||
|
||||
|
||||
Reference in New Issue
Block a user