EmbeddedTerminal

EmbeddedTerminal is a platform-independent C++ library for embedded systems providing a complete terminal/shell implementation with command parsing, file system abstraction, and network interfaces. Works seamlessly across Arduino, ESP-IDF, and native platforms.

Disclaimer

The Readme is partially generated using AI but was proven to be inaccurate in some places. Please refer to the source code and documentation for the most accurate information.

Features

• ✅ Platform Independent: Works on Arduino, ESP32 (ESP-IDF & Arduino), and native environments
• ✅ Command System: Register and execute custom commands with keyword-based parsing
• ✅ File System Abstraction: Unified interface for different file systems (SPIFFS, SD, LittleFS, Native)
• ✅ Built-in Commands: cat, cd, ls, mkdir, rm, rmdir, df, tail, help, ip, download
• ✅ Network Interface: Abstract network interface for displaying connection information
• ✅ Cross-Platform String Handling: Custom ETString class works across all platforms
• ✅ Directory Navigation: Full path traversal and manipulation
• ✅ Comprehensive Testing: Mock implementations and test suites included

Installation

PlatformIO (Recommended)

Add to your platformio.ini:

[env]
lib_deps = 
    boeserfrosch/EmbeddedTerminal@^0.2.1

Arduino Library Manager

1. Open Arduino IDE
2. Go to Sketch → Include Library → Manage Libraries
3. Search for "EmbeddedTerminal"
4. Click Install

Manual Installation

1. Download or clone this repository
2. Copy the folder to your libraries directory:
   • Arduino: Documents/Arduino/libraries/
   • PlatformIO: Include in lib_deps or place in lib/

Quick Start

Basic Terminal Setup (Recommended)

Full example: examples/BasicTerminal/BasicTerminal.ino

#include <Terminal.h>
#include <BuiltinCommandFactory.h>
#include <hal/ArduinoFileSystem.h>

ArduinoFileSystem fs;
DirectoryNavigator nav(&fs);
Terminal term(Serial);
BuiltinCommandFactory factory;

void setup() {
    Serial.begin(115200);
    
    // Register all built-in commands using factory
    factory.registerAllCommands(term, nav, nullptr);
    
    Serial.println("Terminal ready! Type 'help' for available commands.");
    Serial.print("> ");
}

void loop() {
    term.loop();
}

Selective Command Registration

Register only specific command categories using flags:

Full example: examples/SelectiveRegistration/SelectiveRegistration.ino

#include <BuiltinCommandFlags.h>

BuiltinCommandFactory factory;

void setup() {
    Serial.begin(115200);
    
    // Register only filesystem navigation commands
    factory.registerFilesystemCommands(term, nav, CMD_LS | CMD_CD | CMD_CAT);
    
    // Register disk usage command
    factory.registerDiskCommands(term, nav);
    
    // Register network commands (requires INetworkInterface)
    // factory.registerNetworkCommands(term, networkInterface);
    
    // Register help command
    factory.registerHelpCommand(term);
    
    Serial.println("Terminal ready! Type 'help' for available commands.");
    Serial.print("> ");
}

With Network Interface (ESP32)

Full example: examples/NetworkTerminal/NetworkTerminal.ino

#include <Terminal.h>
#include <BuiltinCommandFactory.h>
#include <hal/ESPNetworkInterface.h>

ArduinoFileSystem fs;
DirectoryNavigator nav(&fs);
ESPNetworkInterface netInterface;
Terminal term(Serial);
BuiltinCommandFactory factory;

void setup() {
    Serial.begin(115200);
    WiFi.begin("SSID", "password");
    
    // Register all commands including network
    factory.registerAllCommands(term, nav, &netInterface);
    
    Serial.println("Terminal ready! Type 'help' for available commands.");
    Serial.print("> ");
}

void loop() {
    term.loop();
}

Custom Commands

Full example: examples/SimpleCustomCommand/SimpleCustomCommand.ino

#include <Terminal.h>
#include <interfaces/ICommand.h>
#include <DirectoryNavigator.h>

// Platform-specific file system
#if defined(ESP32)
#include <hal/SDMMCFileSystem.h>
SDMMCFileSystem fs;
#elif defined(ARDUINO)
#include <hal/ArduinoFileSystem.h>
ArduinoFileSystem fs;
#else
#include <hal/NativeFileSystem.h>
NativeFileSystem fs;
#endif

class MyCommand : public ICommand {
public:
    ETString trigger(const ETString &keyword, const ETString &additional) override {
        return "Hello from custom command!";
    }
    
    ETString usage(const ETString &keyword) override {
        return "mycmd - Custom command example";
    }
};

DirectoryNavigator nav(&fs);
MyCommand myCmd;
Terminal term(Serial);

