Need help with SimpleCLI?
Click the “chat” button below for chat support from the developer who created it, or find similar developers for support.

About the developer

spacehuhn
133 Stars 25 Forks MIT License 137 Commits 3 Opened issues

Description

Command Line Interface Library for Arduino

Services available

!
?

Need anything else?

Contributors list

# 5,864
C++
C
Arduino
esp8266
9 commits
# 228,764
C
Shell
nfc
Arduino
1 commit
# 332,182
apidoc
gopro
Shell
HTML
1 commit

SimpleCLI

SimpleCLI Logo

A Command Line Interface Library for Arduino!
Add commands to your project without hassle.

Ardu Badge for SimpleCLI Library

🐦 Twitter | 📺 YouTube | 🌍 spacehuhn.io

Support this project and become a patron on patreon.com/spacehuhn.
Also available: Stickers!

Cowsay command example

Projects

A list of projects that make use of this library:
- The Chicken Man Game - Control ESP32 with Command Line Interface Over the Internet - WiFiDuck - ESP8266 Deauther V3

Overview

About

The goal of this library is to control your Arduino projects using commands similar to the Linux CLI.
Because parsing and validating strings in C/C++ can be quite a pain, this library aims to simplify the process as much as possible.

Supported Devices

Strings take up a good amount of memory, so it's strongly recommended to chose a development board with at least 32 KB RAM.
It doesn't make much sense to run this library on an Uno or Nano, because it will quickly take up a most of the resources.
Here's a list of tested hardware (feel free to contribute by making a Pull-Request):

| Chipset | Board(s) | Flash | RAM | Support | | ------- | -------- | ----- | --- | ------- | | ATtiny85 | Digispark | 8 KB | 512 Byte | No! (Does not compile C++11) | | ATmega328P | Arduino Nano, Arduino Uno | 32 KB | 2 KB | Works for small projects | | ATmega32u4 | Arduino Leonardo, Pro Micro | 32 KB | 2,560 Byte | Works for small projects | | ATSAMD21G18 | Arduino MKR WiFi 1010 | 256 KB | 32 KB | Yes! | | ATSAMD51G19 | Adafruit ItsyBitsy M4 Express | 512 KB | 192 KB | Yes! | | ESP8266 | NodeMCU, D1 Mini | 512 KB - 16 MB | 80 KB | Yes! | | ESP32 | DSTIKE D-duino-32 | 1 MB - 16 MB |520 KB | Yes! |

Some flash and RAM values depend on the development board or module being used.

Installation

1) Click Download Zip to download the source code from GitHub.
2) Unzip and rename the Folder name to "SimpleCLI".
3) Paste it in your library folder (usually located somewhere at documents/Arduino/libraries).
4) Restart the Arduino IDE.

Usage

SimpleCLI YouTube Tutorial

Examples

Please check out the example sketches, it's the quickest way to understand how this library works.
The following sections are for reference.

Ping with arguments command example

Include Library

#include 

Create SimpleCLI instance

SimpleCLI cli;

SimpleCLI cli(COMMAND_QUEUE_SIZE, ERROR_QUEUE_SIZE);

COMMAND_QUEUE_SIZE
and
ERROR_QUEUE_SIZE
are
int
s set to 10 commands and 10 errors by default.
The oldest command or error will be deleted automatically if the queue gets full.
You can most likely ignore the queue sizes, as those are just a safety mechanism and won't be important for most use cases.

Adding Commands

Command names should only contain upper-, lowercase letters and numbers!
Recommended are names with only lowercase letters and no numbers.

// Normal command with a defined number of arguments
// For example: echo -str "Hello" -n 3
Command myCommand = cli.addCommand("myCommandName");
Command myCommand = cli.addCmd("myCmdName");

// Single-Argument-Command that saves everything after the command name in the first argument // For example: echo this will be a single string -even with hyphen and in "quotes" // => "this will be a single string -even with hyphen and in "quotes"" will be the argument value Command mySingleArgumentCommand = cli.addSingleArgumentCommand("mySingleArgumentCommandName"); Command mySingleArgCmd = cli.addSingleArgCmd("mySingleArgCmdName");

// Boundless-Command that accepts any amount of arguments separated by spaces // For example: sum 1 2 3 // => "1", "2", "3" will the argument values Command myBoundlessCommand = cli.addBoundlessCommand("myBoundlessCommandName"); Command myBoundlessCmd = cli.addBoundlessCmd("myBoundlessCmdName");

Adding Commands with callback

Sometimes it's useful to give the command a callback function that will be executed automatically when the command was entered.
You must define these callback functions as a global void function with a

cmd
pointer as shown here:
c++
void myCallback(cmd* commandPointer) {
  Command cmd(commandPointer); // Create wrapper class instance for the pointer
  // ..
}

