console.hpp

Go to the documentation of this file.

// SPDX-License-Identifier: Apache-2.0
// Copyright 2026 Chris Leishman
 
#pragma once
 
#include <idfxx/cpu>
#include <idfxx/error>
#include <idfxx/gpio>
#include <idfxx/uart>
 
#include <esp_console.h>
#include <filesystem>
#include <functional>
#include <optional>
#include <string_view>
#include <utility>
 
namespace idfxx::console {
 
// =============================================================================
// Command types
// =============================================================================
 
using handler = std::move_only_function<int(int argc, char** argv)>;
 
struct command {
    std::string_view name;      
    std::string_view help = {}; 
    std::string_view hint = {}; 
    void* argtable = nullptr;   
};
 
// =============================================================================
// Command registration (free functions)
// =============================================================================
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void register_command(const command& cmd, handler callback);
 
void deregister_command(std::string_view name);
 
void register_help_command();
 
void deregister_help_command();
#endif
 
[[nodiscard]] result<void> try_register_command(const command& cmd, handler callback);
 
result<void> try_deregister_command(std::string_view name);
 
[[nodiscard]] result<void> try_register_help_command();
 
result<void> try_deregister_help_command();
 
// =============================================================================
// Low-level console (non-REPL use)
// =============================================================================
 
struct config {
    size_t max_cmdline_length = 256; 
    size_t max_cmdline_args = 32;    
    int hint_color = 39;             
    bool hint_bold = false;          
};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
void init(const config& cfg = {});
 
void deinit();
 
int run(std::string_view cmdline);
#endif
 
[[nodiscard]] result<void> try_init(const config& cfg = {});
 
result<void> try_deinit();
 
[[nodiscard]] result<int> try_run(std::string_view cmdline);
 
// =============================================================================
// REPL
// =============================================================================
 
class repl {
public:
    struct config {
        size_t max_history_len = 32;                         
        std::filesystem::path history_save_path = {};        
        size_t task_stack_size = 4096;                       
        task_priority priority = 2;                          
        std::optional<core_id> core_affinity = std::nullopt; 
        std::string_view prompt = {};                        
        size_t max_cmdline_length = 0;                       
    };
 
    // =========================================================================
    // UART backend
    // =========================================================================
 
#if CONFIG_ESP_CONSOLE_UART_DEFAULT || CONFIG_ESP_CONSOLE_UART_CUSTOM || defined(__DOXYGEN__)
    static constexpr uart_port default_uart_port = static_cast<uart_port>(CONFIG_ESP_CONSOLE_UART_NUM);
 
    struct uart_config {
        uart_port port = default_uart_port;               
        int baud_rate = CONFIG_ESP_CONSOLE_UART_BAUDRATE; 
        gpio tx_gpio = gpio::nc();                        
        gpio rx_gpio = gpio::nc();                        
    };
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit repl(const config& cfg, const uart_config& uart);
#endif
 
    [[nodiscard]] static result<repl> make(const config& cfg, const uart_config& uart);
#endif // UART
 
    // =========================================================================
    // USB CDC backend
    // =========================================================================
 
#if CONFIG_ESP_CONSOLE_USB_CDC || (defined(__DOXYGEN__) && SOC_USB_OTG_SUPPORTED)
    struct usb_cdc_config {};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit repl(const config& cfg, const usb_cdc_config& usb_cdc);
#endif
 
    [[nodiscard]] static result<repl> make(const config& cfg, const usb_cdc_config& usb_cdc);
#endif // USB CDC
 
    // =========================================================================
    // USB Serial JTAG backend
    // =========================================================================
 
#if CONFIG_ESP_CONSOLE_USB_SERIAL_JTAG || (defined(__DOXYGEN__) && SOC_USB_SERIAL_JTAG_SUPPORTED)
    struct usb_serial_jtag_config {};
 
#ifdef CONFIG_COMPILER_CXX_EXCEPTIONS
    [[nodiscard]] explicit repl(const config& cfg, const usb_serial_jtag_config& usb_jtag);
#endif
 
    [[nodiscard]] static result<repl> make(const config& cfg, const usb_serial_jtag_config& usb_jtag);
#endif // USB Serial JTAG
 
    // =========================================================================
    // Lifecycle
    // =========================================================================
 
    ~repl();
 
    repl(const repl&) = delete;
    repl& operator=(const repl&) = delete;
 
    repl(repl&& other) noexcept;
 
    repl& operator=(repl&& other) noexcept;
 
    [[nodiscard]] esp_console_repl_t* idf_handle() const noexcept { return _handle; }
 
private:
    explicit repl(esp_console_repl_t* handle)
        : _handle(handle) {}
 
    void _stop_and_delete() noexcept;
 
    static esp_console_repl_config_t _translate_config(const config& cfg);
 
    esp_console_repl_t* _handle = nullptr;
};
 
 
} // namespace idfxx::console