Merge remote-tracking branch 'origin/master' into feature/github-7022

examples/system/console/advanced/example_test.py

@@ -0,0 +1,22 @@
+# type: ignore
+from __future__ import print_function
+
+import ttfw_idf
+
+
+@ttfw_idf.idf_example_test(env_tag='Example_GENERIC', target=['esp32', 'esp32c3'])
+def test_examples_system_console_advanced(env, _):
+    dut = env.get_dut('console_example', 'examples/system/console/advanced', app_config_name='history')
+    print('Using binary path: {}'.format(dut.app.binary_path))
+    dut.start_app()
+    dut.expect('Command history enabled')
+    env.close_dut(dut.name)
+
+    dut = env.get_dut('console_example', 'examples/system/console/advanced', app_config_name='nohistory')
+    print('Using binary path: {}'.format(dut.app.binary_path))
+    dut.start_app()
+    dut.expect('Command history disabled')
+
+
+if __name__ == '__main__':
+    test_examples_system_console_advanced()

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

@@ -121,6 +121,9 @@ static void initialize_console(void)
     /* Set command history size */
     linenoiseHistorySetMaxLen(100);
 
+    /* Set command maximum length */
+    linenoiseSetMaxLineLen(console_config.max_cmdline_length);
+
     /* Don't return empty lines */
     linenoiseAllowEmpty(false);
 

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

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

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

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

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.5)
+
+set(EXTRA_COMPONENT_DIRS $ENV{IDF_PATH}/examples/system/console/advanced/components)
+
+include($ENV{IDF_PATH}/tools/cmake/project.cmake)
+project(console)

examples/system/console/basic/Makefile

@@ -0,0 +1,10 @@
+#
+# This is a project Makefile. It is assumed the directory this Makefile resides in is a
+# project subdirectory.
+#
+
+PROJECT_NAME := console
+
+EXTRA_COMPONENT_DIRS := $(IDF_PATH)/examples/system/console/advanced/components
+
+include $(IDF_PATH)/make/project.mk

examples/system/console/basic/README.md

@@ -0,0 +1,151 @@
+# Console Example
+
+(See the README.md file in the upper level 'examples' directory for more information about examples.)
+
+This example illustrates the usage of the [Console Component](https://docs.espressif.com/projects/esp-idf/en/latest/api-guides/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 port (UART).
+
+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).
+
+## How to use example
+
+### Hardware Required
+
+This example should be able to run on any commonly available Espressif development board.
+
+### Configure the project
+
+```
+idf.py menuconfig
+```
+
+* Enable/disable `Example Configuration > Store command history in flash` as necessary
+
+### 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. Note that GPIO15 is 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 modify the example's [UART configuration](#Configuring-UART-and-VFS).
+
+```
+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 Putty instead.
+esp32>
+```
+
+## Example Breakdown
+
+### Configuring UART
+
+The ``initialize_console()`` function in the example configures some aspects of UART relevant to the operation of the console. 
+
+- **Line Endings**: The default line endings are configured to match those expected/generated by common serial monitor programs, such as `screen`, `minicom`, and the `idf_monitor.py` included in the SDK. The default behavior for these commands are:
+    - When 'enter' key is pressed on the keyboard, `CR` (0x13) code is sent to the serial device.
+    - To move the cursor to the beginning of the next line, serial device needs to send `CR LF` (0x13 0x10) sequence.
+
+### Line editing
+
+The main source file of the example illustrates how to use `linenoise` library, including line completion, hints, and history.
+
+### Commands
+
+Several commands are registered using `esp_console_cmd_register()` function. See the `register_wifi()` and `register_system()` functions in `cmd_wifi.c` and `cmd_system.c` files.
+
+### Command handling
+
+Main loop inside `app_main()` function illustrates how to use `linenoise` and `esp_console_run()` to implement read/eval loop.
+
+### Argument parsing
+
+Several commands implemented in `cmd_wifi.c` and `cmd_system.c` use the Argtable3 library to parse and check the arguments.
+
+### Command history
+
+Each time a new command line is obtained from `linenoise`, it is written into history and the history is saved into a file in flash memory. On reset, history is initialized from that file.

examples/system/console/basic/example_test.py

@@ -1,21 +1,22 @@
+# type: ignore
 from __future__ import print_function
 
 import ttfw_idf
 
 
 @ttfw_idf.idf_example_test(env_tag='Example_GENERIC', target=['esp32', 'esp32c3'])
