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.
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
See also
- 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
See also
- 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
See also
See also
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
See also
See also
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
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.
-
session_start_cb_t on_session_start
-
struct Config
Configuration for a ping session.
-
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.
-
inline explicit Menu(std::reference_wrapper<Ping> ping)
-
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].
-
std::string target_host
-
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.
-
uint32_t transmitted = {0}
-
typedef std::function<void()> session_start_cb_t
-
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.
-
inline explicit Menu(std::reference_wrapper<Ping> ping)