A Command Line Interface Library for Arduino!
Add commands to your project without hassle.
🐦 Twitter
| 📺 YouTube
| 🌍 spacehuhn.io
Support this project and become a patron on patreon.com/spacehuhn.
Also available: Stickers!
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
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.
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.
- Click Download Zip to download the source code from GitHub.
- Unzip and rename the Folder name to "SimpleCLI".
- Paste it in your library folder (usually located somewhere at documents/Arduino/libraries).
- Restart the Arduino IDE.
Please check out the example sketches, it's the quickest way to understand how this library works.
The following sections are for reference.
#include<SimpleCLI.h>SimpleCLI cli;
SimpleCLI cli(COMMAND_QUEUE_SIZE, ERROR_QUEUE_SIZE);COMMAND_QUEUE_SIZE and ERROR_QUEUE_SIZE are ints 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.
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");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:
voidmyCallback(cmd* commandPointer) {
Command cmd(commandPointer); // Create wrapper class instance for the pointer// ..
}Now you can create a command and pass it the function pointer:
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);Keep in mind that you can only add arguments to Commands and not to SingleArgumentCommands and BoundlessCommands.
// 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");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 |
// Inline
cli.parse("myCommand");
// From string
String input = "myCommand";
cli.parse(input);
// From serial
String input = Serial.readString();
cli.parse(input);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.
// First check if a newly parsed command is availableif(cli.available()) {
// Get the command out of the queue
Command cmd = cli.getCommand();
// Check if it's the command you're looking forif(cmd == myCommand) {
// Get the Argument(s) you want
Argument myArgument = cmd.getArgument("argumentName"); // via name
Argument myOtherArgument = cmd.getArgument(2); // via index// Do stuff// ...
}
}// Check if a new error occurredif(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:
voiderrorCallback(cmd_error* e) {
CommandError cmdError(e); // Create wrapper object// Print error
Serial.print("ERROR: ");
Serial.println(cmdError.toString());
// Print command usageif (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);Here is a plain overview of all classes and their methods:
SimpleCLI(int commandQueueSize = 10, int errorQueueSize = 10);
voidpause();
voidunpause();
voidparse(String& input);
voidparse(constchar* input);
voidparse(constchar* input, size_t input_len);
boolavailable() const;
boolerrored() const;
boolpaused() const;
intcountCmdQueue() const;
intcountErrorQueue() const;
Command getCmd();
Command getCmd(String name);
Command getCmd(constchar* name);
Command getCommand();
Command getCommand(String name);
Command getCommand(constchar* name);
CommandError getError();
Command addCmd(constchar* name, void (* callback)(cmd* c) = NULL);
Command addBoundlessCmd(constchar* name, void (* callback)(cmd* c) = NULL);
Command addSingleArgCmd(constchar* name, void (* callback)(cmd* c) = NULL);
Command addCommand(constchar* name, void (* callback)(cmd* c) = NULL);
Command addBoundlessCommand(constchar* name, void (* callback)(cmd* c) = NULL);
Command addSingleArgumentCommand(constchar* name, void (* callback)(cmd* c) = NULL);
String toString(bool descriptions = true) const;
voidtoString(String& s, bool descriptions = true) const;
voidsetCaseSensetive(bool caseSensetive = true);
voidsetOnError(void (* onError)(cmd_error* e));enumclassCommandType { NORMAL, BOUNDLESS, SINGLE };Command(cmd* cmdPointer = NULL, bool persistent = COMMAND_PERSISTENT);
Command(const Command& c);
Command(Command&& c);
Command& operator=(const Command& c);
Command& operator=(Command&& c);
booloperator==(const Command& c) const;
booloperator!=(const Command& c) const;
operatorbool() const;
boolsetCaseSensetive(bool caseSensetive = true);
boolsetCallback(void (* callback)(cmd* c));
voidsetDescription(constchar* description);
Argument addArg(constchar* name, constchar* defaultValue);
Argument addArg(constchar* name);
Argument addPosArg(constchar* name, constchar* defaultValue);
Argument addPosArg(constchar* name);
Argument addFlagArg(constchar* name, constchar* defaultValue = "");
Argument addArgument(constchar* name, constchar* defaultValue);
Argument addArgument(constchar* name);
Argument addPositionalArgument(constchar* name, constchar* defaultValue);
Argument addPositionalArgument(constchar* name);
Argument addFlagArgument(constchar* name, constchar* defaultValue = "");
boolequals(String name) const;
boolequals(constchar* name) const;
boolequals(const Command& c) const;
String getName() const;
intcountArgs() const;
Argument getArgument(int i = 0) const;
Argument getArgument(constchar* name) const;
Argument getArgument(String name) const;
Argument getArgument(const Argument& a) const;
Argument getArg(int i = 0) const;
Argument getArg(constchar* name) const;
Argument getArg(String name) const;
Argument getArg(const Argument& a) const;
CommandType getType() const;
boolhasDescription() const;
String getDescription() const;
String toString(bool description = true) const;
voidtoString(String& s, bool description = true) const;
voidrun() const;
cmd* getPtr();enumclassCommandErrorType { NULL_POINTER, EMPTY_LINE, PARSE_SUCCESSFUL,
COMMAND_NOT_FOUND, UNKNOWN_ARGUMENT, MISSING_ARGUMENT,
MISSING_ARGUMENT_VALUE, UNCLOSED_QUOTE };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);
booloperator==(const CommandError& e) const;
booloperator!=(const CommandError& e) const;
booloperator>(const CommandError& e) const;
booloperator<(const CommandError& e) const;
booloperator>=(const CommandError& e) const;
booloperator<=(const CommandError& e) const;
operatorbool() const;
boolhasCommand() const;
boolhasArgument() const;
boolhasData() const;
boolhasCmd() const;
boolhasArg() 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;
voidtoString(String& s) const;
cmd_error* getPtr();enumclassArgumentType { NORMAL, POSITIONAL, FLAG };Argument(arg* argPointer = NULL, bool persistent = ARGUMENT_PERSISTENT);
Argument(const Argument& a);
Argument(Argument&& a);
Argument& operator=(const Argument& a);
Argument& operator=(Argument&& a);
booloperator==(const Argument& a) const;
booloperator!=(const Argument& a) const;
operatorbool() const;
boolisSet() const;
boolisRequired() const;
boolisOptional() const;
boolhasDefaultValue() const;
boolisReq() const;
boolisOpt() const;
String getName() const;
String getValue() const;
ArgumentType getType() const;
String toString() const;
voidtoString(String& s) const;
boolequals(String name, bool caseSensetive = false) const;
boolequals(constchar* name, bool caseSensetive = false) const;
boolequals(const Argument& a, bool caseSensetive = false) const;
arg* getPtr();This software is licensed under the MIT License. See the license file for details.