-def test_examples_system_console(env, extra_data):
-    dut = env.get_dut('console_example', 'examples/system/console', app_config_name='history')
+def test_examples_system_console_basic(env, _):
+    dut = env.get_dut('console_example', 'examples/system/console/basic', app_config_name='history')
     print('Using binary path: {}'.format(dut.app.binary_path))
     dut.start_app()
     dut.expect('Command history enabled')
     env.close_dut(dut.name)
 
-    dut = env.get_dut('console_example', 'examples/system/console', app_config_name='nohistory')
+    dut = env.get_dut('console_example', 'examples/system/console/basic', app_config_name='nohistory')
     print('Using binary path: {}'.format(dut.app.binary_path))
     dut.start_app()
     dut.expect('Command history disabled')
 
 
 if __name__ == '__main__':
-    test_examples_system_console()
+    test_examples_system_console_basic()

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

@@ -0,0 +1,3 @@
+idf_component_register(SRCS "cmd_wifi.c"
+                            "console_example_main.c"
+                    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, initalizes 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/cmd_decl.h

@@ -0,0 +1,21 @@
+/* Console example — declarations of command registration functions.
+
+   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.
+*/
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+#include "cmd_system.h"
+#include "cmd_wifi.h"
+#include "cmd_nvs.h"
+
+#ifdef __cplusplus
+}
+#endif

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

@@ -0,0 +1,132 @@
+/* Console example — WiFi commands
+
+   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_log.h"
+#include "esp_console.h"
+#include "argtable3/argtable3.h"
+#include "cmd_decl.h"
+#include "freertos/FreeRTOS.h"
+#include "freertos/event_groups.h"
+#include "esp_wifi.h"
+#include "esp_netif.h"
+#include "esp_event.h"
+#include "cmd_wifi.h"
+
+#define JOIN_TIMEOUT_MS (10000)
+
+static EventGroupHandle_t wifi_event_group;
+const int CONNECTED_BIT = BIT0;
+
+
+static void event_handler(void* arg, esp_event_base_t event_base,
+                                int32_t event_id, void* event_data)
+{
+    if (event_base == WIFI_EVENT && event_id == WIFI_EVENT_STA_DISCONNECTED) {
+        esp_wifi_connect();
+        xEventGroupClearBits(wifi_event_group, CONNECTED_BIT);
+    } else if (event_base == IP_EVENT && event_id == IP_EVENT_STA_GOT_IP) {
+        xEventGroupSetBits(wifi_event_group, CONNECTED_BIT);
+    }
+}
+
+static void initialise_wifi(void)
+{
+    esp_log_level_set("wifi", ESP_LOG_WARN);
+    static bool initialized = false;
+    if (initialized) {
+        return;
+    }
+    ESP_ERROR_CHECK(esp_netif_init());
+    wifi_event_group = xEventGroupCreate();
+    ESP_ERROR_CHECK(esp_event_loop_create_default());
+    esp_netif_t *ap_netif = esp_netif_create_default_wifi_ap();
+    assert(ap_netif);
+    esp_netif_t *sta_netif = esp_netif_create_default_wifi_sta();
+    assert(sta_netif);
+    wifi_init_config_t cfg = WIFI_INIT_CONFIG_DEFAULT();
+    ESP_ERROR_CHECK( esp_wifi_init(&cfg) );
+    ESP_ERROR_CHECK( esp_event_handler_register(WIFI_EVENT, WIFI_EVENT_STA_DISCONNECTED, &event_handler, NULL) );
+    ESP_ERROR_CHECK( esp_event_handler_register(IP_EVENT, IP_EVENT_STA_GOT_IP, &event_handler, NULL) );
+    ESP_ERROR_CHECK( esp_wifi_set_storage(WIFI_STORAGE_RAM) );
+    ESP_ERROR_CHECK( esp_wifi_set_mode(WIFI_MODE_NULL) );
+    ESP_ERROR_CHECK( esp_wifi_start() );
+    initialized = true;
+}
+
+static bool wifi_join(const char *ssid, const char *pass, int timeout_ms)
+{
+    initialise_wifi();
+    wifi_config_t wifi_config = { 0 };
+    strlcpy((char *) wifi_config.sta.ssid, ssid, sizeof(wifi_config.sta.ssid));
+    if (pass) {
+        strlcpy((char *) wifi_config.sta.password, pass, sizeof(wifi_config.sta.password));
+    }
+
+    ESP_ERROR_CHECK( esp_wifi_set_mode(WIFI_MODE_STA) );
+    ESP_ERROR_CHECK( esp_wifi_set_config(WIFI_IF_STA, &wifi_config) );
+    esp_wifi_connect();
+
+    int bits = xEventGroupWaitBits(wifi_event_group, CONNECTED_BIT,
+                                   pdFALSE, pdTRUE, timeout_ms / portTICK_PERIOD_MS);
+    return (bits & CONNECTED_BIT) != 0;
+}
+
+/** Arguments used by 'join' function */
+static struct {
+    struct arg_int *timeout;
+    struct arg_str *ssid;
+    struct arg_str *password;
+    struct arg_end *end;
+} join_args;
+
+static int connect(int argc, char **argv)
+{
+    int nerrors = arg_parse(argc, argv, (void **) &join_args);
+    if (nerrors != 0) {
+        arg_print_errors(stderr, join_args.end, argv[0]);
+        return 1;
+    }
+    ESP_LOGI(__func__, "Connecting to '%s'",
+             join_args.ssid->sval[0]);
+
+    /* set default value*/
+    if (join_args.timeout->count == 0) {
+        join_args.timeout->ival[0] = JOIN_TIMEOUT_MS;
+    }
+
+    bool connected = wifi_join(join_args.ssid->sval[0],
+                               join_args.password->sval[0],
+                               join_args.timeout->ival[0]);
+    if (!connected) {
+        ESP_LOGW(__func__, "Connection timed out");
+        return 1;
+    }
+    ESP_LOGI(__func__, "Connected");
+    return 0;
+}
+
+void register_wifi(void)
+{
+    join_args.timeout = arg_int0(NULL, "timeout", "<t>", "Connection timeout, ms");
+    join_args.ssid = arg_str1(NULL, NULL, "<ssid>", "SSID of AP");
+    join_args.password = arg_str0(NULL, NULL, "<pass>", "PSK of AP");
+    join_args.end = arg_end(2);
+
+    const esp_console_cmd_t join_cmd = {
+        .command = "join",
+        .help = "Join WiFi AP as a station",
+        .hint = NULL,
+        .func = &connect,
+        .argtable = &join_args
+    };
+
+    ESP_ERROR_CHECK( esp_console_cmd_register(&join_cmd) );
+}

