FreeRTOS CLI

简介

CLI指命令行界面，开发调试过程中有助于改善人机交互的体验。

简易的交互方法可以通过UART传输字符，指明机器执行特定功能，具体格式开发者自行定义。
FreeRTOS的CLI组件一定意义上是对交互方式进行了格式化，调试功能单元化，简化开发调试时人机交互的操作。

源码

在FreeRTOS源码下载时已经包含该组件：FreeRTOS-Plus/Source/FreeRTOS-Plus-CLI。
官方提供的CLI组件参考示例源码

FreeRTOS-Plus
+---Demo
|   +---AWS
|   +---Common
|   |   +---Demo_IP_Protocols
|   |   +---FreeRTOS_Plus_CLI_Demos	// demo code
|   |   |   +---File-Related-CLI-commands.c
|   |   |   +---Sample-CLI-commands.c
|   |   |   +---UARTCommandConsole.c
|   |   |   \---UDP-Related-CLI-commands.c
|   |   +--- ...
|   |   \---WinPCap
|   +--- ...
|   \---FreeRTOS_Plus_WolfSSL_Windows_Simulator
+---Source
|   +---FreeRTOS-Plus-CLI	// source code
|   |   +---FreeRTOS_CLI.c
|   |   \---FreeRTOS_CLI.h
|   +--- ...
|   \---Utilities
+---Test
\---ThirdParty

移植

配置工程

源码文件添加到工程，增加宏定义配置输出缓存数组大小#define configCOMMAND_INT_MAX_OUTPUT_SIZE 128

/* If the application writer needs to place the buffer used by the CLI at a
fixed address then set configAPPLICATION_PROVIDES_cOutputBuffer to 1 in
FreeRTOSConfig.h, then declare an array with the following name and size in 
one of the application files:
	char cOutputBuffer[ configCOMMAND_INT_MAX_OUTPUT_SIZE ];
*/
#ifndef configAPPLICATION_PROVIDES_cOutputBuffer
	#define configAPPLICATION_PROVIDES_cOutputBuffer 0
#endif

/* A buffer into which command outputs can be written is declared here, rather
than in the command console implementation, to allow multiple command consoles
to share the same buffer.  For example, an application may allow access to the
command interpreter by UART and by Ethernet.  Sharing a buffer is done purely
to save RAM.  Note, however, that the command console itself is not re-entrant,
so only one command interpreter interface can be used at any one time.  For that
reason, no attempt at providing mutual exclusion to the cOutputBuffer array is
attempted.

configAPPLICATION_PROVIDES_cOutputBuffer is provided to allow the application
writer to provide their own cOutputBuffer declaration in cases where the
buffer needs to be placed at a fixed address (rather than by the linker). */
#if( configAPPLICATION_PROVIDES_cOutputBuffer == 0 )
	static char cOutputBuffer[ configCOMMAND_INT_MAX_OUTPUT_SIZE ];
#else
	extern char cOutputBuffer[ configCOMMAND_INT_MAX_OUTPUT_SIZE ];
#endif

接收命令

根据实际情况实现，可以是UART等方式，只要能够将输入命令传进来就行。
例如，接收的命令都放入到指定的输入缓冲数组中char input_str[255] = {0};

命令识别

假定使用UART传输命令，发送命令时默认添加\r标识字符到末尾

BaseType_t FreeRTOS_CLIProcessCommand( const char * const pcCommandInput, char * pcWriteBuffer, size_t xWriteBufferLen  )
{
	...
	if( ( pcCommandInput[ xCommandStringLength ] == ' ' ) || ( pcCommandInput[ xCommandStringLength ] == 0x00 ) )
	...
}

修改为

BaseType_t FreeRTOS_CLIProcessCommand( const char * const pcCommandInput, char * pcWriteBuffer, size_t xWriteBufferLen  )
{
	...
	if( ( pcCommandInput[ xCommandStringLength ] == '\r' ) || ( pcCommandInput[ xCommandStringLength ] == '\n' ) )
	...
}

