mirror of
https://github.com/espressif/esp-idf.git
synced 2025-10-16 08:59:13 +00:00
Merge branch 'docs/update_CN_trans_console_ota_v4.3' into 'release/v4.3'
update CN trans for console and ota for v4.3 See merge request espressif/esp-idf!16022
This commit is contained in:
Dai Zi Yan
@@ -23,7 +23,7 @@ Line editing feature lets users compose commands by typing them, erasing symbols
|
||||
|
||||
This feature relies on ANSI escape sequence support in the terminal application. As such, serial monitors which display raw UART data can not be used together with the line editing library. If you see ``[6n`` or similar escape sequence when running :example:`system/console` example instead of a command prompt (e.g. ``esp>`` ), it means that the serial monitor does not support escape sequences. Programs which are known to work are GNU screen, minicom, and idf_monitor.py (which can be invoked using ``idf.py monitor`` from project directory).
|
||||
|
||||
Here is an overview of functions provided by `linenoise`_ library.
|
||||
Here is an overview of functions provided by `linenoise <https://github.com/antirez/linenoise>`_ library.
|
||||
|
||||
Configuration
|
||||
^^^^^^^^^^^^^
|
||||
@@ -31,12 +31,15 @@ Configuration
|
||||
Linenoise library does not need explicit initialization. However, some configuration defaults may need to be changed before invoking the main line editing function.
|
||||
|
||||
:cpp:func:`linenoiseClearScreen`
|
||||
|
||||
Clear terminal screen using an escape sequence and position the cursor at the top left corner.
|
||||
|
||||
:cpp:func:`linenoiseSetMultiLine`
|
||||
|
||||
Switch between single line and multi line editing modes. In single line mode, if the length of the command exceeds the width of the terminal, the command text is scrolled within the line to show the end of the text. In this case the beginning of the text is hidden. Single line needs less data to be sent to refresh screen on each key press, so exhibits less glitching compared to the multi line mode. On the flip side, editing commands and copying command text from terminal in single line mode is harder. Default is single line mode.
|
||||
|
||||
:cpp:func:`linenoiseAllowEmpty`
|
||||
|
||||
Set whether linenoise library will return a zero-length string (if ``true``) or ``NULL`` (if ``false``) for empty lines. By default, zero-length strings are returned.
|
||||
|
||||
|
||||
@@ -44,26 +47,33 @@ Main loop
|
||||
^^^^^^^^^
|
||||
|
||||
:cpp:func:`linenoise`
|
||||
|
||||
In most cases, console applications have some form of read/eval loop. :cpp:func:`linenoise` is the single function which handles user's key presses and returns completed line once 'enter' key is pressed. As such, it handles the 'read' part of the loop.
|
||||
|
||||
:cpp:func:`linenoiseFree`
|
||||
|
||||
This function must be called to release the command line buffer obtained from :cpp:func:`linenoise` function.
|
||||
|
||||
|
||||
Hints and completions
|
||||
^^^^^^^^^^^^^^^^^^^^^
|
||||
|
||||
:cpp:func:`linenoiseSetCompletionCallback`
|
||||
|
||||
When user presses 'tab' key, linenoise library invokes completion callback. The callback should inspect the contents of the command typed so far and provide a list of possible completions using calls to :cpp:func:`linenoiseAddCompletion` function. :cpp:func:`linenoiseSetCompletionCallback` function should be called to register this completion callback, if completion feature is desired.
|
||||
|
||||
``console`` component provides a ready made function to provide completions for registered commands, :cpp:func:`esp_console_get_completion` (see below).
|
||||
|
||||
:cpp:func:`linenoiseAddCompletion`
|
||||
|
||||
Function to be called by completion callback to inform the library about possible completions of the currently typed command.
|
||||
|
||||
:cpp:func:`linenoiseSetHintsCallback`
|
||||
|
||||
Whenever user input changes, linenoise invokes hints callback. This callback can inspect the command line typed so far, and provide a string with hints (which can include list of command arguments, for example). The library then displays the hint text on the same line where editing happens, possibly with a different color.
|
||||
|
||||
:cpp:func:`linenoiseSetFreeHintsCallback`
|
||||
|
||||
If hint string returned by hints callback is dynamically allocated or needs to be otherwise recycled, the function which performs such cleanup should be registered via :cpp:func:`linenoiseSetFreeHintsCallback`.
|
||||
|
||||
|
||||
@@ -71,20 +81,26 @@ History
|
||||
^^^^^^^
|
||||
|
||||
:cpp:func:`linenoiseHistorySetMaxLen`
|
||||
|
||||
This function sets the number of most recently typed commands to be kept in memory. Users can navigate the history using up/down arrows.
|
||||
|
||||
:cpp:func:`linenoiseHistoryAdd`
|
||||
|
||||
Linenoise does not automatically add commands to history. Instead, applications need to call this function to add command strings to the history.
|
||||
|
||||
:cpp:func:`linenoiseHistorySave`
|
||||
|
||||
Function saves command history from RAM to a text file, for example on an SD card or on a filesystem in flash memory.
|
||||
|
||||
:cpp:func:`linenoiseHistoryLoad`
|
||||
|
||||
Counterpart to :cpp:func:`linenoiseHistorySave`, loads history from a file.
|
||||
|
||||
:cpp:func:`linenoiseHistoryFree`
|
||||
|
||||
Releases memory used to store command history. Call this function when done working with linenoise library.
|
||||
|
||||
|
||||
Splitting of command line into arguments
|
||||
----------------------------------------
|
||||
|
||||
@@ -107,12 +123,7 @@ Examples:
|
||||
Argument parsing
|
||||
----------------
|
||||
|
||||
For argument parsing, ``console`` component includes `argtable3`_ library. Please see `tutorial`_ for an introduction to `argtable3`_. Github repository also includes `examples`_.
|
||||
|
||||
.. _argtable3: http://www.argtable.org/
|
||||
.. _linenoise: https://github.com/antirez/linenoise
|
||||
.. _tutorial: http://www.argtable.org/tutorial/
|
||||
.. _examples: https://github.com/argtable/argtable3/tree/master/examples
|
||||
For argument parsing, ``console`` component includes `argtable3 <http://www.argtable.org/>`_ library. Please see `tutorial <http://www.argtable.org/tutorial/>`_ for an introduction to `argtable3 <http://www.argtable.org/>`_. Github repository also includes `examples <https://github.com/argtable/argtable3/tree/master/examples>`_.
|
||||
|
||||
|
||||
Command registration and dispatching
|
||||
@@ -132,17 +143,22 @@ For each command, application provides the following information (in the form of
|
||||
A few other functions are provided by the command registration module:
|
||||
|
||||
:cpp:func:`esp_console_run`
|
||||
|
||||
This function takes the command line string, splits it into argc/argv argument list using :cpp:func:`esp_console_split_argv`, looks up the command in the list of registered components, and if it is found, executes its handler.
|
||||
|
||||
:cpp:func:`esp_console_register_help_command`
|
||||
|
||||
Adds ``help`` command to the list of registered commands. This command prints the list of all the registered commands, along with their arguments and help texts.
|
||||
|
||||
:cpp:func:`esp_console_get_completion`
|
||||
|
||||
Callback function to be used with :cpp:func:`linenoiseSetCompletionCallback` from linenoise library. Provides completions to linenoise based on the list of registered commands.
|
||||
|
||||
:cpp:func:`esp_console_get_hint`
|
||||
|
||||
Callback function to be used with :cpp:func:`linenoiseSetHintsCallback` from linenoise library. Provides argument hints for registered commands to linenoise.
|
||||
|
||||
|
||||
Initialize console REPL environment
|
||||
-----------------------------------
|
||||
|
||||
@@ -152,6 +168,7 @@ In a typical application, you only need to call :cpp:func:`esp_console_new_repl_
|
||||
|
||||
After that, you can register your own commands with :cpp:func:`esp_console_cmd_register`. The REPL environment keeps in init state until you call :cpp:func:`esp_console_start_repl`.
|
||||
|
||||
|
||||
Application Example
|
||||
-------------------
|
||||
|
||||
@@ -159,6 +176,7 @@ Example application illustrating usage of the ``console`` component is available
|
||||
|
||||
Besides that, ESP-IDF contains several useful examples which based on `console` component and can be treated as "tools" when developing applications. For example, :example:`peripherals/i2c/i2c_tools`, :example:`wifi/iperf`.
|
||||
|
||||
|
||||
API Reference
|
||||
-------------
|
||||
|
||||
|
||||
@@ -5,33 +5,24 @@ Over The Air Updates (OTA)
|
||||
OTA Process Overview
|
||||
--------------------
|
||||
|
||||
The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running
|
||||
(for example, over WiFi or Bluetooth.)
|
||||
The OTA update mechanism allows a device to update itself based on data received while the normal firmware is running (for example, over Wi-Fi or Bluetooth.)
|
||||
|
||||
OTA requires configuring the :doc:`Partition Table <../../api-guides/partition-tables>` of the device with at least two "OTA app slot"
|
||||
partitions (ie `ota_0` and `ota_1`) and an "OTA Data Partition".
|
||||
OTA requires configuring the :doc:`Partition Table <../../api-guides/partition-tables>` of the device with at least two "OTA app slot" partitions (i.e. `ota_0` and `ota_1`) and an "OTA Data Partition".
|
||||
|
||||
The OTA operation functions write a new app firmware image to whichever OTA app slot is not currently being used for
|
||||
booting. Once the image is verified, the OTA Data partition is updated to specify that this image should be used for the
|
||||
next boot.
|
||||
The OTA operation functions write a new app firmware image to whichever OTA app slot that is currently not selected for booting. Once the image is verified, the OTA Data partition is updated to specify that this image should be used for the next boot.
|
||||
|
||||
.. _ota_data_partition:
|
||||
|
||||
OTA Data Partition
|
||||
------------------
|
||||
|
||||
An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table <../../api-guides/partition-tables>`
|
||||
of any project which uses the OTA functions.
|
||||
An OTA data partition (type ``data``, subtype ``ota``) must be included in the :doc:`Partition Table <../../api-guides/partition-tables>` of any project which uses the OTA functions.
|
||||
|
||||
For factory boot settings, the OTA data partition should contain no data (all bytes erased to 0xFF). In this case the
|
||||
esp-idf software bootloader will boot the factory app if it is present in the the partition table. If no factory app is
|
||||
included in the partition table, the first available OTA slot (usually ``ota_0``) is booted.
|
||||
For factory boot settings, the OTA data partition should contain no data (all bytes erased to 0xFF). In this case the esp-idf software bootloader will boot the factory app if it is present in the the partition table. If no factory app is included in the partition table, the first available OTA slot (usually ``ota_0``) is booted.
|
||||
|
||||
After the first OTA update, the OTA data partition is updated to specify which OTA app slot partition should be booted next.
|
||||
|
||||
The OTA data partition is two flash sectors (0x2000 bytes) in size, to prevent problems if there is a power failure
|
||||
while it is being written. Sectors are independently erased and written with matching data, and if they disagree a
|
||||
counter field is used to determine which sector was written more recently.
|
||||
The OTA data partition is two flash sectors (0x2000 bytes) in size, to prevent problems if there is a power failure while it is being written. Sectors are independently erased and written with matching data, and if they disagree a counter field is used to determine which sector was written more recently.
|
||||
|
||||
.. _app_rollback:
|
||||
|
||||
@@ -51,26 +42,19 @@ App OTA State
|
||||
|
||||
States control the process of selecting a boot app:
|
||||
|
||||
+-----------------------------+--------------------------------------------------------+
|
||||
| States | Restriction of selecting a boot app in bootloader |
|
||||
+=============================+========================================================+
|
||||
| ESP_OTA_IMG_VALID | None restriction. Will be selected. |
|
||||
+-----------------------------+--------------------------------------------------------+
|
||||
| ESP_OTA_IMG_UNDEFINED | None restriction. Will be selected. |
|
||||
+-----------------------------+--------------------------------------------------------+
|
||||
| ESP_OTA_IMG_INVALID | Will not be selected. |
|
||||
+-----------------------------+--------------------------------------------------------+
|
||||
| ESP_OTA_IMG_ABORTED | Will not be selected. |
|
||||
+-----------------------------+--------------------------------------------------------+
|
||||
| ESP_OTA_IMG_NEW | If :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option |
|
||||
| | is set it will be selected only once. In bootloader |
|
||||
| | the state immediately changes to |
|
||||
| | ``ESP_OTA_IMG_PENDING_VERIFY``. |
|
||||
+-----------------------------+--------------------------------------------------------+
|
||||
| ESP_OTA_IMG_PENDING_VERIFY | If :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option |
|
||||
| | is set it will not be selected and the state will |
|
||||
| | change to ``ESP_OTA_IMG_ABORTED``. |
|
||||
+-----------------------------+--------------------------------------------------------+
|
||||
============================= ======================================================================
|
||||
States Restriction of selecting a boot app in bootloader
|
||||
============================= ======================================================================
|
||||
ESP_OTA_IMG_VALID None restriction. Will be selected.
|
||||
ESP_OTA_IMG_UNDEFINED None restriction. Will be selected.
|
||||
ESP_OTA_IMG_INVALID Will not be selected.
|
||||
ESP_OTA_IMG_ABORTED Will not be selected.
|
||||
ESP_OTA_IMG_NEW If :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is set it will
|
||||
be selected only once. In bootloader the state immediately changes to
|
||||
``ESP_OTA_IMG_PENDING_VERIFY``.
|
||||
ESP_OTA_IMG_PENDING_VERIFY If :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is set it will
|
||||
not be selected and the state will change to ``ESP_OTA_IMG_ABORTED``.
|
||||
============================= ======================================================================
|
||||
|
||||
If :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is not enabled (by default), then the use of the following functions :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` and :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` are optional, and ``ESP_OTA_IMG_NEW`` and ``ESP_OTA_IMG_PENDING_VERIFY`` states are not used.
|
||||
|
||||
@@ -118,8 +102,7 @@ A brief description of where the states are set:
|
||||
|
||||
* ``ESP_OTA_IMG_VALID`` state is set by :cpp:func:`esp_ota_mark_app_valid_cancel_rollback` function.
|
||||
* ``ESP_OTA_IMG_UNDEFINED`` state is set by :cpp:func:`esp_ota_set_boot_partition` function if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is not enabled.
|
||||
* ``ESP_OTA_IMG_NEW`` state is set by :cpp:func:`esp_ota_set_boot_partition` function if
|
||||
:ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is enabled.
|
||||
* ``ESP_OTA_IMG_NEW`` state is set by :cpp:func:`esp_ota_set_boot_partition` function if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is enabled.
|
||||
* ``ESP_OTA_IMG_INVALID`` state is set by :cpp:func:`esp_ota_mark_app_invalid_rollback_and_reboot` function.
|
||||
* ``ESP_OTA_IMG_ABORTED`` state is set if there was no confirmation of the application operability and occurs reboots (if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is enabled).
|
||||
* ``ESP_OTA_IMG_PENDING_VERIFY`` state is set in a bootloader if :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` option is enabled and selected app has ``ESP_OTA_IMG_NEW`` state.
|
||||
@@ -133,7 +116,6 @@ Anti-rollback prevents rollback to application with security version lower than
|
||||
|
||||
This function works if set :ref:`CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK` option. In the bootloader, when selecting a bootable application, an additional security version check is added which is on the chip and in the application image. The version in the bootable firmware must be greater than or equal to the version in the chip.
|
||||
|
||||
|
||||
:ref:`CONFIG_BOOTLOADER_APP_ANTI_ROLLBACK` and :ref:`CONFIG_BOOTLOADER_APP_ROLLBACK_ENABLE` options are used together. In this case, rollback is possible only on the security version which is equal or higher than the version in the chip.
|
||||
|
||||
|
||||
@@ -151,7 +133,7 @@ A typical anti-rollback scheme is
|
||||
|
||||
Recommendation:
|
||||
|
||||
If you want to avoid the download/erase overhead in case of the app from the server has security version lower then running app you have to get ``new_app_info.secure_version`` from the first package of an image and compare it with the secure version of efuse. Use ``esp_efuse_check_secure_version(new_app_info.secure_version)`` function if it is true then continue downloading otherwise abort.
|
||||
If you want to avoid the download/erase overhead in case of the app from the server has security version lower then running app, you have to get ``new_app_info.secure_version`` from the first package of an image and compare it with the secure version of efuse. Use ``esp_efuse_check_secure_version(new_app_info.secure_version)`` function if it is true then continue downloading otherwise abort.
|
||||
|
||||
.. code-block:: c
|
||||
|
||||
@@ -220,8 +202,7 @@ The component `app_update` provides a tool :component_file:`otatool.py<app_updat
|
||||
- write to OTA partition (write_ota_partition)
|
||||
- read contents of OTA partition (read_ota_partition)
|
||||
|
||||
The tool can either be imported and used from another Python script or invoked from shell script for users wanting to perform operation programmatically. This is facilitated by the tool's Python API
|
||||
and command-line interface, respectively.
|
||||
The tool can either be imported and used from another Python script or invoked from shell script for users wanting to perform operation programmatically. This is facilitated by the tool's Python API and command-line interface, respectively.
|
||||
|
||||
Python API
|
||||
^^^^^^^^^^
|
||||
@@ -321,6 +302,3 @@ API Reference
|
||||
-------------
|
||||
|
||||
.. include-build-file:: inc/esp_ota_ops.inc
|
||||
|
||||
|
||||
|
||||
|
||||
Reference in New Issue
Block a user