Console Framework

Table of Contents

• Console Framework Introduction
  • Console Framework Module Features
• Console Framework Module APIs Overview
• Console Framework Module Operational Overview
  • Console Framework Module Important Operational Notes and Limitations
    • Console Framework Module Operational Notes
    • Console Framework Module Limitations
• Including the Console Framework Module in an Application
• Configuring the Console Framework Module
  • Configuring the Console Framework Lower-Level Modules
• Using the Console Framework Module in an Application

Console Framework Introduction

The Console Framework provides a complete API implementation for a menu-driven console command line interface (CLI) using the ThreadX RTOS. The Console Framework module uses a lower-level communications interface, which connects to a hardware option for either UART, USB or Ethernet Telnet connectivity. The Console Framework module has a user-defined menu of commands and various APIs to present a prompt, identify and issue a callback for menu commands and read, write and parse input strings.

Console Framework Module Features

The console framework supports the following features:

• Creation of a menu-based command-line interface
• Submenus and navigation through multiple menus in a single call
• Menu navigation to go up to the parent menu or back to the root
• A help menu for each menu
• Writing NULL terminated strings and reading until return character is received
• An API to help parse arguments to the command line
• Case-insensitive inputs

The Console Framework module organization, as depicted in the thread stack window in the SSP configurator, is shown in the following figure. Each implementation choice, Ethernet, UART, and USB has its own lower-level modules that are added automatically based on the developer's implementation choice. In most cases, all the needed configuration information is automatically added to the modules leaving the developer with just a few important configuration settings that need to be selected.

Console Framework Module Block Diagram

Console Framework Module APIs Overview

The Console Framework defines APIs for opening, closing, reading, writing and issuing an input prompt. A complete list of the available APIs, an example API call and a short description of each can be found in the following table. A table of status return values follows the API summary table.

Console Framework Module API Summary

Function Name	Example API Call and Description
open	g_sf_console0.p_api->open(g_sf_console0.p_ctrl, g_sf_console0.p_cfg); The open API configures the console. This function must be called before any other console functions. Note This call is made automatically during system initialization, prior to entering the users thread. Unless the user closes the console, open will not need to be called.
close	g_sf_console0.p_api->close(g_sf_console0.p_ctrl); The close API handles the clean-up of internal driver data.
prompt	g_sf_console0.p_api->prompt(g_sf_console0.p_ctrl, NULL, TX_WAIT_FOREVER); The prompt API prints the prompt string from the menu, waits for input, parses the input based on the menu, and calls the appropriate callback function if a command is identified.
parse	g_sf_console0.p_api->parse(g_sf_console0.p_ctrl, commands, input, s_length); The parse API looks for an input string in the command menu and, if one is found, calls the appropriate callback function.
read	g_sf_console0.p_api->read(g_sf_console0.p_ctrl, ch, 1, TX_WAIT_FOREVER); The read API puts data into the destination, byte-by-byte and echoes the input to the console. Backspace, delete, and left/right arrow keys are supported. Read completes when a line ending with CR, CR+LF, or CR+NULL is received, or when the input exceeds the number of bytes allowed. If the buffer overflows SF_CONSOLE_MAX_INPUT_LENGTH, the read will return an error code.
write	g_sf_console0.p_api->write(g_sf_console0.p_ctrl, (uint8_t*)data_string, TX_WAIT_FOREVER); The write API gets the buffer mutex object and handles data transmission at the HAL layer. It obtains the event flag to synchronize the completion of a data transfer.
argumentFind	g_sf_console0.p_api->argumentFind("LED", p_args->p_remaining_string, NULL, &led_num); The argumentFind API locates a command line argument in an input string and returns the index of the character immediately following the argument. Any string numbers are converted to integers.
versionGet	g_sf_console0.p_api->versionGet(&version); Retrieve the API version with the version pointer.

Note

For more complete descriptions of operation and definitions for the function data structures, typedefs, defines, API data, API structures and function variables, review the SSP User's Manual API References for the associated module.

Status Return Values

