Added arduino example and improved documentation

Author: geekfactory

Shell.h

@@ -29,6 +29,24 @@
 /*-------------------------------------------------------------*/
 /*		Macros and definitions				*/
 /*-------------------------------------------------------------*/
+#if !defined(CONFIG_SHELL_MAX_COMMANDS)
+/**
+ * Defines the maximum number of commands that can be registered
+ */
+#define CONFIG_SHELL_MAX_COMMANDS		5
+#endif
+#if !defined(CONFIG_SHELL_MAX_INPUT)
+/**
+ * Defines the maximum characters that the input buffer can accept
+ */
+#define CONFIG_SHELL_MAX_INPUT			100
+#endif
+#if !defined(CONFIG_SHELL_MAX_COMMAND_ARGS)
+/**
+ * Configures the maximum number of arguments per command tha can be accepted
+ */
+#define CONFIG_SHELL_MAX_COMMAND_ARGS		10
+#endif
 
 #define SHELL_ASCII_NUL				0x00
 #define SHELL_ASCII_BEL				0x07
@@ -49,25 +67,6 @@
 #define SHELL_RET_FAILURE			1
 #define SHELL_RET_IOPENDING			-1
 
-#if !defined(CONFIG_SHELL_MAX_COMMANDS)
-/**
- * Defines the maximum number of commands that can be registered
- */
-#define CONFIG_SHELL_MAX_COMMANDS		5
-#endif
-#if !defined(CONFIG_SHELL_MAX_INPUT)
-/**
- * Defines the maximum characters that the input buffer can accept
- */
-#define CONFIG_SHELL_MAX_INPUT			100
-#endif
-#if !defined(CONFIG_SHELL_MAX_COMMAND_ARGS)
-/**
- * Configures the maximum number of arguments per command tha can be accepted
- */
-#define CONFIG_SHELL_MAX_COMMAND_ARGS		10
-#endif
-
 /*-------------------------------------------------------------*/
 /*		Typedefs enums & structs			*/
 /*-------------------------------------------------------------*/
@@ -94,13 +93,13 @@ typedef int (*shell_reader_t) (char *);
  * shell
  */
 enum shell_errors {
-	E_SHELL_ERR_ARGCOUNT = 0,
-	E_SHELL_ERR_OUTOFRANGE,
-	E_SHELL_ERR_VALUE,
-	E_SHELL_ERR_ACTION,
-	E_SHELL_ERR_PARSE,
-	E_SHELL_ERR_STORAGE,
-	E_SHELL_ERR_IO,
+	E_SHELL_ERR_ARGCOUNT = 0,	//!< There are missing arguments for the command
+	E_SHELL_ERR_OUTOFRANGE,		//!< The program received an argument that is out of range
+	E_SHELL_ERR_VALUE,		//!< The program received an argument with a value different than expected
+	E_SHELL_ERR_ACTION,		//!< Invalid action requested for the current state
+	E_SHELL_ERR_PARSE,		//!< Cannot parse the user input
+	E_SHELL_ERR_STORAGE,		//!< Cannot access storage device or memory device
+	E_SHELL_ERR_IO,			//!< IO device error caused program interruption
 };
 
 /**
@@ -118,97 +117,114 @@ struct shell_command_entry {
 #ifdef	__cplusplus
 extern "C" {
 #endif
+/**
+ * @brief Prepares the command line interface
+ *
+ * Initializes the resources used by the command line interface. This function
+ * also tries to start the command line task if the option is enabled. The main
+ * program for the command line interface where all the data is handled is
+ * shell_task().
+ *
+ * @param reader The callback function used to get a character from the stream.
+ *
+ * @param writer The callback function used to write a character to the stream.
+ *
+ * @param msg The message to display upon startup of the program
+ *
+ * @return Returns TRUE if the shell was succesfully initialized, returns FALSE
+ * otherwise.
+ */
+uint8_t shell_init(shell_reader_t reader, shell_writer_t writer, char * msg);
 
