FreeRTOS CLI（三）

FreeRTOS_CLIProcessCommand()

FreeRTOS_CLI.h

BaseType_t FreeRTOS_CLIProcessCommand( int8_t *pcCommandInput, 
                                          int8_t *pcWriteBuffer, 
                                          size_t xWriteBufferLen  );
		

FreeRTOS+CLI is an extensible framework that allows the application writer to define and register their own command line input commands. Separate documentation pages are provided that describe how to write a function that implements the behaviour of a user defined command, how to registers user defined commands with FreeRTOS+CLI, and how to implement a FreeRTOS+CLI task.

This page describes the FreeRTOS_CLIProcessCommand() function. FreeRTOS_CLIProcessCommand() is the API function that takes the string entered by the user at the command prompt, and if the string matches a registered command, executes the function that implements the command behaviour.获取用户在命令提示下输入的字符串，如果该字符串与注册的命令匹配，则执行实现命令行为的函数

 

Parameters:

pcCommandInput	The complete input string, exactly as entered by the user at the command prompt (which might be a UART console, keyboard, telnet client, or other user input client).
pcWriteBuffer	If pcCommandInput does not contain a correctly formatted command, then FreeRTOS_CLIProcessCommand() will output a null terminated error message into the pcWriteBuffer buffer. If pcCommandInput does contain a correctly formatted command, then FreeRTOS_CLIProcessCommand() will execute the function that implements the command behaviour, which will place its generated output into the pcWriteBuffer buffer.
xWriteBufferLen	The the size of the buffer pointed to by the pcWriteBuffer parameter. Writing more than xWriteBufferLen characters into pcWriteBuffer will cause a buffer overflow.

Returns:

FreeRTOS_CLIProcessCommand() executes a function that implements the behaviour of a command, and returns the value returned by the function it executed. These values are described on the Implementing a Command page.

 

Examples

The FreeRTOS+CLI Task Implementation page contains example code that includes a demonstration of how FreeRTOS_CLIProcessCommand() is used.

 

FreeRTOS+IO Integration （集成）

FreeRTOS+CLI is an extensible framework that allows the application writer to define and register their own command line input commands. Separate documentation pages are provided that describe how to write a function that implements the behaviour of a user defined command, and how to register user defined commands with FreeRTOS+CLI.

This page describes how to port FreeRTOS+CLI onto real hardware by providing input output (IO) routines, and a FreeRTOS+CLI task.

FreeRTOS+CLI 连接实际的IO设备 

Input and output

A command line interface receives characters from an input, and writes characters to an output. The low level details of how this is achieved is dependent on the microcontroller being used, and the interfaces the microcontroller provides.（如何实现这种输入输出的功能的较为底层的实现是依靠使用的微控制器和微控制器提供的接口）

There is a FreeRTOS+CLI featured demo that uses the FreeRTOS+IO FreeRTOS_read() and FreeRTOS_write() API functions to provide the necessary input and output to a UART. The command line interface it creates is accessed using a standard dumb terminal program, such as HyperTerminal. There is another FreeRTOS+CLI featured demo that uses a TCP/IP sockets interface to provide the necessary input and output. The command line interface it creates is accessed using a telnet client. The structure of the FreeRTOS task that runs the FreeRTOS+CLI code is similar in both cases, and is provided below.

 

An example FreeRTOS+CLI task

The source code below implements a task that manages a FreeRTOS+CLI command interpreter interface. The FreeRTOS+IO FreeRTOS_read() and FreeRTOS_write() API functions are use to provide the IO interface. It is assumed that the FreeRTOS+IO descriptor has already been opened and configured to use the interrupt driven character queue transfer mode.

The task uses the FreeRTOS+CLI FreeRTOS_CLIProcessCommand() API function.

The comments in the source code provide more information. Note this function is not re-entrant.

 

#define MAX_INPUT_LENGTH 50 #define MAX_OUTPUT_LENGTH 100 static const int8_t * const pcWelcomeMessage = "FreeRTOS command server.\r\nType Help to view a list of registered commands.\r\n"; void vCommandConsoleTask( void *pvParameters ) { Peripheral_Descriptor_t xConsole; int8_t cRxedChar, cInputIndex = 0; BaseType_t xMoreDataToFollow; /* The input and output buffers are declared static to keep them off the stack. */ static int8_t pcOutputString[ MAX_OUTPUT_LENGTH ], pcInputString[ MAX_INPUT_LENGTH ]; /* This code assumes the peripheral being used as the console has already been opened and configured, and is passed into the task as the task parameter. Cast the task parameter to the correct type. */ xConsole = ( Peripheral_Descriptor_t ) pvParameters; /* Send a welcome message to the user knows they are connected. */ FreeRTOS_write( xConsole, pcWelcomeMessage, strlen( pcWelcomeMessage ) ); for( ;; ) { /* This implementation reads a single character at a time. Wait in the Blocked state until a character is received. */ FreeRTOS_read( xConsole, &cRxedChar, sizeof( cRxedChar ) ); if( cRxedChar == '\n' ) { /* A newline character was received, so the input command string is complete and can be processed. Transmit a line separator, just to make the output easier to read. */ FreeRTOS_write( xConsole, "\r\n", strlen( "\r\n" ); /* The command interpreter is called repeatedly until it returns pdFALSE. See the "Implementing a command" documentation for an exaplanation of why this is. */ do { /* Send the command string to the command interpreter. Any output generated by the command interpreter will be placed in the pcOutputString buffer. */ xMoreDataToFollow = FreeRTOS_CLIProcessCommand ( pcInputString, /* The command string.*/ pcOutputString, /* The output buffer. */ MAX_OUTPUT_LENGTH/* The size of the output buffer. */ ); /* Write the output generated by the command interpreter to the console. */ FreeRTOS_write( xConsole, pcOutputString, strlen( pcOutputString ) ); } while( xMoreDataToFollow != pdFALSE ); /* All the strings generated by the input command have been sent. Processing of the command is complete. Clear the input string ready to receive the next command. */ cInputIndex = 0; memset( pcInputString, 0x00, MAX_INPUT_LENGTH ); } else { /* The if() clause performs the processing after a newline character is received. This else clause performs the processing if any other character is received. */ if( cRxedChar == '\r' ) { /* Ignore carriage returns. */ } else if( cRxedChar == '\b' ) { /* Backspace was pressed. Erase the last character in the input buffer - if there are any. */ if( cInputIndex > 0 ) { cInputIndex--; pcInputString[ cInputIndex ] = '\0'; } } else { /* A character was entered. It was not a new line, backspace or carriage return, so it is accepted as part of the input and placed into the input buffer. When a \n is entered the complete string will be passed to the command interpreter. */ if( cInputIndex < MAX_INPUT_LENGTH ) { pcInputString[ cInputIndex ] = cRxedChar; cInputIndex++; } } } } } An example of a task that implements a FreeRTOS+CLI command console