Now you can create a command and pass it the function pointer:
```c++ Command myCommand = cli.addCommand("myCommandName", myCallback); Command myCommand = cli.addBoundlessCommand("myCommandName", myCallback); Command myCommand = cli.addSingleArgumentCommand("myCommandName", myCallback);

Command myCommand = cli.addCmd("myCommandName", myCallback); Command myCommand = cli.addBoundlessCmd("myCommandName", myCallback); Command myCommand = cli.addSingleArgCmd("myCommandName", myCallback); ```

Adding Arguments

Keep in mind that you can only add arguments to

Command
s and not to
SingleArgumentCommand
s and
BoundlessCommand
s.
// myCommandName -argumentName "argumentValue"
Argument myArg = myCommand.addArgument("argumentName");
Argument myArg = myCommand.addArg("argumentName");

// Giving the argument a default value, means that the user does not have to specify the argument // myCommandName // myCommandName -argumentName "argumentValue" Argument myArg = myCommand.addArgument("argumentName", "DefaultValue"); Argument myArg = myCommand.addArg("argumentName", "DefaultValue");

// Positional arguments have a certain position and do not have to be named // myCommandName "argumentValue" // myCommandName -argumentName "argumentValue" Argument myArg = myCommand.addPositionalArgument("argumentName"); Argument myArg = myCommand.addPosArg("argumentName");

// Those can also have default values // myCommandName // myCommandName "argumentValue" // myCommandName -argumentName "argumentValue" Argument myArg = myCommand.addPositionalArgument("argumentName", "DefaultValue"); Argument myArg = myCommand.addPosArg("argumentName", "DefaultValue");

// Flag arguments can either be specified (set) or not, but they don't accept any value // myCommandName // myCommandName -argumentName Argument myArg = myCommand.addFlagArgument("argumentName"); Argument myArg = myCommand.addFlagArg("argumentName");

Templates

With this neat feature, you can give commands and arguments multiple names.
- A comma (

,
) separates multiple names.
- A forward slash (
/
) declares everything after it optional (until the next comma, or the end of the string).

You can combine them together.

This means a command or argument name should not use

,
and
/
as a part of the regular name!

These characters will always be interpreted as a separator.

Here are some examples:

| Name-String | Results | | ----------- | ------- | |

a,b,c,d,efg
|
a
,
b
,
c
,
d
,
efg
| |
ping,pong,test
|
ping
,
pong
,
test
| |
p/ping
|
p
,
ping
| |
p/ing/s
|
p
,
ping
,
pings
| |
p/ing/s,pong
|
p
,
ping
,
pings
,
pong
| |
p/ing/s,pong/s
|
p
,
ping
,
pings
,
pong
,
pongs
|

Parsing Input

// Inline
cli.parse("myCommand");

// From string String input = "myCommand"; cli.parse(input);

// From serial String input = Serial.readString(); cli.parse(input);

Reacting on Commands

Be aware that this is only necessary if you have commands that do not have a callback function.
Callbacks will be run automatically and the command will not wait in the queue.
```c++ // First check if a newly parsed command is available if(cli.available()) {

// Get the command out of the queue Command cmd = cli.getCommand();

// Check if it's the command you're looking for if(cmd == myCommand) {

// Get the Argument(s) you want
Argument myArgument = cmd.getArgument("argumentName"); // via name
Argument myOtherArgument = cmd.getArgument(2); // via index

// Do stuff // ...

}

} ```

Reacting on Errors

