ESP_MAC_ETH,
} esp_mac_type_t;
+/** @cond */
#define TWO_UNIVERSAL_MAC_ADDR 2
#define FOUR_UNIVERSAL_MAC_ADDR 4
#define UNIVERSAL_MAC_ADDR_NUM CONFIG_NUMBER_OF_UNIVERSAL_MAC_ADDRESS
-
+/** @endcond */
/**
* @brief Reset reasons
/** @cond */
/**
- * @attention application don't need to call this function anymore. It do nothing and will
+ * @attention Applications don't need to call this function anymore. It does nothing and will
* be removed in future version.
*/
void system_init(void) __attribute__ ((deprecated));
* This name will be removed in a future release.
*/
void system_restore(void) __attribute__ ((deprecated));
+/** @endcond */
+/**
+ * Shutdown handler type
+ */
typedef void (*shutdown_handler_t)(void);
+
/**
* @brief Register shutdown handler
*
- * This function allows you to register a handler that gets invoked before a
- * systematic shutdown of the chip.
+ * This function allows you to register a handler that gets invoked before
+ * the application is restarted using esp_restart function.
*/
esp_err_t esp_register_shutdown_handler(shutdown_handler_t handle);
*/
void esp_restart(void) __attribute__ ((noreturn));
+/** @cond */
/**
* @brief Restart system.
*
* This name will be removed in a future release.
*/
void system_restart(void) __attribute__ ((deprecated, noreturn));
+/** @endcond */
/**
* @brief Get reason of last reset
*/
esp_reset_reason_t esp_reset_reason(void);
+/** @cond */
/**
* @brief Get system time, unit: microsecond.
*
* This definition will be removed in a future release.
*/
uint32_t system_get_time(void) __attribute__ ((deprecated));
+/** @endcond */
/**
* @brief Get the size of available heap.
*/
uint32_t esp_get_free_heap_size(void);
+/** @cond */
/**
* @brief Get the size of available heap.
*
* @return Available heap size, in bytes.
*/
uint32_t system_get_free_heap_size(void) __attribute__ ((deprecated));
+/** @endcond */
/**
* @brief Get the minimum heap that has ever been available
*/
esp_err_t esp_efuse_mac_get_default(uint8_t *mac);
+/** @cond */
/**
* @brief Read hardware MAC address from efuse.
*
* @return ESP_OK on success
*/
esp_err_t system_efuse_read_mac(uint8_t *mac) __attribute__ ((deprecated));
+/** @endcond */
/**
* @brief Read base MAC address and set MAC address of the interface.
*/
esp_err_t esp_derive_local_mac(uint8_t* local_mac, const uint8_t* universal_mac);
+/** @cond */
/**
* Get SDK version
*
* @return constant string "master"
*/
const char* system_get_sdk_version(void) __attribute__ ((deprecated));
+/** @endcond */
/**
* Get IDF version
CHIP_ESP32 = 1, //!< ESP32
} esp_chip_model_t;
-/**
- * Chip feature flags, used in esp_chip_info_t
- */
-#define CHIP_FEATURE_EMB_FLASH BIT(0)
-#define CHIP_FEATURE_WIFI_BGN BIT(1)
-#define CHIP_FEATURE_BLE BIT(4)
-#define CHIP_FEATURE_BT BIT(5)
+/* Chip feature flags, used in esp_chip_info_t */
+#define CHIP_FEATURE_EMB_FLASH BIT(0) //!< Chip has embedded flash memory
+#define CHIP_FEATURE_WIFI_BGN BIT(1) //!< Chip has 2.4GHz WiFi
+#define CHIP_FEATURE_BLE BIT(4) //!< Chip has Bluetooth LE
+#define CHIP_FEATURE_BT BIT(5) //!< Chip has Bluetooth Classic
/**
* @brief The structure represents information about the chip
../../components/freertos/include/freertos/event_groups.h \
../../components/freertos/include/freertos/ringbuf.h \
### Helper functions for error codes
- ../../components/esp32/include/esp_err.h
+ ../../components/esp32/include/esp_err.h \
+ ### System APIs
+ ../../components/esp32/include/esp_system.h
+++ /dev/null
-Base MAC address
-================
-
-Overview
---------
-
-Serveral MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (WiFi/BT/Ethernet).
-The final octet of each universally administered MAC address increases by one. Only the first one which is called base MAC address
-of them is stored in EFUSE or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3
-(respectively) to the final octet of the base MAC address.
-
-If the universally administered MAC addresses are not enough for all of the networking interfaces. Local administered MAC addresses
-which are derived from universally administered MAC addresses are assigned to the reset of networking interfaces.
-
-A `definition of local vs universal MAC address can be found on Wikipedia <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_.
-
-The number of universally administered MAC address can be configured using ``make menuconfig``.
-
-Base MAC address
-^^^^^^^^^^^^^^^^
-
-If using the default base MAC address factory programmed by Espressif in BLK0 of EFUSE, nothing needs to be done.
-
-If using a custom base MAC address stored in BLK3 of EFUSE, call API ``esp_efuse_mac_get_custom()`` to get the base MAC address
-which is stored in BLK3 of EFUSE. If correct MAC address is returned, then call ``esp_base_mac_addr_set()`` to set the base MAC
-address for system to generate the MAC addresses used by the networking interfaces(WiFi/BT/Ethernet).
-There are 192 bits storage spaces for custom to store base MAC address in BLK3 of EFUSE. They are EFUSE_BLK3_RDATA0,
-EFUSE_BLK3_RDATA1, EFUSE_BLK3_RDATA2, EFUSE_BLK3_RDATA3, EFUSE_BLK3_RDATA4 and EFUSE_BLK3_RDATA5, each of them is 32 bits
-register. The format of the 192 bits storage spaces is:
-
-.. highlight:: none
-
-::
-
- ------------------------------------------------------
- Field |Bits |Range |Description
- ------------------------------------------------------
- version |8 |[191:184] |1: useful. 0: useless
- ------------------------------------------------------
- reserve |112 |[183:72] |reserved
- ------------------------------------------------------
- mac address |64 |[71:8] |base MAC address
- ------------------------------------------------------
- mac crc |8 |[7:0] |crc of base MAC address
- ------------------------------------------------------
-
-If using base MAC address stored in external storage, firstly get the base MAC address stored in external storage, then call
-API ``esp_base_mac_addr_set()`` to set the base MAC address for system to generate the MAC addresses used by the networking
-interfaces(WiFi/BT/Ethernet).
-
-All of the steps must be done before initializing the networking interfaces(WiFi/BT/Ethernet). It is recommended to do it in
-``app_main()`` which can be referenced in :example:`system/base_mac_address`.
-
-Number of universally administered MAC address
-^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
-
-If the number of universal MAC addresses is two, only two interfaces (WiFi station and Bluetooth) receive a universally
-administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address.
-The remaining two interfaces (WiFi softap and Ethernet) receive local MAC addresses. These are derived from the universal
-WiFi station and Bluetooth MAC addresses, respectively.
-
-If the number of universal MAC addresses is four, all four interfaces (WiFi station, WiFi softap, Bluetooth and Ethernet)
-receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively)
-to the final octet of the base MAC address.
-
-When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC
-address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)
-
-API Reference
--------------
-
-Header Files
-^^^^^^^^^^^^
-
- * :component_file:`esp32/include/esp_system.h`
-
-
-Functions
----------
-
-.. doxygenfunction:: esp_base_mac_addr_set
-.. doxygenfunction:: esp_efuse_mac_get_custom
Application Level Tracing <app_trace>
Power Management <power_management>
Sleep Modes <sleep_modes>
- Base MAC address <base_mac_address>
Over The Air Updates (OTA) <ota>
ESP HTTPS OTA <esp_https_ota>
ESP pthread <esp_pthread>
Error Codes and Helper Functions <esp_err>
+ Miscellaneous System APIs <system>
Example code for this API section is provided in :example:`system` directory of ESP-IDF examples.
--- /dev/null
+Miscellaneous System APIs
+=========================
+
+Software reset
+--------------
+
+To perform software reset of the chip, :cpp:func:`esp_restart` function is provided. When the function is called, execution of the program will stop, both CPUs will be reset, application will be loaded by the bootloader and started again.
+
+Additionally, :cpp:func:`esp_register_shutdown_handler` function is provided to register a routine which needs to be called prior to restart (when done by :cpp:func:`esp_restart`). This is similar to the functionality of ``atexit`` POSIX function.
+
+Reset reason
+------------
+
+ESP-IDF application can be started or restarted due to a variety of reasons. To get the last reset reason, call :cpp:func:`esp_reset_reason` function. See description of :cpp:type:`esp_reset_reason_t` for the list of possible reset reasons.
+
+Heap memory
+-----------
+
+Two heap memory related functions are provided:
+
+* :cpp:func:`esp_get_free_heap_size` returns the current size of free heap memory
+* :cpp:func:`esp_get_minimum_free_heap_size` returns the minimum size of free heap memory that was available during program execution.
+
+Note that ESP-IDF supports multiple heaps with different capabilities. Functions mentioned in this section return the size of heap memory which can be allocated using ``malloc`` family of functions. For further information about heap memory see :doc:`Heap Memory Allocation <mem_alloc>`.
+
+Random number generation
+------------------------
+
+ESP32 contains a hardware random number generator, values from it can be obtained using :cpp:func:`esp_random`.
+
+When Wi-Fi or Bluetooth are enabled, numbers returned by hardware random number generator (RNG) can be considered true random numbers. Without Wi-Fi or Bluetooth enabled, hardware RNG is a pseudo-random number generator. At startup, ESP-IDF bootloader seeds the hardware RNG with entropy, but care must be taken when reading random values between the start of ``app_main`` and initialization of Wi-Fi or Bluetooth drivers.
+
+
+MAC Address
+-----------
+
+These APIs allow querying and customizing MAC addresses used by Wi-Fi, Bluetooth, and Ethernet drivers.
+
+ESP32 has up to 4 network interfaces: Wi-Fi station, Wi-Fi AP, Ethernet, and Bluetooth. Each of these interfaces needs to have a MAC address assigned to it. In ESP-IDF these addresses are calculated from *Base MAC address*. Base MAC address can be initialized with factory-programmed value from EFUSE, or with a user-defined value. In addition to setting the base MAC address, applications can specify the way in which MAC addresses are allocated to devices. See `Number of universally administered MAC address`_ section for more details.
+
++---------------+--------------------------------+----------------------------------+
+| Interface | MAC address | MAC address |
+| | (4 universally administered) | (2 universally administered) |
++===============+================================+==================================+
+| Wi-Fi Station | base_mac | base_mac |
++---------------+--------------------------------+----------------------------------+
+| Wi-Fi SoftAP | base_mac, +1 to the last octet | base_mac, first octet randomized |
++---------------+--------------------------------+----------------------------------+
+| Bluetooth | base_mac, +2 to the last octet | base_mac, +1 to the last octet |
++---------------+--------------------------------+----------------------------------+
+| Ethernet | base_mac, +3 to the last octet | base_mac, +1 to the last octet, |
+| | | first octet randomized |
++---------------+--------------------------------+----------------------------------+
+
+
+Base MAC address
+^^^^^^^^^^^^^^^^
+
+Wi-Fi, Bluetooth, and Ethernet drivers use :cpp:func:`esp_read_mac` function to get MAC address for a specific interface.
+
+By default, this function will use MAC address factory programmed in BLK0 of EFUSE as the base MAC address. MAC addresses of each interface will be calculated according to the table above.
+
+Applications which don't use MAC address factory programmed into BLK0 of EFUSE can modify base MAC address used by :cpp:func:`esp_read_mac` using a call to :cpp:func:`esp_base_mac_addr_set`. Custom value of MAC address can come from application defined storage, such as Flash, NVS, etc. Note that the call to :cpp:func:`esp_base_mac_addr_set` needs to happen before network protocol stacks are initialized, for example, early in ``app_main``.
+
+Custom MAC address in BLK3 of EFUSE
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+To facilitate usage of custom MAC addresses, ESP-IDF provides :cpp:func:`esp_efuse_mac_get_custom` function, which loads MAC address from BLK3 of EFUSE. This function assumes that custom MAC address is stored in BLK3 of EFUSE (EFUSE_BLK3_RDATA0, EFUSE_BLK3_RDATA1, EFUSE_BLK3_RDATA2, EFUSE_BLK3_RDATA3, EFUSE_BLK3_RDATA4, EFUSE_BLK3_RDATA5 registers) in the following format:
+
++-----------------+-----------+---------------+------------------------------+
+| Field | # of bits | Range of bits | Notes |
++=================+===========+===============+==============================+
+| Version | 8 | 191:184 | 0: invalid, others — valid |
++-----------------+-----------+---------------+------------------------------+
+| Reserved | 128 | 183:56 | |
++-----------------+-----------+---------------+------------------------------+
+| MAC address | 48 | 55:8 | |
++-----------------+-----------+---------------+------------------------------+
+| MAC address CRC | 8 | 7:0 | CRC-8-CCITT, polynomial 0x07 |
++-----------------+-----------+---------------+------------------------------+
+
+Once MAC address has been obtained using :cpp:func:`esp_efuse_mac_get_custom`, call :cpp:func:`esp_base_mac_addr_set` to set this MAC address as base MAC address.
+
+
+Number of universally administered MAC address
+^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
+
+Serveral MAC addresses (universally administered by IEEE) are uniquely assigned to the networking interfaces (Wi-Fi/BT/Ethernet). The final octet of each universally administered MAC address increases by one. Only the first one of them (which is called base MAC address) is stored in EFUSE or external storage, the others are generated from it. Here, 'generate' means adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
+
+If the universally administered MAC addresses are not enough for all of the networking interfaces, locally administered MAC addresses which are derived from universally administered MAC addresses are assigned to the rest of networking interfaces.
+
+See `this article <https://en.wikipedia.org/wiki/MAC_address#Universal_vs._local>`_ for the definition of local and universally administered MAC addresses.
+
+The number of universally administered MAC address can be configured using :envvar:`CONFIG_NUMBER_OF_UNIVERSAL_MAC_ADDRESS`.
+
+If the number of universal MAC addresses is two, only two interfaces (Wi-Fi Station and Bluetooth) receive a universally administered MAC address. These are generated sequentially by adding 0 and 1 (respectively) to the base MAC address. The remaining two interfaces (Wi-Fi SoftAP and Ethernet) receive local MAC addresses. These are derived from the universal Wi-Fi station and Bluetooth MAC addresses, respectively.
+
+If the number of universal MAC addresses is four, all four interfaces (Wi-Fi Station, Wi-Fi SoftAP, Bluetooth and Ethernet) receive a universally administered MAC address. These are generated sequentially by adding 0, 1, 2 and 3 (respectively) to the final octet of the base MAC address.
+
+When using the default (Espressif-assigned) base MAC address, either setting can be used. When using a custom universal MAC address range, the correct setting will depend on the allocation of MAC addresses in this range (either 2 or 4 per device.)
+
+Chip version
+------------
+
+:cpp:func:`esp_chip_info` function fills :cpp:class:`esp_chip_info_t` structure with information about the chip. This includes the chip revision, number of CPU cores, and a bit mask of features enabled in the chip.
+
+SDK version
+-----------
+
+:cpp:func:`esp_get_idf_version` returns a string describing the IDF version which was used to compile the application. This is the same value as the one available through ``IDF_VER`` variable of the build system. The version string generally has the format of ``git describe`` output.
+
+
+API Reference
+-------------
+
+.. include:: /_build/inc/esp_system.inc
+
+
+++ /dev/null
-.. include:: ../../../en/api-reference/system/base_mac_address.rst
\ No newline at end of file
--- /dev/null
+.. include:: ../../../en/api-reference/system/system.rst
projects / esp-idf / commitdiff