-	/**
-	 * @brief Prepares the command line interface
-	 *
-	 * Initializes the resources used by the command line interface. This function
-	 * also tries to start the command line task if the option is enabled. The main
-	 * program for the command line interface where all the data is handled is
-	 * shell_task().
-	 *
-	 * @param reader The callback function used to get a character from the stream.
-	 *
-	 * @param writer The callback function used to write a character to the stream.
-	 *
-	 * @param msg The message to display upon startup of the program
-	 *
-	 * @return Returns TRUE if the shell was succesfully initialized, returns FALSE
-	 * otherwise.
-	 */
-	uint8_t shell_init(shell_reader_t reader, shell_writer_t writer, char * msg);
-
-	/**
-	 * @brief Register a command with the command interpreter
-	 *
-	 * Registers a command on the available command list. The name of the command
-	 * and the function that implements it´s functionality should be provided.
-	 *
-	 * @param program The type shell_program_t is a pointer to a function
-	 * that is executed when the written command matches the associated name
-	 *
-	 * @param string A string containing the name of the command to be registered.
-	 *
-	 * @return Returns TRUE if command was successfully added to the command list,
-	 * or returns FALSE if something fails (no more commands can be registered).
-	 */
-	uint8_t shell_register(shell_program_t program, const char * string);
-
-	/**
-	 * @brief Unregister all commands
-	 *
-	 * Errases all entries on the command list, returning it to it´s default status.
-	 */
-	void shell_unregister_all();
-
-	/**
-	 * @brief Prints the list of registered commands
-	 *
-	 * Prints a list of available commands to the terminal using the callback
-	 * functions provided on initialization.
-	 */
-	void shell_print_commands();
-
-	/**
-	 * @brief Prints error messages to the terminal screen
-	 *
-	 * @param error The code (ID) of the error to print
-	 *
-	 * @param field The name of the parameter or variable where the error was
-	 * detected.
-	 */
-	void shell_print_error(int error, const char * field);
-
-	/**
-	 * @brief Prints a null terminated string to the terminal
-	 *
-	 * Displays a string on the terminal. The string should be null terminated.
-	 *
-	 * @param string The string to send to the terminal
-	 */
-	void shell_print(const char * string);
-
-	/**
-	 * @brief Prints a string and moves the cursor to the next line
-	 *
-	 * @param string The string to send to the terminal
-	 */
-	void shell_println(const char * string);
-
-	/**
-	 *
-	 */
-	void shell_printf(char * fmt, ...);
-
-	/**
-	 *
-	 * @brief Main Shell processing loop
-	 *
-	 * This function implements the main functionality of the command line interface
-	 * this function should be called frequently so it can handle the input from the
-	 * data stream.
-	 */
-	void shell_task();
+/**
+ * @brief Register a command with the command interpreter
+ *
+ * Registers a command on the available command list. The name of the command
+ * and the function that implements it´s functionality should be provided.
+ *
+ * @param program The type shell_program_t is a pointer to a function
+ * that is executed when the written command matches the associated name
+ *
+ * @param string A string containing the name of the command to be registered.
+ *
+ * @return Returns TRUE if command was successfully added to the command list,
+ * or returns FALSE if something fails (no more commands can be registered).
+ */
+uint8_t shell_register(shell_program_t program, const char * string);
+
+/**
+ * @brief Unregister all commands
+ *
+ * Errases all entries on the command list, returning it to it´s default status.
+ */
+void shell_unregister_all();
+
+/**
+ * @brief Prints the list of registered commands
+ *
+ * Prints a list of available commands to the terminal using the callback
+ * functions provided on initialization.
+ */
+void shell_print_commands();
+
+/**
+ * @brief Prints error messages to the terminal screen
+ *
+ * This function presents an alternative for displaying program errors in a
+ * uniform format.
+ *
+ * @param error The code (ID) of the error to print
+ *
+ * @param field The name of the parameter or variable where the error was
+ * detected.
+ */
+void shell_print_error(int error, const char * field);
+
+/**
+ * @brief Prints a null terminated string to the terminal
+ *
+ * Displays a string on the terminal. The string should be null terminated.
+ *
+ * @param string The string to send to the terminal
+ */
+void shell_print(const char * string);
+
+/**
+ * @brief Prints a string and moves the cursor to the next line
+ *
+ * Displays a string on the terminal and moves the cursor to the next line. The
+ * string should be null terminated.
+ *
+ * @param string The string to send to the terminal
+ */
+void shell_println(const char * string);
+
+/**
+ * @brief Prints formatted text to the terminal
+ *
+ * Displays a string (fmt) on the terminal. If the string includes format
+ * specifiers (subsequences beginning with '%'), the additional arguments
+ * following format are formatted and inserted in the resulting string
+ * replacing their respective specifiers.
+ *
+ * This function implements it´s own mechanism for text formatting. It doesn´t
+ * rely on the native print functions.
+ *
+ * @param fmt The string to send to the terminal, the string can include format
+ * specifiers in a similar fashion to printf standard function.
+ *
+ * @param ... Aditional arguments that are inserted on the string as text
+ */
+void shell_printf(char * fmt, ...);
+
+/**
+ * @brief Main Shell processing loop
+ *
+ * This function implements the main functionality of the command line interface
+ * this function should be called frequently so it can handle the input from the
+ * data stream.
+ */
+void shell_task();
 
 #ifdef	__cplusplus
 }

