feat(esp_repl): Add esp_linenoise and esp_commands dependencies

Author: SoucheSouche

esp_repl/CMakeLists.txt

@@ -4,5 +4,4 @@ set(srcs "esp_repl.c")
 
 idf_component_register(
                     SRCS ${srcs}
-                    INCLUDE_DIRS include
-                    PRIV_INCLUDE_DIRS private_include)
+                    INCLUDE_DIRS include)

esp_repl/esp_repl.c

@@ -1,3 +1,4 @@
+
 /*
  * SPDX-FileCopyrightText: 2025 Espressif Systems (Shanghai) CO LTD
  *
@@ -9,7 +10,8 @@
 #include "freertos/semphr.h"
 #include "esp_repl.h"
 #include "esp_err.h"
-
+#include "esp_commands.h"
+#include "esp_linenoise.h"
 typedef enum {
     ESP_REPL_STATE_RUNNING,
     ESP_REPL_STATE_STOPPED
@@ -34,8 +36,8 @@ typedef struct esp_repl_instance {
 
 esp_err_t esp_repl_create(esp_repl_instance_handle_t *handle, const esp_repl_config_t *config)
 {
-    if ((config->executor.func == NULL) ||
-            (config->reader.func == NULL) ||
+    if ((config->linenoise_handle == NULL) ||
+            (config->command_set_handle == NULL) ||
             (config->max_cmd_line_size == 0)) {
         return ESP_ERR_INVALID_ARG;
     }
@@ -140,11 +142,22 @@ void esp_repl(esp_repl_instance_handle_t handle)
      * function is called. */
     xSemaphoreTake(state->mux, portMAX_DELAY);
 