examples/system/console/basic/main/cmd_wifi.h

@@ -0,0 +1,20 @@
+/* Console example — declarations of command registration functions.
+
+   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.
+*/
+#pragma once
+
+#ifdef __cplusplus
+extern "C" {
+#endif
+
+// Register WiFi functions
+void register_wifi(void);
+
+#ifdef __cplusplus
+}
+#endif

examples/system/console/basic/main/component.mk

@@ -0,0 +1,4 @@
+#
+# "main" pseudo-component makefile.
+#
+# (Uses default behaviour of compiling all source files in directory, adding 'include' to include path.)

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

@@ -0,0 +1,95 @@
+/* Console example
+
+   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 "driver/uart.h"
+#include "linenoise/linenoise.h"
+#include "argtable3/argtable3.h"
+#include "cmd_decl.h"
+#include "esp_vfs_fat.h"
+#include "nvs.h"
+#include "nvs_flash.h"
+
+#ifdef CONFIG_ESP_CONSOLE_USB_CDC
+#error This example is incompatible with USB CDC console. Please try "console_usb" example instead.
+#endif // CONFIG_ESP_CONSOLE_USB_CDC
+
+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(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();
+    esp_console_dev_uart_config_t uart_config = ESP_CONSOLE_DEV_UART_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();
+    register_wifi();
+    register_nvs();
+
+    ESP_ERROR_CHECK(esp_console_new_repl_uart(&uart_config, &repl_config, &repl));
+
+    ESP_ERROR_CHECK(esp_console_start_repl(repl));
+}

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, 1M,
+storage,  data, fat,     ,        1M,

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,17 @@
+# 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

examples/system/console/sdkconfig.ci.history

@@ -1,4 +0,0 @@
-CONFIG_STORE_HISTORY=y
-# IDF-3090
-CONFIG_ESP32C3_REV_MIN_0=y
-CONFIG_ESP32C3_REV_MIN=0

examples/system/console/sdkconfig.ci.nohistory

@@ -1,4 +0,0 @@
-CONFIG_STORE_HISTORY=n
-# IDF-3090
-CONFIG_ESP32C3_REV_MIN_0=y
-CONFIG_ESP32C3_REV_MIN=0