alex/esp-idf
1
0
Fork 0
mirror of https://github.com/espressif/esp-idf.git synced 2025-12-16 04:22:22 +00:00
Code Issues Packages Projects Releases Wiki Activity

Merge branch 'master' into feature/cmake_update

Browse Source
This commit is contained in:
Angus Gratton
2018-05-30 17:41:35 +10:00
committed by Angus Gratton
parent f5f966d91a 9d47f348ab
commit 6b9784cc45
1102 changed files with 77153 additions and 96172 deletions
Download Patch File Download Diff File Expand all files Collapse all files

45
docs/en/api-guides/bootloader.rst
View File

@@ -9,7 +9,52 @@ Bootloader performs the following functions:
Bootloader is located at the address `0x1000` in the flash.
FACTORY reset
---------------------------
The user can write a basic working firmware and load it into the factory partition.
Next, update the firmware via OTA (over the air). The updated firmware will be loaded into an OTA app partition slot and the OTA data partition is updated to boot from this partition.
If you want to be able to roll back to the factory firmware and clear the settings, then you need to set :ref:`CONFIG_BOOTLOADER_FACTORY_RESET`.
The factory reset mechanism allows to reset the device to factory settings:
- Clear one or more data partitions.
- Boot from "factory" partition.
:ref:`CONFIG_BOOTLOADER_DATA_FACTORY_RESET` allows customers to select which data partitions will be erased when the factory reset is executed.
Can specify the names of partitions through comma-delimited with optional spaces for readability. (Like this: "nvs, phy_init, nvs_custom, ...").
Make sure that the name specified in the partition table and here are the same.
Partitions of type "app" cannot be specified here.
:ref:`CONFIG_BOOTLOADER_OTA_DATA_ERASE` - the device will boot from "factory" partition after a factory reset. The OTA data partition will be cleared.
:ref:`CONFIG_BOOTLOADER_NUM_PIN_FACTORY_RESET`- number of the GPIO input for factory reset uses to trigger a factory reset, this GPIO must be pulled low on reset to trigger this.
:ref:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO`- this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
Partition table.::
# Name, Type, SubType, Offset, Size, Flags
# Note: if you change the phy_init or app partition offset, make sure to change the offset in Kconfig.projbuild
nvs, data, nvs, 0x9000, 0x4000
otadata, data, ota, 0xd000, 0x2000
phy_init, data, phy, 0xf000, 0x1000
factory, 0, 0, 0x10000, 1M
test, 0, test, , 512K
ota_0, 0, ota_0, , 512K
ota_1, 0, ota_1, , 512K
Boot from TEST firmware
------------------------
The user can write a special firmware for testing in production, and run it as needed. The partition table also needs a dedicated partition for this testing firmware (See `partition table`).
To trigger a test app you need to set :ref:`CONFIG_BOOTLOADER_APP_TEST`.
:ref:`CONFIG_BOOTLOADER_NUM_PIN_APP_TEST` - number of the GPIO input to boot TEST partition. The selected GPIO will be configured as an input with internal pull-up enabled. To trigger a test app, this GPIO must be pulled low on reset.
After the GPIO input is deactivated and the device reboots, the old application will boot (factory or any OTA slot).
:ref:`CONFIG_BOOTLOADER_HOLD_TIME_GPIO` - this is hold time of GPIO for reset/test mode (by default 5 seconds). The GPIO must be held low continuously for this period of time after reset before a factory reset or test partition boot (as applicable) is performed.
Customer bootloader
---------------------
The current bootloader implementation allows the customer to override it. To do this, you must copy the folder `/esp-idf/components/bootloader` and then edit `/your_project/components/bootloader/subproject/main/bootloader_main.c`.
In the bootloader space, you can not use the drivers and functions from other components. If necessary, then the required functionality should be placed in the folder bootloader (note that this will increase its size).
It is necessary to monitor its size because there can be overlays in memory with a partition table leading to damage. At the moment the bootloader is limited to the partition table from the address `0x8000`.

2
docs/en/api-guides/core_dump.rst
View File

@@ -63,6 +63,8 @@ Base64-encoded body of core dump will be between the following header and footer
<body of base64-encoded core dump, save it to file on disk>
================= CORE DUMP END ===================
The `CORE DUMP START` and `CORE DUMP END` lines must not be included in core dump text file.
Running 'espcoredump.py'
------------------------------------

7
docs/en/api-guides/freertos-smp.rst
View File

@@ -16,6 +16,9 @@ of FreeRTOS v8.2.0. This guide outlines the major differences between vanilla
FreeRTOS and ESP-IDF FreeRTOS. The API reference for vanilla FreeRTOS can be
found via http://www.freertos.org/a00106.html
For information regarding features that are exclusive to ESP-IDF FreeRTOS,
see :doc:`ESP-IDF FreeRTOS Additions<../api-reference/system/freertos_additions>`.
:ref:`backported-features`: Although ESP-IDF FreeRTOS is based on the Xtensa
port of FreeRTOS v8.2.0, a number of FreeRTOS v9.0.0 features have been backported
to ESP-IDF.
@@ -70,10 +73,6 @@ used to free memory pointed to by TLSP. Call
:cpp:func:`vTaskSetThreadLocalStoragePointerAndDelCallback()` to set TLSP and Deletion
Callbacks.
:ref:`FreeRTOS Hooks<hooks_api_reference>`: Vanilla FreeRTOS Hooks were not designed for SMP.
ESP-IDF provides its own Idle and Tick Hooks in addition to the Vanilla FreeRTOS
hooks. For full details, see the ESP-IDF Hooks API Reference.
:ref:`esp-idf-freertos-configuration`: Several aspects of ESP-IDF FreeRTOS can be
configured using ``make meunconfig`` such as running ESP-IDF in Unicore Mode,
or configuring the number of Thread Local Storage Pointers each task will have.

2
docs/en/api-guides/jtag-debugging/building-openocd-macos.rst
View File

@@ -12,7 +12,7 @@ Download Sources of OpenOCD
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
cd ~/esp
git clone –recursive https://github.com/espressif/openocd-esp32.git
git clone --recursive https://github.com/espressif/openocd-esp32.git
The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory.

2
docs/en/api-guides/jtag-debugging/building-openocd-windows.rst
View File

@@ -13,7 +13,7 @@ Download Sources of OpenOCD
The sources for the ESP32-enabled variant of OpenOCD are available from Espressif GitHub under https://github.com/espressif/openocd-esp32. To download the sources, use the following commands::
cd ~/esp
git clone –recursive https://github.com/espressif/openocd-esp32.git
git clone --recursive https://github.com/espressif/openocd-esp32.git
The clone of sources should be now saved in ``~/esp/openocd-esp32`` directory.

0
docs/en/api-guides/ulp_instruction_set.rst Executable file → Normal file
View File

187
docs/en/api-guides/wifi.rst Executable file → Normal file
View File

@@ -1295,51 +1295,9 @@ Wi-Fi 80211 Packet Send
The esp_wifi_80211_tx API can be used to:
- Send the beacon, probe request, probe response, action frame.
- Send the QoS and non-QoS data frame.
- Send the non-QoS data frame.
It cannot be used for sending cryptographic frames.
Parameters of esp_wifi_80211_tx
+++++++++++++++++++++++++++++++++++++++++++
+-----------------------------+---------------------------------------------------+
| Parameter | Description |
+=============================+===================================================+
| ifx | Wi-Fi interface ID: if the Wi-Fi mode is Station, |
| | the ifx should be WIFI_IF_STA. If the Wi-Fi |
| | mode is SoftAP, the ifx should be WIFI_IF_AP. If |
| | the Wi-Fi mode is Station+SoftAP, the ifx should |
| | be WIFI_IF_STA or WIFI_IF_AP. |
| | If the ifx is wrong, the API returns |
| | ESP_ERR_WIFI_IF. |
+-----------------------------+---------------------------------------------------+
| buffer | Raw 802.11 buffer. For building the correct |
| | buffer, refer to the following sections: |
| | |
| | If the buffer is wrong, or violates the Wi-Fi |
| | driver's restrictions, the API returns |
| | ESP_ERR_INVALID_ARG or results in unexpected |
| | behavior. **Please read the following section |
| | carefully to make sure you understand the |
| | restrictions on encapsulating the buffer.** |
| | |
+-----------------------------+---------------------------------------------------+
| len | The length must be <= 1500; otherwise, the API |
| | will return ESP_ERR_INVALID_ARG. |
| | |
+-----------------------------+---------------------------------------------------+
| en_sys_seq | If en_sys_seq is true, it means that the Wi-Fi |
| | driver will rewrite the sequence number in the |
| | buffer; otherwise, it will not rewrite the |
| | sequence number. |
| | Generally, if esp_wifi_80211_tx is called before |
| | the Wi-Fi connection has been set up, both |
| | en_sys_seq==true and en_sys_seq==false are fine. |
| | However, if the API is called after the Wi-Fi |
| | connection has been set up, en_sys_seq should be |
| | true. For more details, read the following section|
| | about the sequence configuration. |
+-----------------------------+---------------------------------------------------+
It cannot be used for sending encrypted or QoS frames.
Preconditions of Using esp_wifi_80211_tx
++++++++++++++++++++++++++++++++++++++++++++
@@ -1348,6 +1306,12 @@ Preconditions of Using esp_wifi_80211_tx
- Either esp_wifi_set_promiscuous(true), or esp_wifi_start(), or both of these APIs return ESP_OK. This is because we need to make sure that Wi-Fi hardware is initialized before esp_wifi_80211_tx() is called. In ESP32, both esp_wifi_set_promiscuous(true) and esp_wifi_start() can trigger the initialization of Wi-Fi hardware.
- The parameters of esp_wifi_80211_tx are hereby correctly provided.
Data rate
+++++++++++++++++++++++++++++++++++++++++++++++
- If there is no WiFi connection, the data rate is 1Mbps.
- If there is WiFi connection and the packet is from station to SoftAP or from SoftAP to station, the data rate is same as the WiFi connection. Otherwise the data rate is 1Mbps.
Side-Effects to Avoid in Different Scenarios
+++++++++++++++++++++++++++++++++++++++++++++++++++++
@@ -1356,10 +1320,10 @@ Theoretically, if we do not consider the side-effects the API imposes on the Wi-
+-----------------------------+---------------------------------------------------+
| Scenario | Description |
+=============================+===================================================+
| NO_CONN_MGMT | In this scenario, no Wi-Fi connection is set up, |
| No WiFi connection | In this scenario, no Wi-Fi connection is set up, |
| | so there are no side-effects on the Wi-Fi driver. |
| - No Wi-Fi connection | If en_sys_seq==true, the Wi-Fi driver is |
| - Can send management frame| responsible for the sequence control. If |
| | If en_sys_seq==true, the Wi-Fi driver is |
| | responsible for the sequence control. If |
| | en_sys_seq==false, the application needs to ensure|
| | that the buffer has the correct sequence. |
| | |
@@ -1394,48 +1358,48 @@ Theoretically, if we do not consider the side-effects the API imposes on the Wi-
| | side-effects and can be ignored when there are |
| | good reasons for doing this. |
+-----------------------------+---------------------------------------------------+
| NO_CONN_NON_QOS | Same as in NO_CONN_MGMT |
| | |
| - No Wi-Fi connection | |
| - Can send non-QoS frame | |
| | |
+-----------------------------+---------------------------------------------------+
| NO_CONN_QOS | Same as in NO_CONN_MGMT |
| | |
| - No Wi-Fi connection | |
| - Can send QoS frame | |
| | |
+-----------------------------+---------------------------------------------------+
| CONN_MGMT | When the Wi-Fi connection is already set up, and |
| Have WiFi connection | When the Wi-Fi connection is already set up, and |
| | the sequence is controlled by the application, the|
| - Have Wi-Fi connection | latter may impact the sequence control of the |
| - Send management frame | Wi-Fi connection, as a whole. So, the |
| only | recommendation is that en_sys_seq be true. |
| | The MAC-address recommendations in the |
| | NO_CONN_MGMT scenario also apply to the CONN_MGMT |
| | scenario. |
+-----------------------------+---------------------------------------------------+
| CONN_NON_QOS | Generally, we should use a socket API, instead of |
| | this one, in order to send the data frame when |
| - Have Wi-Fi connection | the Wi-Fi connection is already set up. |
| - Can send non-QoS frame | |
| | However, if you have any special reasons for using|
| | this particular API, then en_sys_seq must be true;|
| | otherwise, you may impact the internal sequence |
| | control of the Wi-Fi connection described |
| | in CONN_MGMT. |
| | The MAC-address recommendations in the |
| | NO_CONN_MGMT scenario also apply to the CONN_MGMT |
| | scenario. |
+-----------------------------+---------------------------------------------------+
| CONN_QOS | Same as in CONN_NON_QOS |
| | latter may impact the sequence control of the |
| | Wi-Fi connection, as a whole. So, the |
| | en_sys_seq need to be true, otherwise |
| | ESP_ERR_WIFI_ARG is returned. |
| | |
| - Have Wi-Fi connection | |
| - Can send non-QoS frame | |
| | The MAC-address recommendations in the |
| | "No WiFi connection" scenario also apply to this |
| | scenario. |
| | |
| | If the WiFi mode is station mode and the MAC |
| | address1 is the MAC of AP to which the station is |
| | connected, the MAC address2 is the MAC of station |
| | interface, we say the packets is from the station |
| | to SoftAP. On the other hand, if the WiFi mode is |
| | SoftAP mode and the MAC address1 is the MAC of |
| | the station who connects to this SoftAP, the MAC |
| | address2 is the MAC of SoftAP interface, we say |
| | the packet is from the SoftAP to station. |
| | To avoid conflicting with WiFi connections, the |
| | following checks are applied: |
| | |
| | - If the packet type is data and is from the |
| | station to SoftAP, the ToDS bit in ieee80211 |
| | frame control should be 1, the FromDS bit |
| | should be 0, otherwise the packet will be |
| | discarded by WiFi driver. |
| | - If the packet type is data and is from the |
| | softAP to station, the ToDS bit in ieee80211 |
| | frame control should be 0, the FromDS bit |
| | should be 1, otherwise the packet will be |
| | discarded by WiFi driver. |
| | - If the packet is from station to SoftAP or |
| | from SoftAP to station, the Power Management, |
| | More Data, Re-Transmission bits should be 0, |
| | otherwise the packet will be discarded by WiFi |
| | driver. |
| | |
| | ESP_ERR_WIFI_ARG is returned if any check fails. |
+-----------------------------+---------------------------------------------------+
Wi-Fi Sniffer Mode
---------------------------
@@ -1456,6 +1420,61 @@ The Wi-Fi sniffer mode can be enabled in the Wi-Fi mode of WIFI_MODE_NULL, or WI
Another noteworthy issue about the sniffer is the callback wifi_promiscuous_cb_t. The callback will be called directly in the Wi-Fi driver task, so if the application has a lot of work to do for each filtered packet, the recommendation is to post an event to the application task in the callback and defer the real work to the application task.
Wi-Fi Multiple Antennas
--------------------------
The Wi-Fi multiple antennas selecting can be depicted as following picture::
__________
|Enabled |
___|Antenna 0 |\\ _________
|__________| \\ GPIO[0] <----> antenna_select[0] ---| | --- antenna 0
RX/TX ___ \\____\ GPIO[1] <----> antenna_select[1] ---| Antenna | --- antenna 1
\ __________ // / GPIO[2] <----> antenna_select[2] ---| Switch | ... ...
\ ___|Enabled | // GPIO[3] <----> antenna_select[3] ---|_________| --- antenna 15
\ |Antenna 1 |//
|__________|
ESP32 supports up to sixteen antennas through external antenna switch. The antenna switch can be controlled by up to four address pins - antenna_select[0:3]. Different input value of antenna_select[0:3] means selecting different antenna. E.g. the value '0b1011' means the antenna 11 is selected. The default value of antenna_select[3:0] is '0b0000', it means the antenna 0 is selected by default.
Up to four GPIOs are connected to the four active high antenna_select pins. ESP32 can select the antenna by control the GPIO[0:3]. The API :cpp:func:`esp_wifi_set_ant_gpio()` is used to configure which GPIOs are connected to antenna_selects. If GPIO[x] is connected to antenna_select[x], then gpio_config->gpio_cfg[x].gpio_select should be set to 1 and gpio_config->gpio_cfg[x].gpio_num should be provided.
Although up to sixteen anteenas are supported, only one or two antennas can be simultaneously enabled for RX/TX. The API :cpp:func:`esp_wifi_set_ant()` is used to configure which antennas are enabled.
The enabled antennas selecting algorithm is also configured by :cpp:func:`esp_wifi_set_ant()`. The RX/TX antenna mode can be WIFI_ANT_MODE_ANT0, WIFI_ANT_MODE_ANT1 or WIFI_ANT_MODE_AUTO. If the antenna mode is WIFI_ANT_MODE_ANT0, the enabled antenna 0 is selected for RX/TX data. If the antenna mode is WIFI_ANT_MODE_ANT1, the enabled antenna 1 is selected for RX/TX data. Otherwise, WiFi automatically selects the antenna that has better signal from the enabled antennas.
If the RX antenna mode is WIFI_ANT_MODE_AUTO, the default antenna mode also needs to be set. Because the RX antenna switching only happens when some conditions are met, e.g. the RX antenna starts to switch if the RSSI is lower than -65dBm and if another antenna has better signal etc, RX uses the default antenna if the conditions are not met. If the default antenna mode is WIFI_ANT_MODE_ANT1, the enabled antenna 1 is used as the default RX antenna, otherwise the enabled antenna 0 is used as the default RX antenna.
Some limitations need to be considered:
- The TX antenna can be set to WIFI_ANT_MODE_AUTO only if the RX antenna mode is WIFI_ANT_MODE_AUTO because TX antenna selecting algorithm is based on RX antenna in WIFI_ANT_MODE_AUTO type.
- Currently BT doesn't support the multiple antennas feature, please don't use multiple antennas related APIs.
Following is the recommended scenarios to use the multiple antennas:
- In Wi-Fi mode WIFI_MODE_STA, both RX/TX antenna modes are configured to WIFI_ANT_MODE_AUTO. The WiFi driver selects the better RX/TX antenna automatically.
- The RX antenna mode is configured to WIFI_ANT_MODE_AUTO. The TX antenna mode is configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1. The applications can choose to always select a specified antenna for TX, or implement their own TX antenna selecting algorithm, e.g. selecting the TX antenna mode based on the channel switch information etc.
- Both RX/TX antenna modes are configured to WIFI_ANT_MODE_ANT0 or WIFI_ANT_MODE_ANT1.
Wi-Fi Multiple Antennas Configuration
+++++++++++++++++++++++++++++++++++++
Generally, following steps can be taken to configure the multiple antennas:
- Configure which GPIOs are connected to the antenna_selects, for example, if four antennas are supported and GPIO20/GPIO21 are connected to antenna_select[0]/antenna_select[1], the configurations look like::
wifi_ant_gpio_config_t config = {
{ .gpio_select = 1, .gpio_num = 20 },
{ .gpio_select = 1, .gpio_num = 21 }
};
- Configure which antennas are enabled and how RX/TX use the enabled antennas, for example, if antenna1 and antenna3 are enabled, the RX needs to select the better antenna automatically and uses antenna1 as its default antenna, the TX always selects the antenna3. The configuration looks like::
wifi_ant_config_t config = {
.rx_ant_mode = WIFI_ANT_MODE_AUTO,
.rx_ant_default = WIFI_ANT_ANT0,
.tx_ant_mode = WIFI_ANT_MODE_ANT1,
.enabled_ant0 = 1,
.enabled_ant1 = 3
};
Wi-Fi Buffer Usage
--------------------------