Home

Awesome

SimpleCLI

<p align="center"><img alt="SimpleCLI Logo" src="img/simplecli.gif" width="150"></p> <p align="center"> <b>A Command Line Interface Library for Arduino!</b><br> Add commands to your project without hassle.<br> <br> <a href="https://www.ardu-badge.com/SimpleCLI" target="_blank"><img alt="Ardu Badge for SimpleCLI Library" src="https://www.ardu-badge.com/badge/SimpleCLI.svg"></a><br> <br> <a href='https://ko-fi.com/G2G75FA4V' target='_blank'><img height='36' style='border:0px;height:36px;' src='https://cdn.ko-fi.com/cdn/kofi3.png?v=3' border='0' alt='Buy Me a Coffee at ko-fi.com' /></a> </p>

Cowsay command example

Projects

A list of projects that make use of this library:

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):

ChipsetBoard(s)FlashRAMSupport
ATtiny85Digispark8 KB512 ByteNo! (Does not compile C++11)
ATmega328PArduino Nano, Arduino Uno32 KB2 KBWorks for small projects
ATmega32u4Arduino Leonardo, Pro Micro32 KB2,560 ByteWorks for small projects
ATSAMD21G18Arduino MKR WiFi 1010256 KB32 KBYes!
ATSAMD51G19Adafruit ItsyBitsy M4 Express512 KB192 KBYes!
ESP8266NodeMCU, D1 Mini512 KB - 16 MB80 KBYes!
ESP32DSTIKE D-duino-321 MB - 16 MB520 KBYes!

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 <SimpleCLI.h>

Create SimpleCLI instance

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.

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:

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:

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 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");

Templates

With this neat feature, you can give commands and arguments multiple names.

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-StringResults
a,b,c,d,efga, b, c, d, efg
ping,pong,testping, pong, test
p/pingp, ping
p/ing/sp, ping, pings
p/ing/s,pongp, ping, pings, pong
p/ing/s,pong/sp, 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.

// 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;
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.