espressif/esp-idf
1
0
Fork 1
mirror of https://github.com/espressif/esp-idf.git synced 2026-05-05 12:25:03 +02:00
Code Issues Packages Projects Releases Wiki Activity

console: simplify examples

Browse Source 
1. simplify console examples
2. add "quit" command
3. support console command overwrite
4. add API reference
This commit is contained in:
suda-morris
2020-02-03 18:01:04 +08:00
parent 13623ef430
commit 75cadc2e41
31 changed files with 794 additions and 1288 deletions
Download Patch File Download Diff File Expand all files Collapse all files
components/console/esp_console.h
+101 -20
View File
@@ -1,4 +1,4 @@
// Copyright 2016-2017 Espressif Systems (Shanghai) PTE LTD
// Copyright 2016-2019 Espressif Systems (Shanghai) PTE LTD
//
// Licensed under the Apache License, Version 2.0 (the "License");
// you may not use this file except in compliance with the License.
@@ -14,8 +14,7 @@
#pragma once
#ifdef __cplusplus
extern "C"
{
extern "C" {
#endif
#include <stddef.h>
@@ -30,38 +29,75 @@ typedef struct linenoiseCompletions linenoiseCompletions;
typedef struct {
size_t max_cmdline_length; //!< length of command line buffer, in bytes
size_t max_cmdline_args; //!< maximum number of command line arguments to parse
int hint_color; //!< ASCII color code of hint text
int hint_bold; //!< Set to 1 to print hint text in bold
int hint_color; //!< ASCII color code of hint text
int hint_bold; //!< Set to 1 to print hint text in bold
} esp_console_config_t;
/**
* @brief Default console configuration value
*
*/
#define ESP_CONSOLE_CONFIG_DEFAULT() \
{ \
.max_cmdline_length = 256, \
.max_cmdline_args = 32, \
.hint_color = 39, \
.hint_bold = 0 \
}
/**
* @brief Parameters for console REPL (Read Eval Print Loop)
*
*/
typedef struct {
uint32_t max_history_len; //!< maximum length for the history
const char *history_save_path; //!< file path used to save history commands, set to NULL won't save to file system
uint32_t task_stack_size; //!< repl task stack size
uint32_t task_priority; //!< repl task priority
const char *prompt; //!< prompt (NULL represents default: "esp> ")
} esp_console_repl_config_t;
/**
* @brief Default console repl configuration value
*
*/
#define ESP_CONSOLE_REPL_CONFIG_DEFAULT() \
{ \
.max_history_len = 32, \
.history_save_path = NULL, \
.task_stack_size = 4096, \
.task_priority = 2, \
.prompt = NULL, \
}
/**
* @brief initialize console module
* Call this once before using other console module features
* @param config console configuration
* @note Call this once before using other console module features
* @return
* - ESP_OK on success
* - ESP_ERR_NO_MEM if out of memory
* - ESP_ERR_INVALID_STATE if already initialized
* - ESP_ERR_INVALID_ARG if the configuration is invalid
*/
esp_err_t esp_console_init(const esp_console_config_t* config);
esp_err_t esp_console_init(const esp_console_config_t *config);
/**
* @brief de-initialize console module
* Call this once when done using console module functions
* @note Call this once when done using console module functions
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE if not initialized yet
*/
esp_err_t esp_console_deinit(void);
/**
* @brief Console command main function
* @param argc number of arguments
* @param argv array with argc entries, each pointing to a zero-terminated string argument
* @return console command return code, 0 indicates "success"
*/
typedef int (*esp_console_cmd_func_t)(int argc, char** argv);
typedef int (*esp_console_cmd_func_t)(int argc, char **argv);
/**
* @brief Console command description
@@ -71,19 +107,19 @@ typedef struct {
* Command name. Must not be NULL, must not contain spaces.
* The pointer must be valid until the call to esp_console_deinit.
*/
const char* command; //!< command name
const char *command;
/**
* Help text for the command, shown by help command.
* If set, the pointer must be valid until the call to esp_console_deinit.
* If not set, the command will not be listed in 'help' output.
*/
const char* help;
const char *help;
/**
* Hint text, usually lists possible arguments.
* If set to NULL, and 'argtable' field is non-NULL, hint will be generated
* automatically
*/
const char* hint;
const char *hint;
/**
* Pointer to a function which implements the command.
*/
@@ -94,7 +130,7 @@ typedef struct {
* Array/structure which this field points to must end with an arg_end.
* Only used for the duration of esp_console_cmd_register call.
*/
void* argtable;
void *argtable;
} esp_console_cmd_t;
/**
@@ -103,6 +139,7 @@ typedef struct {
* @return
* - ESP_OK on success
* - ESP_ERR_NO_MEM if out of memory
* - ESP_ERR_INVALID_ARG if command description includes invalid arguments
*/
esp_err_t esp_console_cmd_register(const esp_console_cmd_t *cmd);
@@ -117,11 +154,11 @@ esp_err_t esp_console_cmd_register(const esp_console_cmd_t *cmd);
* - ESP_ERR_NOT_FOUND, if command with given name wasn't registered
* - ESP_ERR_INVALID_STATE, if esp_console_init wasn't called
*/
esp_err_t esp_console_run(const char* cmdline, int* cmd_ret);
esp_err_t esp_console_run(const char *cmdline, int *cmd_ret);
/**
* @brief Split command line into arguments in place
*
* @verbatim
* - This function finds whitespace-separated arguments in the given input line.
*
* 'abc def 1 20 .3' -> [ 'abc', 'def', '1', '20', '.3' ]
@@ -134,9 +171,9 @@ esp_err_t esp_console_run(const char* cmdline, int* cmd_ret);
* - Escape sequences may be used to produce backslash, double quote, and space:
*
* 'a\ b\\c\"' -> [ 'a b\c"' ]
*
* Pointers to at most argv_size - 1 arguments are returned in argv array.
* The pointer after the last one (i.e. argv[argc]) is set to NULL.
* @endverbatim
* @note Pointers to at most argv_size - 1 arguments are returned in argv array.
* The pointer after the last one (i.e. argv[argc]) is set to NULL.
*
* @param line pointer to buffer to parse; it is modified in place
* @param argv array where the pointers to arguments are written
@@ -179,14 +216,58 @@ const char *esp_console_get_hint(const char *buf, int *color, int *bold);
/**
* @brief Register a 'help' command
*
* Default 'help' command prints the list of registered commands along with
* hints and help strings.
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE, if esp_console_init wasn't called
*/
esp_err_t esp_console_register_help_command(void);
/******************************************************************************
* Console REPL
******************************************************************************/
/**
* @brief Initialize console REPL environment
*
* @note This is a all-in-one function to establish the environment needed for REPL, includes:
* - Install the UART driver on the console UART (8n1, 115200, REF_TICK clock source)
* - Configures the stdin/stdout to go through the UART driver
* - Initializes linenoise
* - Spawn new thread to run REPL in the background
*
* @attention This function is meant to be used in the examples to make the code more compact.
* Applications which use console functionality should be based on
* the underlying linenoise and esp_console functions.
*
* @return
* - ESP_OK on success
* - ESP_FAIL Parameter error
*/
esp_err_t esp_console_repl_init(const esp_console_repl_config_t *config);
/**
* @brief Start REPL task
*
* @return
* - ESP_OK on success
* - ESP_ERR_INVALID_STATE, if repl has started already
*/
esp_err_t esp_console_repl_start(void);
/**
* @brief Register a 'quit' command
*
* Default 'quit' command will destory resources and exit REPL environment.
*
* @return
* - ESP_OK on success
* - others on failed
*/
esp_err_t esp_console_register_quit_command(void);
#ifdef __cplusplus
}
#endif