void setup() {
    Serial.begin(115200);
    
    // Register custom command
    term.registerCommand("mycmd", &myCmd);
    
    Serial.println("Terminal ready! Type 'help' for available commands.");
    Serial.print("> ");
}

void loop() {
    term.loop();
}

See also: examples/CustomCommand/CustomCommand.ino for more advanced custom command examples (echo, uptime, LED control)

Auto Completion

EmbeddedTerminal supports TAB-based auto completion for commands and file paths. When the user presses TAB while typing, the terminal:

1. Looks up the command being typed
2. Asks that command for completion suggestions
3. Auto-fills the longest common prefix
4. Displays remaining options if multiple matches exist

Using Auto Completion

No setup required! Auto completion works automatically with built-in commands that support it:

• cd <TAB>: Suggests available directories
• cat <TAB>: Suggests available files and directories
• ls <TAB>: Suggests available directories
• Any path argument: Auto-complete works mid-word on any path

Example Usage

> cd /t[TAB]
> cd /tmp/
  data/
  logs/
  cache/

If only one match, auto-completes immediately:

> cat /data/m[TAB]
> cat /data/message.txt

Adding Auto Completion to Custom Commands

To add auto completion to your custom command, implement the IAutoCompleter interface:

#include <Terminal.h>
#include <interfaces/ICommand.h>
#include <interfaces/IAutoCompleter.h>
#include <DefaultAutoCompleters.h>

class MyAutocompleteCommand : public ICommand, public IAutoCompleter {
public:
    MyAutocompleteCommand(DirectoryNavigator &nav) : nav_(nav) {}
    
    ETString trigger(const ETString &keyword, const ETString &additional) override {
        return "Command: " + additional;
    }
    
    ETString usage(const ETString &keyword) override {
        return "myautocmd [argument] - Command with auto completion";
    }
    
    // Provide auto completion suggestions
    ETVector<ETString> getSuggestions(const ETString &partial) override {
        ETVector<ETString> suggestions;
        
        // Return suggestions that match the partial input
        // Example: suggest files in current directory
        ETVector<ETString> files = nav_.ls("/");
        for (const auto &file : files) {
            if (file.startsWith(partial)) {
                suggestions.push_back(file);
            }
        }
        
        return suggestions;
    }

private:
    DirectoryNavigator &nav_;
};

// Register like any other command
MyAutocompleteCommand myCmd(nav);
term.registerCommand("myautocmd", &myCmd);

Built-in Auto Completers (available in src/DefaultAutoCompleters.h):

• CommandCompleter: Suggests available command names from the terminal's command map
• FilePathCompleter: Suggests files and directories that match the partial path
• DirectoryCompleter: Suggests only directories (useful for cd, ls, etc.)

You can use these in your own commands:

class MyCommand : public ICommand, public IAutoCompleter {
    DirectoryNavigator &nav_;
    
    ETVector<ETString> getSuggestions(const ETString &partial) override {
        // Use DirectoryCompleter to suggest directories
        DirectoryCompleter completer(nav_);
        return completer.getSuggestions(partial);
    }
};

Supported Platforms

| Platform | Framework | Status | Notes | | ---------- | ----------- | -------- | ------- | | ESP32-S3 | ESP-IDF | ✅ Tested | Full support | | ESP32-S3 | Arduino | ✅ Tested | Full support | | ESP32 | ESP-IDF | ✅ Compatible | Should work | | ESP32 | Arduino | ✅ Compatible | Should work | | Arduino | Arduino | ✅ Compatible | Requires ArxContainer | | Native | Desktop C++ | ✅ Tested | For testing/development |

Built-in Commands

| Command | Description | Example | | --------- | ------------- | --------- | | help | List available commands | help | | cat | Display file contents | cat file.txt | | cd | Change directory | cd /folder | | ls | List directory contents | ls, ls -l, ls -d | | mkdir | Create directory | mkdir newfolder | | rm | Remove file | rm file.txt | | rmdir | Remove directory | rmdir folder | | df | Show disk usage | df | | tail | Show end of file | tail file.txt | | ip | Show network interfaces | ip, ip eth0 | | download | Download file via network | download url |

API Reference

BuiltinCommandFactory

Factory class for creating and managing built-in commands.

class BuiltinCommandFactory {
public:
    // Register all built-in commands
    void registerAllCommands(Terminal &term, DirectoryNavigator &nav, INetworkInterface *net);
    
    // Register command categories
    void registerFilesystemCommands(Terminal &term, DirectoryNavigator &nav);
    void registerFilesystemCommands(Terminal &term, DirectoryNavigator &nav, uint16_t flags);
    void registerDiskCommands(Terminal &term, DirectoryNavigator &nav);
    void regis