Author Topic: How to extend CLI menus and commands in the uTasker application  (Read 5543 times)

Offline mark

  • Global Moderator
  • Hero Member
  • *****
  • Posts: 3238
    • View Profile
    • uTasker
How to extend CLI menus and commands in the uTasker application
« on: February 19, 2021, 07:07:32 PM »
How to add new CLI menus and commands - valid from check-in 6th February 2021.

1. Add a new line in the table tMainCommand[]

    {"C",                 "Go to My Commands menu",                DO_HELP,          DO_MENU_HELP_MY_COMMANDS},

and add a new define DO_MENU_HELP_MY_COMMANDS (for example, see where the list with DO_MENU_HELP_MQTT is and add it on to there)

2. Search for the way that DO_MENU_HELP_MQTT is handled:

        else if (DO_MENU_HELP_MQTT == ucType) {
            ucMenu = MENU_HELP_MQTT;                                     // set MQTT menu
            return (fnDisplayHelp(0));                                   // large menu may require special handling

and add a new help handler for your new sub-menu:

        else if (DO_MENU_HELP_MY_COMMANDS == ucType) {
            ucMenu = MENU_HELP_MY_COMMANDS;                                     // set my new menu
            return (fnDisplayHelp(0));                                   // large menu may require special handling

Locate MENU_HELP_MQTT (it is an enum in versions from 6th Feb. 2021) and extend the list with MENU_HELP_MY_COMMANDS (this must be in the enum list menu_help_reference in the same order as the main menu is built up!!!!!).

3. Add a new line in the table



{ tMyCommands,          15, (sizeof(tMyCommands)/sizeof(DEBUG_COMMAND)),          "    My menu"},

Note that the value 15 is the tab spacing when listing commands in this menu. 15 tends to be fine but it can be increased if you have long commands in the menu (which are added next). See reference at the end to see what the TAB SPACING affects.

4. This then needs its own sub-menu (tMyCommands)

Start with

static const DEBUG_COMMAND tMyCommands[] = {
    {"up",                "go to main menu",                       DO_HELP,          DO_HELP_UP},
    {"help",              "Display menu specific help",            DO_HELP,          DO_MAIN_HELP},
    {"quit",              "Leave command mode",                    DO_TELNET,        DO_TELNET_QUIT},

so it supports basic help, quit and up commands.

This should already run, showing a sparse new sub-menu

5. To add a new command insert one in to the tMyCommands[] table

    {"new_command",              "Description",                  DO_MY_GROUP,      DO_MY_COMMAND},

where you need to add new defines

DO_MY_GROUP (see where the list with DO_TELNET is and add it to there)

DO_MY_COMMAND (start a new list of defines dedicated to the new sub-menu - eg. beginning with 1)

You can also use existing groups (such as DO_TELNET) if you want to handle the new command type there rather than creating a new group.

6. Make a group action handle (assuming a new group define was added) where the new command is handled - starting an action, with or without interpreting additional parameters passed in the ptrInput string)

static void fnNewGroup(unsigned char ucType, CHAR *ptrInput)
    switch (ucType) {
    case DO_MY_COMMAND:
        // Handle the command here

and enter it in

static int fnDoCommand(unsigned char ucFunction, unsigned char ucType, CHAR *ptrInput)

    case DO_TELNET:                  <----example of existing group handler
        fnDoTelnet(ucType, ptrInput);
    case DO_MY_GROUP:         <--- the new group handler
        fnNewGroup(ucType, ptrInput);


Now the new sub-menu exists, can be entered and exited and one new command is available. When the command is executed the DO_MY_COMMAND case is hit and the specific new command code can be added there.

     Main menu
N [TAB SPACING]Configure network
S              Configure serial interface
I              Go to I/O menu
A              Go to administration menu
O              Go to overview/statistics menu
U              Go to USB menu
M              MQTT client commands
C              Go to My Commands menu
help           Display menu specific help
quit           Leave command mode

     My menu
up             go to main menu
new_command    Description
help           Display menu specific help
quit           Leave command mode


To extend existing sub-menus with new commands just step 5. can be used to extend existing menus and no new group is usually needed.



« Last Edit: February 19, 2021, 08:45:06 PM by mark »