// Check if a new error occurred
if(cli.errored()) {
  CommandError e = cli.getError();

// Print the error, or do whatever you want with it Serial.println(e.toString()); }

You can also make a error callback function, like this one:

void errorCallback(cmd_error* e) {
    CommandError cmdError(e); // Create wrapper object

// Print error
Serial.print("ERROR: ");
Serial.println(cmdError.toString());

// Print command usage
if (cmdError.hasCommand()) {
    Serial.print("Did you mean \"");
    Serial.print(cmdError.getCommand().toString());
    Serial.println("\"?");
}

}

Just don't forget to add the error callback function to the SimpleCLI instance:

cli.setOnError(errorCallback);

Classes & Methods

Here is a plain overview of all classes and their methods:

SimpleCLI

SimpleCLI(int commandQueueSize = 10, int errorQueueSize = 10);

void pause(); void unpause();

void parse(String& input); void parse(const char* input); void parse(const char* input, size_t input_len);

bool available() const; bool errored() const; bool paused() const;

int countCmdQueue() const; int countErrorQueue() const;

Command getCmd(); Command getCmd(String name); Command getCmd(const char* name);

Command getCommand(); Command getCommand(String name); Command getCommand(const char* name);

CommandError getError();

Command addCmd(const char* name, void (* callback)(cmd* c) = NULL); Command addBoundlessCmd(const char* name, void (* callback)(cmd* c) = NULL); Command addSingleArgCmd(const char* name, void (* callback)(cmd* c) = NULL);

Command addCommand(const char* name, void (* callback)(cmd* c) = NULL); Command addBoundlessCommand(const char* name, void (* callback)(cmd* c) = NULL); Command addSingleArgumentCommand(const char* name, void (* callback)(cmd* c) = NULL);

String toString(bool descriptions = true) const; void toString(String& s, bool descriptions = true) const;

void setCaseSensetive(bool caseSensetive = true); void setOnError(void (* onError)(cmd_error* e));

CommandType

enum class CommandType { NORMAL, BOUNDLESS, SINGLE };

Command

Command(cmd* cmdPointer = NULL, bool persistent = COMMAND_PERSISTENT);
Command(const Command& c);
Command(Command&& c);

Command& operator=(const Command& c); Command& operator=(Command&& c);

bool operator==(const Command& c) const; bool operator!=(const Command& c) const;

operator bool() const;

bool setCaseSensetive(bool caseSensetive = true); bool setCallback(void (* callback)(cmd* c));

void setDescription(const char* description);

Argument addArg(const char* name, const char* defaultValue); Argument addArg(const char* name); Argument addPosArg(const char* name, const char* defaultValue); Argument addPosArg(const char* name); Argument addFlagArg(const char* name, const char* defaultValue = "");

Argument addArgument(const char* name, const char* defaultValue); Argument addArgument(const char* name); Argument addPositionalArgument(const char* name, const char* defaultValue); Argument addPositionalArgument(const char* name); Argument addFlagArgument(const char* name, const char* defaultValue = "");

bool equals(String name) const; bool equals(const char* name) const; bool equals(const Command& c) const;

String getName() const; int countArgs() const;

Argument getArgument(int i = 0) const; Argument getArgument(const char* name) const; Argument getArgument(String name) const; Argument getArgument(const Argument& a) const;

Argument getArg(int i = 0) const; Argument getArg(const char* name) const; Argument getArg(String name) const; Argument getArg(const Argument& a) const;

CommandType getType() const;

bool hasDescription() const; String getDescription() const;

String toString(bool description = true) const; void toString(String& s, bool description = true) const;

void run() const;

cmd* getPtr();

CommandErrorType

enum class CommandErrorType { NULL_POINTER, EMPTY_LINE, PARSE_SUCCESSFUL,
                              COMMAND_NOT_FOUND, UNKNOWN_ARGUMENT, MISSING_ARGUMENT,
                              MISSING_ARGUMENT_VALUE, UNCLOSED_QUOTE };

CommandError

CommandError(cmd_error* errorPointer = NULL, bool persistent = COMMAND_ERROR_PERSISTENT);
CommandError(const CommandError& e);
CommandError(CommandError&& e);

CommandError& operator=(const CommandError& e); CommandError& operator=(CommandError&& e);

bool operator==(const CommandError& e) const; bool operator!=(const CommandError& e) const;

bool operator>(const CommandError& e) const; bool operator=(const CommandError& e) const; bool operator<=(const CommandError& e) const;

operator bool() const;

bool hasCommand() const; bool hasArgument() const; bool hasData() const;

bool hasCmd() const; bool hasArg() const;

CommandErrorType getType() const; Command getCommand() const; Argument getArgument() const; String getData() const; String getMessage() const;

Command getCmd() const; Argument getArg() const; String getMsg() const;

String toString() const; void toString(String& s) const;

cmd_error* getPtr();

ArgumentType

enum class ArgumentType { NORMAL, POSITIONAL, FLAG };

Argument

Argument(arg* argPointer = NULL, bool persistent = ARGUMENT_PERSISTENT);
Argument(const Argument& a);
Argument(Argument&& a);

Argument& operator=(const Argument& a); Argument& operator=(Argument&& a);

bool operator==(const Argument& a) const; bool operator!=(const Argument& a) const;

operator bool() const;

bool isSet() const; bool isRequired() const; bool isOptional() const; bool hasDefaultValue() const;

bool isReq() const; bool isOpt() const;

String getName() const; String getValue() const;

ArgumentType getType() const;

String toString() const; void toString(String& s) const;

bool equals(String name, bool caseSensetive = false) const; bool equals(const char* name, bool caseSensetive = false) const; bool equals(const Argument& a, bool caseSensetive = false) const;

arg* getPtr();

License

This software is licensed under the MIT License. See the license file for details.

We use cookies. If you continue to browse the site, you agree to the use of cookies. For more information on our use of cookies please see our Privacy Policy.