Name	Description
SSP_SUCCESS	API Call Successful.
SSP_ERR_ASSERTION	p_ctrlis NULL.
SSP_ERR_UNSUPPORTED	Command not found in the current menu.

Note

Lower-level drivers may return common error codes. Refer to the SSP User's Manual API References for the associated module for a definition of all relevant status-return values.

Console Framework Module Operational Overview

The Console Framework module is a ThreadX-aware Command Line Interface (CLI). The module uses ThreadX objects like mutex for blocking and synchronization techniques like event flags for the completion of a transaction. The key operational elements of the Console Framework are initialization and input processing, each of which are described in the following sections.

Console Framework Module Initialization

The open call is automatically generated by the ISDE and is in the file where the module was added. The open call requires the application to define a root menu with a variable name that matches the one in the configurator (g_sf_console_root_menu) by default. By the time execution reaches the thread entry function the module is ready to use, provided the necessary hardware connection is established.

Console Framework Module Input Processing

The Console Framework module requires a set of menus, command structures, and callbacks. The Console Framework module typically operates from the prompt, often located within a while loop in the entry thread. The framework sf_console_api_t::prompt API will print the current menu as a prompt, then read input and echo it back to the console (unless echo is disabled in the properties.)

Following operations are performed against the user input: 

While the console is accepting input,

• Backspace will remove characters before the cursor.
• Delete will remove characters after the cursor.
• The left and right arrow keys move the cursor.
• The up-arrow key will fill in the last command only when nothing else has been entered.

Note

There is no history beyond the last command; if the up-arrow key is pressed twice, the console does not know what command was entered prior to the last command and it will continue to display the last command.

When the console sees a return character on the read input, it parses the input string and calls the associated callback or switches to the next menu if SF_CONSOLE_CALLBACK_NEXT_FUNCTION is used in place of the callback for the command. The console will continue parsing until a callback function is called. If sf_console_api_t::prompt API is called again, it will prompt using the menu that contains the callback function. To navigate up to the parent menu, enter '^'. To navigate to the root menu from any submenu, enter '~'.

The parser will parse the input command till a white space or end of the string.

For example:

With the list of commands[2] = {"echo", "setbitrate"};

1.  >echoIs valid
2.  >echo<space>Is valid
3.  >echo3Is an unsupported command
4.  >setbitrateIs valid
5.  >setbitrate 9600Results in the bit rate being set to 9600

Creating Console Framework Module Required Structures – The Menu

The Console Framework requires a menu and it is up to the developer to create the structure that is used by the Console Framework to implement the menu. The console menu structure (depicted in the following figure) includes a pointer to the previous menu, (for creating multi-level menus) a name for the menu, the number of commands in the menu, and a pointer to an array of command structures. As seen in the following figure, each entry in the array of commands includes pointers to the command name string, the help command description string, the associated command callback function, and a context parameter provided to the callback.

Console Framework Module Menu Structures

The application project example illustrates a Console Framework with a single menu; it controls the toggle of an LED from the CLI. The console command array (g_sf_console_commands, seen on the right in the following figure) stores the array of commands (in this case, just a single command.) The command structure defines the command as "LED TOGGLE", the help description as "Toggle an LED", the callback as led_toggle_callback, and the context as NULL, since it is unused for this example.

The root menu, seen on the left side of the following figure, is identified by the g_sf_console_root_menu structure. The structure defines the menu_prev entry as NULL, since there is only the single menu, the menu_name as "Root", the num_commands as the size of the array divided by the size of an entry (to determine the total number of entries) as "1", and the command_list starting address as "address", the location of the first entry in the command array.

Console Framework Module Menu Structure Example Diagram

Console Framework Module Important Operational Notes and Limitations

Console Framework Module Operational Notes

• To use the Console Framework module sf_console_api_t::prompt API, first set up the menu, command structures and callbacks.

Console Framework Module Limitations

• Refer to the most recent SSP Release Notes for any additional operational limitations for this module.

Including the Console Framework Module in an Application

This section describes how to include the Console Framework module in an application using the SSP configurator.

Note

