Ping

The Ping component provides a C++ wrapper around esp_ping, including a simple CLI menu for running ping tests.

API Reference

Header File

Classes

class Ping : public espp::BaseComponent

ICMP Echo (Ping) helper wrapping ESP-IDF ping API.

This class owns the ping session lifecycle (create/start/delete) and exposes a simple C++ functional interface for receiving ping results. The call to run() is synchronous and returns when the session finishes or an error occurs.

Example usage:

Simple Example

    std::atomic<bool> got_ip{false};
    // Simple WiFi STA bring-up assumed configured via menu
    espp::WifiSta wifi_sta({.ssid = "",
                            .password = "",
                            .num_connect_retries = 5,
                            .on_connected = nullptr,
                            .on_disconnected = nullptr,
                            .on_got_ip =
                                [&](ip_event_got_ip_t *eventdata) {
                                  logger.info("got IP: {}.{}.{}.{}",
                                              IP2STR(&eventdata->ip_info.ip));
                                  got_ip = true;
                                },
                            .log_level = espp::Logger::Verbosity::INFO});
    // create the ping instance
    espp::Ping ping({.session =
                         {
                             .target_host = "google.com",
                         },
                     .callbacks = {
                         .on_session_start = [&]() { logger.info("Ping session started"); },
                         .on_reply =
                             [&](uint32_t seq, uint32_t ttl, uint32_t time_ms, uint32_t bytes) {
                               logger.info("Reply: seq={} ttl={} time={}ms bytes={}", seq, ttl,
                                           time_ms, bytes);
                             },
                         .on_timeout = [&]() { logger.warn("Request timed out"); },
                         .on_end =
                             [&](const espp::Ping::Stats &stats) {
                               logger.info("Ping session ended: {}", stats);
                             },
                     },
                     .log_level = espp::Logger::Verbosity::DEBUG});
    // wait for wifi connection
    while (!got_ip) {
      std::this_thread::sleep_for(std::chrono::milliseconds(100));
    }
    // run the ping session (synchronously)
    std::error_code ec;
    if (!ping.run(ec)) {
      logger.error("Ping failed to start: {}", ec.message());
    }

CLI Example

    // Simple WiFi STA bring-up assumed configured via menu
    espp::WifiSta wifi_sta({.ssid = "",
                            .password = "",
                            .num_connect_retries = 5,
                            .on_connected = nullptr,
                            .on_disconnected = nullptr,
                            .on_got_ip =
                                [&](ip_event_got_ip_t *eventdata) {
                                  logger.info("got IP: {}.{}.{}.{}",
                                              IP2STR(&eventdata->ip_info.ip));
                                },
                            .log_level = espp::Logger::Verbosity::INFO});
    // create the wifi menu to allow connecting to APs
    espp::WifiStaMenu wifi_menu(wifi_sta);

    // create the ping instance and menu
    espp::Ping ping({.session =
                         {
                             .target_host = "1.1.1.1",
                             .task_stack_size = 8192,
                         },
                     .callbacks = {
                         .on_session_start = [&]() { logger.info("Ping session started"); },
                         .on_reply =
                             [&](uint32_t seq, uint32_t ttl, uint32_t time_ms, uint32_t bytes) {
                               logger.info("Reply: seq={} ttl={} time={}ms bytes={}", seq, ttl,
                                           time_ms, bytes);
                             },
                         .on_timeout = [&]() { logger.warn("Request timed out"); },
                         .on_end =
                             [&](const espp::Ping::Stats &stats) {
                               logger.info("Ping session ended: {}", stats);
                             },
                     },
                     .log_level = espp::Logger::Verbosity::DEBUG});
    espp::Ping::Menu ping_menu(ping);

    auto root = std::make_unique<cli::Menu>("root", "root menu");
    root->Insert(wifi_menu.get());
    root->Insert(ping_menu.get());

    cli::Cli cli(std::move(root));
    cli::SetColor();
    cli.ExitAction([](auto &out) { out << "Goodbye and thanks for all the fish.\n"; });

    espp::Cli input(cli);
    input.SetInputHistorySize(10);
    input.Start();

