FreeRTOS Command Line Interface (CLI)


In a previous article, I gnashed my teeth about my implementation of the FreeRTOS FAT SL.  Specifically, I wasn’t very happy about my command line interface.  What I did was cheap and easy, which sometimes is a good thing, but given that the FreeRTOS Command Line Interface comes as part of the FreeRTOS installation, it sure seemed like that would have been a better way to go.  Now that I have finished the FreeRTOS Command Line Interface implementation, I am not totally in love with how it works.  But, it was worth the time to figure it out. In this article In this article I will make a copy of the PSoC Real Time Clock Project, add the FreeRTOS Command Line Interface and explain how the CLI works.  In the next article I will give the project the ability to set and read the time from the RTC component in the PSoC.

While I was working on the implementation I discovered that the example code used FreeRTOS_write and FreeRTOS_read which depend on a Peripheral Driver Library (don’t confuse that with the Cypress Peripheral Driver Library) and are part of FreeRTOS+IO.  I did very a very simple implementation of those commands to make the FreeRTOS Command Line Interface work, and I will talk more about the FreeRTOS+IO in a future article.

FreeRTOS Command Line Interface

The FreeRTOS Command Line Interface is pretty straightforward to use.  Basically you:

  1. Integrate FreeRTOS_CLI.h and .c into your project
  2. Create one or more command functions and register them for use by the CLI by calling FreeRTOS_CLIRegisterCommand
  3. Read input from the terminal UART into a buffer
  4. Call the CLI (when the users presses enter) and display the output

Integrate FreeRTOS Command Line Interface C Files

I start this whole thing by copying the project “RTC-Example” from the previous article into a new project called “RTC-Example-CLI”.  Inside of the directory FreeRTOSv9.0.0/FreeRTOS-Plus/Source/FreeRTOS-Plus-CLI you will find FreeRTOS_CLI.h and FreeRTOS_CLI.c.  These two files have all of the FreeRTOS Command Line implementation.  To make this work I copied them into my project, and then did “Add –> Existing Item” to get PSoC Creator to make them part of the project.

Integrate FreeRTOS Command Line Interface C Files

Create a Command

To use the FreeRTOS Command Line Interface you need to create one or more functions which the CLI will then callback when it detects that the user has typed that command.   Each command takes three input parameters

  1. A pointer to a character buffer where the command can store text to be printed on the screen
  2. The size of that buffer
  3. A pointer to a character buffer that holds the whole string that the user typed

The function is then responsible for

  1. Doing the command
  2. Writing some output into the output buffer (up to the length of the buffer)
  3. Returning pdFALSE (if the command has completed writing the output) or pdTRUE (if it needs to do some more processing or more output)

For example if you want to create a command to clear the screen you would create a function called “clearCommand”  That command would

  1. Ignore the pcCommandString (there are no parameters)
  2. Keep track of the number of characters written into the buffer using a static int
  3. Copy the VT100 Clear String (AKA “\033[2J\033[H”) into the output buffer
  4. Null terminate the output string
  5. If you wrote less characters than the string then return pdTrue
  6. Otherwise return false

Once you have created the command function you then need to register it with the FreeRTOS Command Line Interface.  To do that you create a structure of type “CLI_Command_Definition_t” which has 4 members.

  1. The ascii string which the user can type to trigger the command
  2. The help message
  3. A function pointer to the command function
  4. The number of arguments that the CLI should accept

Finally you need to register the command.  You should be aware that this function uses malloc.

Call the CLI and Display

On the FreeRTOS Command Line Interface webpage they provided a sample task to handle the command line interpreter.  I copied this task into my project and then made a few little changes.

  1. My Mac sends a ‘\r’ when you press the return key so I changed line 164 to reflect that
  2. My Mac sends 0x7F when you press the “Delete” key.  So I changed the ‘\b’ (aka backspace) to be 0x7F aka “del”
  3. I fixed the stupid ‘\r\n’ stuff

One of the great annoyances in the world is the way that line breaks in text files and terminals are handled.  It is typical in “unix” to use just a newline “\n”.  However, in “DOS” it is typical to use a carriage return/newline “\r\n”.  All over FreeRTOS it uses DOS mode.  I typically like to use unix mode… so you will find that I made that changes in the FreeRTOS CLI code.

The cliTask function does a number of things.

  1. Initializes the IO System, RTC and Command Line Interface (lines 154-163)
  2. Gets 1 character from the UART using FreeRTOS_read
  3. If the character is a carriage return (\r) then it calls the CLI until there is no more output (lines 167-196).   Remember that when you implement a command function for the CLI, if you return pdFALSE it means that you have no more output, and if you return pdTRUE then you have more output.
  4. If the character is the delete key (0x7F) then erase the character from the input buffer)
  5. Otherwise add it to the input buffer… assuming that you still have room.  (lines 227-232)

As always you can find all of this code on the IoT Expert GitHub website or your can git clone