+    esp_linenoise_handle_t l_hdl = config->linenoise_handle;
+    esp_command_set_handle_t c_set = config->command_set_handle;
+
     /* REPL loop */
     while (state->state == ESP_REPL_STATE_RUNNING) {
 
         /* try to read a command line */
-        const esp_err_t read_ret = config->reader.func(config->reader.ctx, cmd_line, cmd_line_size);
+        const esp_err_t read_ret = esp_linenoise_get_line(l_hdl, cmd_line, cmd_line_size);
+
+        /* Add the command to the history */
+        esp_linenoise_history_add(l_hdl, cmd_line);
+
+        /* Save command history to filesystem */
+        if (config->history_save_path) {
+            esp_linenoise_history_save(l_hdl, config->history_save_path);
+        }
 
         /* forward the raw command line to the pre executor callback (e.g., save in history).
          * this callback is not necessary for the user to register, continue if it isn't */
@@ -159,7 +172,7 @@ void esp_repl(esp_repl_instance_handle_t handle)
 
         /* try to run the command */
         int cmd_func_ret;
-        const esp_err_t exec_ret = config->executor.func(config->executor.ctx, cmd_line, &cmd_func_ret);
+        const esp_err_t exec_ret = esp_commands_execute(c_set, cmd_line, &cmd_func_ret);
 
         /* forward the raw command line to the post executor callback (e.g., save in history).
          * this callback is not necessary for the user to register, continue if it isn't */

esp_repl/idf_component.yml

@@ -2,7 +2,12 @@ version: "1.0.0"
 description: "esp_repl - Read Eval Print Loop component"
 url: https://github.com/espressif/idf-extra-components/tree/master/esp_repl
 dependencies:
-  idf: ">=6.0"
+  SoucheSouche/test_esp_linenoise:
+    version: "*"
+    registry_url: https://components-staging.espressif.com
+  SoucheSouche/test_esp_commands:
+    version: "*"
+    registry_url: https://components-staging.espressif.com
 sbom:
   manifests:
     - path: sbom_esp_repl.yml

esp_repl/include/esp_repl.h

@@ -11,31 +11,13 @@ extern "C" {
 
 #include <stdbool.h>
 #include "esp_err.h"
+#include "esp_linenoise.h"
 
 /**
  * @brief Handle to a REPL instance.
  */
 typedef struct esp_repl_instance *esp_repl_instance_handle_t;
 
-/**
- * @brief Function prototype for reading input for the REPL.
- *
- * @param ctx User-defined context pointer.
- * @param buf Buffer to store the read data.
- * @param buf_size Size of the buffer in bytes.
- *
- * @return ESP_OK on success, error code otherwise.
- */
-typedef esp_err_t (*esp_repl_reader_fn)(void *ctx, char *buf, size_t buf_size);
-
-/**
- * @brief Reader configuration structure for the REPL.
- */
-typedef struct esp_repl_reader {
-    esp_repl_reader_fn func; /**!< Function to read input */
-    void *ctx;               /**!< Context passed to the reader function */
-} esp_repl_reader_t;
-
 /**
  * @brief Function prototype called before executing a command.
  *
@@ -55,25 +37,6 @@ typedef struct esp_repl_pre_executor {
     void *ctx;                      /**!< Context passed to the pre-executor function */
 } esp_repl_pre_executor_t;
 
-/**
- * @brief Function prototype to execute a REPL command.
- *
- * @param ctx User-defined context pointer.
- * @param buf Null-terminated command string.
- * @param ret_val Pointer to store the command return value.
- *
- * @return ESP_OK on success, error code otherwise.
- */
-typedef esp_err_t (*esp_repl_executor_fn)(void *ctx, const char *buf, int *ret_val);
-
-/**
- * @brief Executor configuration structure for the REPL.
- */
-typedef struct esp_repl_executor {
-    esp_repl_executor_fn func; /**!< Function to execute commands */
-    void *ctx;                  /**!< Context passed to the executor function */
-} esp_repl_executor_t;
-
 /**
  * @brief Function prototype called after executing a command.
  *
@@ -133,13 +96,14 @@ typedef struct esp_repl_on_exit {
  * @brief Configuration structure to initialize a REPL instance.
  */
 typedef struct esp_repl_config {
-    size_t max_cmd_line_size;        /**!< Maximum allowed command line size */
-    esp_repl_reader_t reader;        /**!< Reader callback and context */
-    esp_repl_pre_executor_t pre_executor;   /**!< Pre-executor callback and context */
-    esp_repl_executor_t executor;           /**!< Executor callback and context */
-    esp_repl_post_executor_t post_executor; /**!< Post-executor callback and context */
-    esp_repl_on_stop_t on_stop;             /**!< Stop callback and context */
-    esp_repl_on_exit_t on_exit;             /**!< Exit callback and context */
+    esp_linenoise_handle_t linenoise_handle;    /**!< Handle to the esp_linenoise instance */
+    esp_command_set_handle_t command_set_handle;   /**!< Handle to a set of commands */
+    size_t max_cmd_line_size;                   /**!< Maximum allowed command line size */
+    const char *history_save_path;              /**!< Path to file to save the history */
+    esp_repl_pre_executor_t pre_executor;       /**!< Pre-executor callback and context */
+    esp_repl_post_executor_t post_executor;     /**!< Post-executor callback and context */
+    esp_repl_on_stop_t on_stop;                 /**!< Stop callback and context */
+    esp_repl_on_exit_t on_exit;                 /**!< Exit callback and context */
 } esp_repl_config_t;
 
 /**

esp_repl/test_apps/main/test_esp_repl.c

@@ -6,70 +6,159 @@
 
 #include <string.h>
 #include <stdio.h>
+#include <sys/socket.h>
 #include "freertos/FreeRTOS.h"
 #include "freertos/task.h"
 #include "freertos/semphr.h"
 #include "unity.h"
 #include "esp_repl.h"
+#include "esp_linenoise.h"
+#include "esp_commands.h"
 
-typedef struct esp_linenoise_dummy {
-    size_t value;
-} esp_linenoise_dummy_t;
-typedef struct esp_linenoise_dummy *esp_linenoise_handle_t;
 
-typedef struct esp_commands_dummy {
-    size_t value;
-} esp_commands_dummy_t;
-typedef struct esp_commands_dummy *esp_commands_handle_t;
+static int s_socket_fd[2];
+static size_t s_pre_executor_nb_of_calls = 0;
+static size_t s_post_executor_nb_of_calls = 0;
+static size_t s_on_stop_nb_of_calls = 0;
+static size_t s_on_exit_nb_of_calls = 0;
 
-esp_err_t test_reader_non_blocking(esp_linenoise_handle_t handle, char *buf, size_t buf_size)
+static void test_socket_setup(int socket_fd[2])
 {
-    return ESP_OK;
+    // 2 fd are generated, simulating the full-duplex
+    // communication between linenoise and the terminal
+    TEST_ASSERT_EQUAL(0, socketpair(AF_UNIX, SOCK_STREAM, 0, socket_fd));
+
+    // assure that the read will be blocking
+    int flags = fcntl(socket_fd[0], F_GETFL, 0);
+    flags &= ~O_NONBLOCK;
+    fcntl(socket_fd[0], F_SETFL, flags);
+
+    flags = fcntl(socket_fd[1], F_GETFL, 0);
+    flags &= ~O_NONBLOCK;
+    fcntl(socket_fd[0], F_SETFL, flags);
 }
 
-esp_err_t test_pre_executor(void *ctx, char *buf, const esp_err_t reader_ret_val)
+static void test_socket_teardown(int socket_fd[2])
 {
-    return ESP_OK;
+    close(socket_fd[0]);
+    close(socket_fd[1]);
 }
 
-esp_err_t test_executor(esp_commands_handle_t handle, const char *buf, int *ret_val)
+static void test_send_characters(int socket_fd, const char *msg)
 {
+    // wait to simulate that the user is doing the input
+    // and prevent linenoise to detect the incoming character(s)
+    // as pasted
+    wait_ms(100);
+
+    const size_t msg_len = strlen(msg);
+    const int nwrite = write(socket_fd, msg, msg_len);
+    TEST_ASSERT_EQUAL(msg_len, nwrite);
+}
+
+esp_err_t test_pre_executor(void *ctx, char *buf, const esp_err_t reader_ret_val)
+{
+    s_pre_executor_nb_of_calls++;
     return ESP_OK;
 }
 
 esp_err_t test_post_executor(void *ctx, const char *buf, const esp_err_t executor_ret_val, const int cmd_ret_val)
 {
+    s_post_executor_nb_of_calls++;
     return ESP_OK;
 }
 
 void test_on_stop(void *ctx, esp_repl_instance_handle_t handle)
 {
+    s_on_stop_nb_of_calls++;
     return;
 }
 
 void test_on_exit(void *ctx, esp_repl_instance_handle_t handle)
 {
+    s_on_exit_nb_of_calls++;
     return;
 }
 
-TEST_CASE("esp_repl() called after successful init, with non blocking reader", "[esp_repl]")
+TEST_CASE("esp_repl() loop calls all callbacks and exit on call to esp_repl_stop", "[esp_repl]")
 {
-    esp_commands_dummy_t dummy_esp_linenoise = {.value = 0x01 };
-    esp_commands_dummy_t dummy_esp_commands = {.value = 0x02 };
-    esp_repl_config_t config = {
+    esp_linenoise_config_t linenoise_config;
+    esp_linenoise_get_instance_config_default(&linenoise_config);
+    test_socket_setup(s_socket_fd);
+    esp_linenoise_handle_t esp_linenoise_hdl = esp_linenoise_create_instance(&linenoise_config);
+
+    /* wait for a bit so esp_linenoise has time to properly initialize */
+    vTaskDelay(pdMS_TO_TICKS(100));
+
+    esp_commands_dummy_t dummy_esp_commands = { .value = 0x02 };
+    esp_repl_config_t repl_config = {
+        .linenoise_handle = esp_linenoise_hdl,
+        .command_set_handle = NULL,
         .max_cmd_line_size = 256,
-        .reader = { .func = (esp_repl_reader_fn)test_reader_non_blocking, .ctx = &dummy_esp_linenoise },
+        .history_save_path = NULL,
         .pre_executor = { .func = test_pre_executor, .ctx = NULL },
-        .executor = { .func = (esp_repl_executor_fn)test_executor, .ctx = &dummy_esp_commands },
         .post_executor = { .func = test_post_executor, .ctx = NULL },
         .on_stop = { .func = test_on_stop, .ctx = NULL },
         .on_exit = { .func = test_on_exit, .ctx = NULL }
     };
 
-    esp_repl_instance_handle_t handle = NULL;
-    TEST_ASSERT_EQUAL(ESP_OK, esp_repl_create(&handle, &config));
-    TEST_ASSERT_NOT_NULL(handle);
+    esp_repl_instance_handle_t repl_handle = NULL;
+    TEST_ASSERT_EQUAL(ESP_OK, esp_repl_create(&repl_handle, &repl_config));
+    TEST_ASSERT_NOT_NULL(repl_handle);
 
     xTaskCreate(esp_apptrace_send_uart_tx_task, "app_trace_uart_tx_task", 2500, hw_data, uart_prio, NULL);
 
-}
+    /* should fail before repl is started */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_stop(repl_handle));
+
+    /* start repl */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_start(NULL));
+    TEST_ASSERT_EQUAL(ESP_OK, esp_repl_start(repl_handle));
+
+    /* wait for a bit so linenoise_get_line is reached in the esp_repl while loop */
+    vTaskDelay(pdMS_TO_TICKS(100));
+
+    /* send a dummy string new line terminated to trigger linenoise to return */
+    const char *input_line = "dummy_message\n";
+    test_send_characters(s_socket_fd[1], input_line);
+
+    /* wait for a bit so so esp_repl() has time to loop back  into esp_linenoise_get_line */
+    vTaskDelay(pdMS_TO_TICKS(100));
+
+    /* check that pre-executor, post-executor callbacks are called */
+    TEST_ASSERT(1, s_pre_executor_nb_of_calls);
+    TEST_ASSERT(1, s_post_executor_nb_of_calls);
+
+    /* here, esp_repl() should be back in esp_linenoise_get_line, call
+     * esp_repl_stop() and check that both the on_stop and on_exit callbacks
+     * are being called */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_stop(NULL));
+    TEST_ASSERT_EQUAL(ESP_OK, esp_repl_stop(repl_handle));
+
+    vTaskDelay(pdMS_TO_TICKS(100));
+
+    TEST_ASSERT_EQUAL(1, s_on_stop_nb_of_calls);
+    TEST_ASSERT_EQUAL(1, s_on_exit_nb_of_calls);
+    TEST_ASSERT_EQUAL(2, s_pre_executor_nb_of_calls);
+    TEST_ASSERT_EQUAL(2, s_post_executor_nb_of_calls);
+
+    /* make sure calling stop fails because the repl is no longer running */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_stop(repl_handle));
+
+    /* reset the static variables */
+    s_on_stop_nb_of_calls = 0;
+    s_on_exit_nb_of_calls = 0;
+    s_pre_executor_nb_of_calls = 0;
+    s_post_executor_nb_of_calls = 0;
+
+    /* destroy the repl instance */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_destroy(NULL));
+    TEST_ASSERT_EQUAL(ESP_OK, esp_repl_destroy(repl_handle));
+
+    /* should fail after the instance is destroy */
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_start(repl_handle));
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_stop(repl_handle));
+    TEST_ASSERT_NOT_EQUAL(ESP_OK, esp_repl_destroy(repl_handle));
+
+    test_socket_teardown(s_socket_fd);
+}