CLI Module
- Thomas Watteyne
- Bill Lindsay
- Jonathan Simon
- Dust Writer [linear]
This section refers to the following sample application(s):
03-cli_module03-cli_accesslevel
The Command Line Interface (CLI) allows a human to enter commands and read output from the mote. This data is transferred over a dedicated serial port, different from the UART serial port detailed in UART (HDLC). This results in a terminal-like environment.
The
On-Chip Software Development Kit
provides high-level functions to build a CLI interface.The CLI interface is always active, and used by the
SmartMesh network stack
to provide the following default CLI commands:mset mget mseti mgeti mxtal mfs mlog mtrace minfo mshow
Each starts with an "m", indicating that these are terminated by the "mote", rather than the application.
Refer to the SmartMesh IP Mote CLI Guide for a description of these commands.
Your application can augment this list by registering additional commands. The mote has capacity for a total of 32 CLI commands. The list of built-in commands above uses 10 of those 32 available, meaning you can add up to 22 additional commands. A handler function needs to be defined for each command; it will be called when the user enters the corresponding command. The
SmartMesh network stack
takes care of dispatching the entered commands to the right handler. When a command is entered, the corresponding handler is given the full string entered by the user, allowing the handler to parse the string for arguments, and take appropriate action. The command string itself (the string that a person will type) must be short, up to 10 characters in length. For example: toggleOutput won't work, but togOut will work. Your handler is responsible for determining if the number and format of the passed arguments are correct. The handler may return DN_ERR_INVALID if validation fails, which will result in an "invalid argument(s)" error message being printed by the stack, in addition to any error messages your handler might generate.Refer to the
SmartMesh On-Chip API html documentation
in the /doc directory of the for documentation about this feature.
The 03-cli_module Sample Application
The 03-module_cli sample application registers the extra command sum. Once the command is registered, it appears in the help menu:
cli_module app, ver 1.1.0.7 SmartMeshIP stack, ver 1.3.1.4 > help help <command> Commands: mset mget mseti mgeti mxtal mfs mlog mtrace minfo mshow sum >
The handler corresponding to the sum command parses the input string. If two integers are passed as parameters to the command, the handler calculates and prints the sum of the two. It returns an error if only one parameter is specified.
> sum 1 2 sum: 3 > sum 1 invalid argument(s)
The 03-cli_accesslevel Sample Application
Each CLI command has an associated access level. By changing the active level of the CLI device, you change the subset of commands the user has access to. The table below lists the available access levels.
Only the command that are enabled by the current access level are listed in the output of the "help" command.
| active access level | what commands are enabled? |
|---|---|
DN_CLI_ACCESS_LOGIN (default) | Only commands of access level DN_CLI_ACCESS_LOGIN. |
DN_CLI_ACCESS_VIEWER | All commands of access levels DN_CLI_ACCESS_VIEWER and DN_CLI_ACCESS_LOGIN. |
DN_CLI_ACCESS_USER | All commands of access levels DN_CLI_ACCESS_USER, DN_CLI_ACCESS_VIEWER and DN_CLI_ACCESS_LOGIN. |
DN_CLI_ACCESS_DUST | All commands of access levels DN_CLI_ACCESS_DUST, DN_CLI_ACCESS_USER, DN_CLI_ACCESS_VIEWER and DN_CLI_ACCESS_LOGIN. |
The default access level is DN_CLI_ACCESS_LOGIN. Use dnm_ucli_changeAccessLevel() to change the active access level.
It's up to your application to decide when to change the active access level. You could, for example, implement "login" and "logout" CLI commands which accept a password and switch the active access level.
The 03-cli_accesslevel sample application shows how to use the access level. Internally, it defines the following dummy CLI commands:
| CLI command | access level value | access level |
|---|---|---|
clogin | 1 | DN_CLI_ACCESS_LOGIN |
cviewer | 2 | DN_CLI_ACCESS_VIEWER |
cuser | 3 | DN_CLI_ACCESS_USER |
cdust | 4 | DN_CLI_ACCESS_DUST |
It also defines a level command which allows you to switch the current user level.
Load the firmware on your device, type "help":
> help help <command> Commands: level clogin
Calling a command that is not enabled results in an error:
> cuser access denied
Change the active level to DN_CLI_ACCESS_VIEWER (value 2). The CLI output of the "help" command now also include the cviewer.
> level 2 switched to CLI access level 2 > help help <command> Commands: level clogin cviewer
You can repeat the same operation for levels DN_CLI_ACCESS_USER (value 3) and DN_CLI_ACCESS_DUST (level 4).
The access level of the default CLI commands is DN_CLI_ACCESS_USER (value 3).
They do not appear in the output of the "help" command when the active level is DN_CLI_ACCESS_VIEWER (value 2):
> level 2 switched to CLI access level 2 >help help <command> Commands: level clogin cviewer
They appear in the output of the "help" command when the active level is DN_CLI_ACCESS_USER (value 3):
> level 3 switched to CLI access level 3 > help help <command> Commands: mset mget mseti mgeti mxtal mfs mlog mtrace minfo mshow level clogin cviewer cuser