Public Types

typedef std::function<void()> session_start_cb_t

Alias for the ping session start callback.

typedef std::function<void(uint32_t seq, uint32_t ttl, uint32_t time_ms, uint32_t bytes)> reply_cb_t

Alias for the ping reply callback.

typedef std::function<void()> timeout_cb_t

Alias for the ping timeout callback.

typedef std::function<void(const Stats &stats)> end_cb_t

Alias for the ping session end callback.

Public Functions

explicit Ping(const Config &config)

Construct a Ping helper.

Parameters:

config – Ping configuration and callbacks.

~Ping()

Destructor cleans up any active session.

bool run(std::error_code &ec)

Run the ping session synchronously, blocking until complete or stopped.

Parameters:

ec – Error code set on failure.

Returns:

true if session completed successfully, false otherwise.

inline bool run(const SessionConfig &session_config, std::error_code &ec)

Set new session configuration and run the ping session synchronously.

Parameters:

  • session_config – New session configuration.

  • ec – Error code set on failure.

Returns:

true if session completed successfully, false otherwise.

bool run_async(std::error_code &ec)

Start the ping session asynchronously, returning immediately.

Parameters:

ec – Error code set on failure.

Returns:

true if the session started, false otherwise.

bool run_sync(std::error_code &ec)

Run the ping session synchronously, blocking until complete or stopped.

Parameters:

ec – Error code set on failure.

Returns:

true if the session completed, false otherwise.

void stop()

Stop an active ping session.

bool is_running() const

Check if a ping session is currently running.

Returns:

true if a session is active, false otherwise.

void set_target_host(std::string_view host)

Set the target host (thread-safe).

Parameters:

host – Hostname or dotted-quad IPv4 address.

std::string get_target_host() const

Get the current target host.

Returns:

Target host (empty string if not set).

void set_count(uint32_t count)

Set number of echo requests to send.

Parameters:

count – Number of requests (0 = infinite).

uint32_t get_count() const

Get number of echo requests to send.

Returns:

Number of requests (0 = infinite).

void set_interval_ms(uint32_t interval_ms)

Set interval between requests in milliseconds.

Parameters:

interval_ms – Interval in milliseconds.

uint32_t get_interval_ms() const

Get interval between requests in milliseconds.

Returns:

Interval in milliseconds.

void set_timeout_ms(uint32_t timeout_ms)

Set per-request timeout in milliseconds.

Parameters:

timeout_ms – Timeout in milliseconds.

uint32_t get_timeout_ms() const

Get per-request timeout in milliseconds.

Returns:

Timeout in milliseconds.

void set_data_size(uint32_t data_size)

Set payload size in bytes.

Parameters:

data_size – Payload size in bytes.

uint32_t get_data_size() const

Get payload size in bytes.

Returns:

Payload size in bytes.

void set_ttl(uint8_t ttl)

Set time-to-live value.

Parameters:

ttl – Time-to-live value.

uint8_t get_ttl() const

Get time-to-live value.

Returns:

Time-to-live value.

void set_tos(uint8_t tos)

Set IP type-of-service value.

Parameters:

tos – Type-of-service value.

uint8_t get_tos() const

Get IP type-of-service value.

Returns:

Type-of-service value.

void set_task_stack_size(size_t bytes)

Set ping task stack size.

Parameters:

bytes – Stack size in bytes.

size_t get_task_stack_size() const

Get ping task stack size.

Returns:

Stack size in bytes.

SessionConfig get_session_config() const

Get a copy of the current session configuration (thread-safe).

Returns:

Current session configuration.

inline Stats get_stats() const

Get statistics from the last completed ping session.

Returns:

Statistics structure (all zeros if no session completed).

inline const std::string &get_name() const

Get the name of the component

Note

This is the tag of the logger

Returns:

A const reference to the name of the component

inline void set_log_tag(const std::string_view &tag)

Set the tag for the logger

Parameters:

tag – The tag to use for the logger

