Real time embedded FreeRTOS RSS feed 
Homepage FreeRTOS+ Products FreeRTOS Labs Support Forum Contact / Enquiries

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.


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


[ Back to the top ]    [ About FreeRTOS ]    [ Privacy ]    [ FreeRTOS+ Sitemap ]    [ Main FreeRTOS Sitemap ]    [ ]


Copyright (C) Amazon Web Services, Inc. or its affiliates. All rights reserved.