This section assumes you are familiar with creating a project, adding threads, adding a stack to a thread and configuring a block within the stack. If you are unfamiliar with any of these items, refer to the first few chapters of the SSP User's Manual to learn how to manage each of these important steps in creating SSP-based applications.

To add the Console Framework module to an application, simply add it to a HAL /Common thread using the stacks selection sequence given in the following table. (The default name for the Console Framework module is g_sf_console0. This name can be changed in the associated Properties window.)

Console Framework Module Selection Sequence

Resource	ISDE Tab	Stacks Selection Sequence
g_sf_console0 Console Framework on sf_console	Threads	New Stack> Framework> Services> Console Framework on sf_console

When the Console Framework module on sf_console is added to the thread stack as shown in the following figure, the configurator automatically adds any needed lower‑level modules. Any modules needing additional configuration information have the box text highlighted in Red. Modules with a Gray band are individual modules that stand alone. Modules with a Blue band are shared or common; they need only be added once and can be used by multiple stacks. Modules with a Pink band can require the selection of lower-level modules; these are either optional or recommended. (This is indicated in the block with the inclusion of this text.) If the addition of lower-level modules is required, the module description include Add in the text. Clicking on any Pink banded modules brings up the New icon and displays possible choices.

Console Framework Module Stack

                                                                 

Example Console Framework with UART Communications Framework

Configuring the Console Framework Module

The Console Framework module must be configured by the user for the desired operation. The SSP configuration window will automatically identify (by highlighting the block in red) any required configuration selections, such as interrupts or operating modes, which must be configured for lower-level modules in order to ensure successful operation. Furthermore, only those properties that can be changed without causing conflicts are available for modification. Other properties are 'locked' and are not available for changes, and are identified with a lock icon for the 'locked' property in the Properties window in the ISDE. This approach simplifies the configuration process and makes it much less error-prone than previous 'manual' approaches to configuration. The available configuration settings and defaults for all the user-accessible properties are given in the Properties tab within the SSP configurator, and are shown in the following tables for easy reference.

Note

You may want to open your ISDE, create the module and explore the property settings in parallel with looking over the following configuration table settings; this will help orient you and can be a useful 'hands-on' approach to learning the ins and outs of developing with the SSP.

Configuration Settings for the Console Framework Module on sf_console

ISDE Property	Value	Description
Parameter Checking	BSP, Enabled, Disabled Default: BSP	Enables or disables the parameter checking.
Maximum Input String Length	128	Maximum input string length selection.
Maximum Write String Length	128	Maximum input string length selection.
Console print timeout value	0xFFFFFFFF	Console print timeout value selection.
Name	g_sf_console0	Module name.
Name of Initial Menu (Application Defined)	g_sf_console_root_menu	Initial menu name.
Echo	True, False Default: True	Echo selection.
Autostart	True, False Default: False	Autostart selection.
Name of generated initialization function	sf_console_init0	Name of generated initialization function.
Auto Initialization	Enable, Disable Default: Enable	Auto Initialization selection.

Note

The example values and defaults are for a project using the Synergy S7G2 MCU Group. Other MCUs may have different default values and available configuration settings.

Configuring the Console Framework Lower-Level Modules

The Console Framework provides three different options for Communication Framework implementations: the Telnet Communications Framework, the Communications Framework on USBX v2, and the UART Communications Framework. Each of these frameworks have several lower-level module options themselves; configuration information for these frameworks is provided in the module overviews for the sf_comms_telnet, sf_el_ux_comms_v2, and sf_uart_comms modules.

Using the Console Framework Module in an Application

The typical steps in using the Console Framework module in an application are:

1. Create menu and command structures.
2. Implement needed callbacks.
3. Initialize the Console Framework using hte sf_console_api_t::open API.
4. Use the sf_console_api_t::prompt API to generate the prompt and process commands.
5. Use other APIs (sf_console_api_t::read, sf_console_api_t::write, sf_console_api_t::parse or sf_console_api_t::argumentFind) as needed to process commands.
6. Use sf_console_api_t::close API to close the module if desired.

These common steps are illustrated in a typical operational flow in the following figure:

Flow Diagram of a Typical Console Framework Module Application