inline espp::Logger::Verbosity get_log_level() const

Get the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Returns:

The verbosity level of the logger

inline void set_log_level(espp::Logger::Verbosity level)

Set the log level for the logger

See also

Logger::Verbosity

See also

Logger::set_verbosity

Parameters:

level – The verbosity level to use for the logger

inline void set_log_verbosity(espp::Logger::Verbosity level)

Set the log verbosity for the logger

See also

set_log_level

See also

Logger::Verbosity

See also

Logger::set_verbosity

Note

This is a convenience method that calls set_log_level

Parameters:

level – The verbosity level to use for the logger

inline espp::Logger::Verbosity get_log_verbosity() const

Get the log verbosity for the logger

See also

get_log_level

See also

Logger::Verbosity

See also

Logger::get_verbosity

Note

This is a convenience method that calls get_log_level

Returns:

The verbosity level of the logger

inline void set_log_rate_limit(std::chrono::duration<float> rate_limit)

Set the rate limit for the logger

See also

Logger::set_rate_limit

Note

Only calls to the logger that have _rate_limit suffix will be rate limited

Parameters:

rate_limit – The rate limit to use for the logger

struct Callbacks

User-provided callbacks for ping events.

Public Members

session_start_cb_t on_session_start

Called right before the first probe is sent (optional).

reply_cb_t on_reply

Called for each successful reply.

timeout_cb_t on_timeout

Called when a probe times out. One call per timed out probe.

end_cb_t on_end

Called at session end with summary statistics.

struct Config

Configuration for a ping session.

Public Members

SessionConfig session = {}

Ping session parameters.

Callbacks callbacks = {}

Optional user callbacks.

Logger::Verbosity log_level = {Logger::Verbosity::WARN}

Component log level.

class Menu

Small CLI wrapper for invoking ping from a menu.

Public Functions

inline explicit Menu(std::reference_wrapper<Ping> ping)

Construct a CLI wrapper bound to a Ping instance.

Parameters:

ping – Reference to a Ping instance.

std::unique_ptr<cli::Menu> get(std::string_view name = "ping", std::string_view description = "Ping menu")

Create a CLI submenu with a `run <host>` command.

Parameters:

  • name – Menu name (default: “ping”)

  • description – Menu description (default: “Ping menu”)

Returns:

Unique pointer to the menu instance.

struct SessionConfig

Configuration for an individual ping session.

Public Members

std::string target_host

Hostname or dotted-quad IPv4 address.

size_t task_stack_size = {4096}

Stack size for the ping task.

uint32_t count = {5}

Number of echo requests to send.

uint32_t interval_ms = {1000}

Interval between requests in milliseconds.

uint32_t timeout_ms = {1000}

Per-request timeout in milliseconds.

uint32_t data_size = {0}

Payload size in bytes.

uint8_t ttl = {64}

Time-to-live in the range [1, 255].

uint8_t tos = {0}

Type of service in the range [0, 255].

struct Stats

Statistics from a completed ping session.

Public Members

uint32_t transmitted = {0}

Number of packets transmitted.

uint32_t received = {0}

Number of packets received.

float loss_pct = {0.0f}

Packet loss percentage.

uint32_t avg_ms = {0}

Average round-trip time in milliseconds.

uint32_t min_ms{std::numeric_limits<uint32_t>::max()}

Minimum round-trip time in milliseconds.

uint32_t max_ms = {0}

Maximum round-trip time in milliseconds.

class Menu

Small CLI wrapper for invoking ping from a menu.

Public Functions

inline explicit Menu(std::reference_wrapper<Ping> ping)

Construct a CLI wrapper bound to a Ping instance.

Parameters:

ping – Reference to a Ping instance.

std::unique_ptr<cli::Menu> get(std::string_view name = "ping", std::string_view description = "Ping menu")

Create a CLI submenu with a `run <host>` command.

Parameters:

  • name – Menu name (default: “ping”)

  • description – Menu description (default: “Ping menu”)

Returns:

Unique pointer to the menu instance.