examples/Shell_Basic_Example/Shell_Basic_Example.ino

@@ -0,0 +1,91 @@
+/**
+ * SIMPLE EXAMPLE OF COMMAND SHELL LIBRARY
+ * 
+ * This library implements a command line interface. The experience is similar to the windows
+ * command prompt. This library can invoke functions when a specific string is received, in this
+ * example we register 2 commands that can be executed by typing their names on the arduino serial
+ * monitor (using the hardware UART).
+ * 
+ * The "shell" library is designed to be independent of the communication channel, this means
+ * that it can be used with serial, softSerial and even TCP connections. For this reason the
+ * shell library requires 2 pointers to functions to read and write characters to and from the
+ * physical transmission media.
+ * 
+ * Arguments can be passed to the programs that are invoked by the command line and parsed by
+ * standard string parsing functions, or you can write your own functions. The arguments
+ * are passed as pointers to characters (null terminated strings) in a similar way that you
+ * would receive them on any command line tool written in C. Each parameter is separated by
+ * a "space" character after the command name.
+ */
+
+#include <Shell.h>
+
+void setup()
+{
+  // Prepare serial communication
+  Serial.begin(9600);
+  // Wait after reset or power on...
+  delay(1000);
+
+  // Initialize command line interface (CLI)
+  // We pass the function pointers to the read and write functions that we implement below
+  // We can also pass a char pointer to display a custom start message
+  shell_init(shell_reader, shell_writer, 0);
+
+  // Add commands to the shell
+  shell_register(command_mycommand, "mycommand");
+  shell_register(command_othercommand, "othercommand");
+}
+
+void loop()
+{
+  // This should always be called to process user input
+  shell_task();
+}
+
+/**
+ * Test commands: The commands should always use this function prototype.
+ * They receive 2 parameters: The total count of arguments (argc) and a pointer 
+ * to the begining of each one of the null-terminated argument strings.
+ *
+ + In this example we ignore the parameters passed to the functions
+ */
+int command_mycommand(int argc, char** argv)
+{
+  shell_println("Running \"mycommand\" now");
+  shell_println("Exit...");
+  return SHELL_RET_SUCCESS;
+}
+
+int command_othercommand(int argc, char** argv)
+{
+  shell_println("Running \"othercommand\" now");
+  shell_println("Exit...");
+  return SHELL_RET_SUCCESS;
+}
+
+/**
+ * Function to read data from serial port
+ * Functions to read from physical media should use this prototype:
+ * int my_reader_function(char * data)
+ */
+int shell_reader(char * data)
+{
+  // Wrapper for Serial.read() method
+  if (Serial.available()) {
+    *data = Serial.read();
+    return 1;
+  }
+  return 0;
+}
+
+/**
+ * Function to write data to serial port
+ * Functions to write to physical media should use this prototype
+ * void my_writer_function(char data)
+ */
+void shell_writer(char data)
+{
+  // Wrapper for Serial.write() method
+  Serial.write(data);
+}