chore: import upstream snapshot with attribution

examples/system/console/basic/CMakeLists.txt

@@ -0,0 +1,8 @@
+# The following lines of boilerplate have to be in your project's CMakeLists
+# in this exact order for cmake to work correctly
+cmake_minimum_required(VERSION 3.22)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+# "Trim" the build. Include the minimal set of components, main, and anything it depends on.
+idf_build_set_property(MINIMAL_BUILD ON)
+project(console)

examples/system/console/basic/README.md

@@ -0,0 +1,156 @@
+| Supported Targets | ESP32 | ESP32-C2 | ESP32-C3 | ESP32-C5 | ESP32-C6 | ESP32-C61 | ESP32-H2 | ESP32-H21 | ESP32-H4 | ESP32-P4 | ESP32-S2 | ESP32-S3 | ESP32-S31 |
+| ----------------- | ----- | -------- | -------- | -------- | -------- | --------- | -------- | --------- | -------- | -------- | -------- | -------- | --------- |
+
+# Basic Console Example (`esp_console_repl`)
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example illustrates the usage of the REPL (Read-Eval-Print Loop) APIs of the [Console Component](https://docs.espressif.com/projects/esp-idf/en/latest/esp32/api-reference/system/console.html#console) to create an interactive shell on the ESP chip. The interactive shell running on the ESP chip can then be controlled/interacted with over a serial interface. This example supports UART and USB interfaces.
+
+The interactive shell implemented in this example contains a wide variety of commands, and can act as a basis for applications that require a command-line interface (CLI).
+
+Compared to the [advanced console example](../advanced), this example requires less code to initialize and run the console. `esp_console_repl` API handles most of the details. If you'd like to customize the way console works (for example, process console commands in an existing task), please check the advanced console example.
+
+## How to use example
+
+This example can be used on boards with UART and USB interfaces. The sections below explain how to set up the board and configure the example.
+
+### Using with UART
+
+When UART interface is used, this example should run on any commonly available Espressif development board. UART interface is enabled by default (`CONFIG_ESP_CONSOLE_UART_DEFAULT` option in menuconfig). No extra configuration is required.
+
+### Using with USB_SERIAL_JTAG
+
+*NOTE: We recommend to disable the secondary console output on chips with USB_SERIAL_JTAG since the secondary serial is output-only and would not be very useful when using a console application. This is why the secondary console output is deactivated per default (CONFIG_ESP_CONSOLE_SECONDARY_NONE=y)*
+
+On chips with USB_SERIAL_JTAG peripheral, console example can be used over the USB serial port.
+
+* First, connect the USB cable to the USB_SERIAL_JTAG interface.
+* Second, run `idf.py menuconfig` and enable `CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG` option.
+
+For more details about connecting and configuring USB_SERIAL_JTAG (including pin numbers), see the IDF Programming Guide:
+* [ESP32-C3 USB_SERIAL_JTAG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32c3/api-guides/usb-serial-jtag-console.html)
+* [ESP32-S3 USB_SERIAL_JTAG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/api-guides/usb-serial-jtag-console.html)
+
+### Using with USB CDC (USB_OTG peripheral)
+
+USB_OTG peripheral can also provide a USB serial port which works with this example.
+
+* First, connect the USB cable to the USB_OTG peripheral interface.
+* Second, run `idf.py menuconfig` and enable `CONFIG_ESP_CONSOLE_USB_CDC` option.
+
+For more details about connecting and configuring USB_OTG (including pin numbers), see the IDF Programming Guide:
+* [ESP32-S2 USB_OTG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s2/api-guides/usb-otg-console.html)
+* [ESP32-S3 USB_OTG](https://docs.espressif.com/projects/esp-idf/en/stable/esp32s3/api-guides/usb-otg-console.html)
+
+### Other configuration options
+
+This example has an option to store the command history in Flash. This option is enabled by default.
+
+To disable this, run `idf.py menuconfig` and disable `CONFIG_CONSOLE_STORE_HISTORY` option.
+
+### Build and Flash
+
+Build the project and flash it to the board, then run monitor tool to view serial output:
+
+```
+idf.py -p PORT flash monitor
+```
+
+(Replace PORT with the name of the serial port to use.)
+
+(To exit the serial monitor, type ``Ctrl-]``.)
+
+See the Getting Started Guide for full steps to configure and use ESP-IDF to build projects.
+
+## Example Output
+
+Enter the `help` command get a full list of all available commands. The following is a sample session of the Console Example where a variety of commands provided by the Console Example are used.
+
+On ESP32, GPIO15 may be connected to GND to remove the boot log output.
+
+```
+This is an example of ESP-IDF console component.
+Type 'help' to get the list of commands.
+Use UP/DOWN arrows to navigate through command history.
+Press TAB when typing command name to auto-complete.
+[esp32]> help
+help
+  Print the list of registered commands
+
+free
+  Get the total size of heap memory available
+
+restart
+  Restart the program
+
+deep_sleep  [-t <t>] [--io=<n>] [--io_level=<0|1>]
+  Enter deep sleep mode. Two wakeup modes are supported: timer and GPIO. If no
+  wakeup option is specified, will sleep indefinitely.
+  -t, --time=<t>  Wake up time, ms
+      --io=<n>  If specified, wakeup using GPIO with given number
+  --io_level=<0|1>  GPIO level to trigger wakeup
+
+join  [--timeout=<t>] <ssid> [<pass>]
+  Join WiFi AP as a station
+  --timeout=<t>  Connection timeout, ms
+        <ssid>  SSID of AP
+        <pass>  PSK of AP
+
+[esp32]> free
+257200
+[esp32]> deep_sleep -t 1000
+I (146929) deep_sleep: Enabling timer wakeup, timeout=1000000us
+I (619) heap_init: Initializing. RAM available for dynamic allocation:
+I (620) heap_init: At 3FFAE2A0 len 00001D60 (7 KiB): DRAM
+I (626) heap_init: At 3FFB7EA0 len 00028160 (160 KiB): DRAM
+I (645) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
+I (664) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
+I (684) heap_init: At 40093EA8 len 0000C158 (48 KiB): IRAM
+
+This is an example of ESP-IDF console component.
+Type 'help' to get the list of commands.
+Use UP/DOWN arrows to navigate through command history.
+Press TAB when typing command name to auto-complete.
+[esp32]> join --timeout 10000 test_ap test_password
+I (182639) connect: Connecting to 'test_ap'
+I (184619) connect: Connected
+[esp32]> free
+212328
+[esp32]> restart
+I (205639) restart: Restarting
+I (616) heap_init: Initializing. RAM available for dynamic allocation:
+I (617) heap_init: At 3FFAE2A0 len 00001D60 (7 KiB): DRAM
+I (623) heap_init: At 3FFB7EA0 len 00028160 (160 KiB): DRAM
+I (642) heap_init: At 3FFE0440 len 00003BC0 (14 KiB): D/IRAM
+I (661) heap_init: At 3FFE4350 len 0001BCB0 (111 KiB): D/IRAM
+I (681) heap_init: At 40093EA8 len 0000C158 (48 KiB): IRAM
+
+This is an example of ESP-IDF console component.
+Type 'help' to get the list of commands.
+Use UP/DOWN arrows to navigate through command history.
+Press TAB when typing command name to auto-complete.
+[esp32]>
+
+```
+
+## Troubleshooting
+
+### Line Endings
+
+The line endings in the Console Example are configured to match particular serial monitors. Therefore, if the following log output appears, consider using a different serial monitor (e.g. Putty for Windows) or see [console/advanced](../advanced/main/console_settings.c) for how to initialize a console with custom settings.
+
+```
+This is an example of ESP-IDF console component.
+Type 'help' to get the list of commands.
+Use UP/DOWN arrows to navigate through command history.
+Press TAB when typing command name to auto-complete.
+Your terminal application does not support escape sequences.
+Line editing and history features are disabled.
+On Windows, try using Windows Terminal or Putty instead.
+esp32>
+```
+
+### Escape Sequences on Windows 10
+
+When using the default command line or PowerShell on Windows 10, you may see a message indicating that the console does not support escape sequences, as shown in the above output. To avoid such issues, it is recommended to run the serial monitor under [Windows Terminal](https://en.wikipedia.org/wiki/Windows_Terminal), which supports all required escape sequences for the app, unlike the default terminal. The main escape sequence of concern is the Device Status Report (`0x1b[5n`), which is used to check terminal capabilities. Any response to this sequence indicates support. This should not be an issue on Windows 11, where Windows Terminal is the default.

examples/system/console/basic/main/CMakeLists.txt

@@ -0,0 +1,3 @@
+idf_component_register(SRCS "console_example_main.c"
+                       PRIV_REQUIRES fatfs
+                       INCLUDE_DIRS ".")

examples/system/console/basic/main/Kconfig.projbuild

@@ -0,0 +1,18 @@
+menu "Example Configuration"
+
+    config CONSOLE_STORE_HISTORY
+        bool "Store command history in flash"
+        default y
+        help
+            Linenoise line editing library provides functions to save and load
+            command history. If this option is enabled, initializes a FAT filesystem
+            and uses it to store command history.
+
+    config CONSOLE_MAX_COMMAND_LINE_LENGTH
+        int "Maximum command line length"
+        default 1024
+        help
+            This value marks the maximum length of a single command line. Once it is
+            reached, no more characters will be accepted by the console.
+
+endmenu

examples/system/console/basic/main/console_example_main.c

@@ -0,0 +1,107 @@
+/* Basic console example (esp_console_repl API)
+
+   This example code is in the Public Domain (or CC0 licensed, at your option.)
+
+   Unless required by applicable law or agreed to in writing, this
+   software is distributed on an "AS IS" BASIS, WITHOUT WARRANTIES OR
+   CONDITIONS OF ANY KIND, either express or implied.
+*/
+
+#include <stdio.h>
+#include <string.h>
+#include "esp_system.h"
+#include "esp_log.h"
+#include "esp_console.h"
+#include "esp_vfs_dev.h"
+#include "esp_vfs_fat.h"
+#include "nvs.h"
+#include "nvs_flash.h"
+#include "cmd_system.h"
+#include "cmd_wifi.h"
+#include "cmd_nvs.h"
+
+/*
+ * We warn if a secondary serial console is enabled. A secondary serial console is always output-only and
+ * hence not very useful for interactive console applications. If you encounter this warning, consider disabling
+ * the secondary serial console in menuconfig unless you know what you are doing.
+ */
+#if SOC_USB_SERIAL_JTAG_SUPPORTED
+#if !CONFIG_ESP_CONSOLE_SECONDARY_NONE
+#warning "A secondary serial console is not useful when using the console component. Please disable it in menuconfig."
+#endif
+#endif
+
+static const char* TAG = "example";
+#define PROMPT_STR CONFIG_IDF_TARGET
+
+/* Console command history can be stored to and loaded from a file.
+ * The easiest way to do this is to use FATFS filesystem on top of
+ * wear_levelling library.
+ */
+#if CONFIG_CONSOLE_STORE_HISTORY
+
+#define MOUNT_PATH "/data"
+#define HISTORY_PATH MOUNT_PATH "/history.txt"
+
+static void initialize_filesystem(void)
+{
+    static wl_handle_t wl_handle;
+    const esp_vfs_fat_mount_config_t mount_config = {
+            .max_files = 4,
+            .format_if_mount_failed = true
+    };
+    esp_err_t err = esp_vfs_fat_spiflash_mount_rw_wl(MOUNT_PATH, "storage", &mount_config, &wl_handle);
+    if (err != ESP_OK) {
+        ESP_LOGE(TAG, "Failed to mount FATFS (%s)", esp_err_to_name(err));
+        return;
+    }
+}
+#endif // CONFIG_STORE_HISTORY
+
+static void initialize_nvs(void)
+{
+    esp_err_t err = nvs_flash_init();
+    if (err == ESP_ERR_NVS_NO_FREE_PAGES || err == ESP_ERR_NVS_NEW_VERSION_FOUND) {
+        ESP_ERROR_CHECK( nvs_flash_erase() );
+        err = nvs_flash_init();
+    }
+    ESP_ERROR_CHECK(err);
+}
+
+void app_main(void)
+{
+    esp_console_repl_t *repl = NULL;
+    esp_console_repl_config_t repl_config = ESP_CONSOLE_REPL_CONFIG_DEFAULT();
+    /* Prompt to be printed before each line.
+     * This can be customized, made dynamic, etc.
+     */
+    repl_config.prompt = PROMPT_STR ">";
+    repl_config.max_cmdline_length = CONFIG_CONSOLE_MAX_COMMAND_LINE_LENGTH;
+
+    initialize_nvs();
+
+#if CONFIG_CONSOLE_STORE_HISTORY
+    initialize_filesystem();
+    repl_config.history_save_path = HISTORY_PATH;
+    ESP_LOGI(TAG, "Command history enabled");
+#else
+    ESP_LOGI(TAG, "Command history disabled");
+#endif
+
+    /* Register commands */
+    esp_console_register_help_command();
+    register_system_common();
+#if SOC_LIGHT_SLEEP_SUPPORTED
+    register_system_light_sleep();
+#endif
+#if SOC_DEEP_SLEEP_SUPPORTED
+    register_system_deep_sleep();
+#endif
+#if (CONFIG_ESP_WIFI_ENABLED || CONFIG_ESP_HOST_WIFI_ENABLED)
+    register_wifi();
+#endif
+    register_nvs();
+
+    ESP_ERROR_CHECK(esp_console_new_repl_stdio(&repl_config, &repl));
+    ESP_ERROR_CHECK(esp_console_start_repl(repl));
+}

examples/system/console/basic/main/idf_component.yml

@@ -0,0 +1,7 @@
+dependencies:
+  cmd_system:
+    path: ${IDF_PATH}/examples/system/console/advanced/components/cmd_system
+  cmd_nvs:
+    path: ${IDF_PATH}/examples/system/console/advanced/components/cmd_nvs
+  cmd_wifi:
+    path: ${IDF_PATH}/examples/system/console/advanced/components/cmd_wifi

examples/system/console/basic/partitions_example.csv

@@ -0,0 +1,6 @@
+# Name,   Type, SubType, Offset,  Size, Flags
+# Note: if you have increased the bootloader size, make sure to update the offsets to avoid overlap
+nvs,      data, nvs,     0x9000,  0x6000,
+phy_init, data, phy,     0xf000,  0x1000,
+factory,  app,  factory, 0x10000, 0x110000,
+storage,  data, fat,     ,        1M,

examples/system/console/basic/pytest_console_basic.py

@@ -0,0 +1,22 @@
+# SPDX-FileCopyrightText: 2021-2025 Espressif Systems (Shanghai) CO LTD
+# SPDX-License-Identifier: CC0-1.0
+import pytest
+from pytest_embedded import Dut
+from pytest_embedded_idf.utils import idf_parametrize
+
+
+@pytest.mark.generic
+@pytest.mark.parametrize(
+    'config',
+    [
+        'history',
+        'nohistory',
+    ],
+    indirect=True,
+)
+@idf_parametrize('target', ['esp32', 'esp32c3'], indirect=['target'])
+def test_console_basic(config: str, dut: Dut) -> None:
+    if config == 'history':
+        dut.expect('Command history enabled')
+    elif config == 'nohistory':
+        dut.expect('Command history disabled')

examples/system/console/basic/sdkconfig.ci.history

@@ -0,0 +1 @@
+CONFIG_CONSOLE_STORE_HISTORY=y

examples/system/console/basic/sdkconfig.ci.nohistory

@@ -0,0 +1 @@
+CONFIG_CONSOLE_STORE_HISTORY=n

examples/system/console/basic/sdkconfig.defaults

@@ -0,0 +1,20 @@
+# Reduce bootloader log verbosity
+CONFIG_BOOTLOADER_LOG_LEVEL_WARN=y
+CONFIG_BOOTLOADER_LOG_LEVEL=2
+
+# Increase main task stack size
+CONFIG_ESP_MAIN_TASK_STACK_SIZE=7168
+
+# Enable filesystem
+CONFIG_PARTITION_TABLE_CUSTOM=y
+CONFIG_PARTITION_TABLE_CUSTOM_FILENAME="partitions_example.csv"
+CONFIG_PARTITION_TABLE_FILENAME="partitions_example.csv"
+
+# Enable FreeRTOS stats formatting functions, needed for 'tasks' command
+CONFIG_FREERTOS_USE_TRACE_FACILITY=y
+CONFIG_FREERTOS_USE_STATS_FORMATTING_FUNCTIONS=y
+
+CONFIG_ESPTOOLPY_FLASHSIZE_4MB=y
+
+# On chips with USB serial, disable secondary console which does not make sense when using console component
+CONFIG_ESP_CONSOLE_SECONDARY_NONE=y