自定义命令

/* The structure that defines command line commands.  A command line command
should be defined by declaring a const structure of this type. */
typedef struct xCOMMAND_LINE_INPUT
{
	const char * const pcCommand;				/* The command that causes pxCommandInterpreter to be executed.  For example "help".  Must be all lower case. */
	const char * const pcHelpString;			/* String that describes how to use the command.  Should start with the command itself, and end with "\r\n".  For example "help: Returns a list of all the commands\r\n". */
	const pdCOMMAND_LINE_CALLBACK pxCommandInterpreter;	/* A pointer to the callback function that will return the output generated by the command. */
	int8_t cExpectedNumberOfParameters;			/* Commands expect a fixed number of parameters, which may be zero. */
} CLI_Command_Definition_t;

/* For backward compatibility. */
#define xCommandLineInput CLI_Command_Definition_t

按照CLI_Command_Definition_t结构定义命令，并且将自定义的命令注册到系统中

/*
 * Implements the run-time-stats command.
 */
static BaseType_t prvTaskStatsCommand( char *pcWriteBuffer, size_t xWriteBufferLen, const char *pcCommandString )
{
	return pdFALSE;
}

/* Structure that defines the "run-time-stats" command line command.   This
generates a table that shows how much run time each task has */
static const CLI_Command_Definition_t prvCommand1 =
{
	( const int8_t * const ) "run", /* The command string to type. */
	( const int8_t * const ) "run-time-stats:\r\n Displays a table showing how much processing time each FreeRTOS task has used\r\n\r\n",
	prvRunTimeStatsCommand, /* The function to run. */
	0 /* No parameters are expected. */
};

static void vRegisterCommand(void)
{
	/* Register all the command line commands defined immediately above. */
	FreeRTOS_CLIRegisterCommand( &prvCommand1 );
}

创建CLI任务

/* task entry */
static void prvTask2( void *pvParameters )
{
	BaseType_t xReturn = pdTRUE;
	char *pcOutputString = FreeRTOS_CLIGetOutputBuffer();

	/* Remove compiler warning about unused parameter. */
	( void ) pvParameters;

	for( ;; )
	{
		/* simple condition for command ending */
		if(input_str[index - 1] == '\r')
		{
			do{
				xReturn = FreeRTOS_CLIProcessCommand(input_str, pcOutputString,
											configCOMMAND_INT_MAX_OUTPUT_SIZE);
				printf("%s\n", pcOutputString);
			}while(pdFALSE != xReturn);

			index = 0;
		}

		printf("RTOS task 2!\r\n");
		vTaskDelay(500);
	}
}

/* create task */
void vCommandTaskStart(void)
{
	vRegisterCommand();
	xTaskCreate( prvTask2, "CLI", configMINIMAL_STACK_SIZE, NULL,
				 configMAX_PRIORITIES - 2, NULL );
}

补充细节

命令回调函数

static BaseType_t prvCommand( char *pcWriteBuffer, size_t xWriteBufferLen, const char *pcCommandString )
{
	//TODO
	return pdFALSE;
}

命令回调函数执行结束必须以pdFALSE作为返回值，否则FreeRTOS_CLIProcessCommand会一直循环，但是一个命令是可以多次进入分段执行。比如

static BaseType_t prvCommand( char *pcWriteBuffer, size_t xWriteBufferLen, const char *pcCommandString )
{
	{ //first
		return pdTRUE;
	}
	
	{ //second
		return pdFALSE;
	}
}

命令行参数

命令处理时会判断命令行参数数量，命令和参数之间以空格字符分割。
判别方式：

• 当前字符是空格，上一个字符不是空格：命令参数增加一
• 当前字符是结束符，上一个字符是是空格：命令参数减一

比如：上面我们以\r作为命令结束符判别，如果输入命令时最后敲了空格再回车发送就会导致识别为一个命令参数。
因为发送内容为xxx \r，空格后的\r作为了命令参数。