PING Development Guide_Rev1.2

中文

Revision History

Version	Date	Author	Reviewer	Revision Content
Rev1.0	2023-09-19	LJZ	zlc	Initial document creation
Rev1.1	2024-03-25	sxx		Changed document name
Rev1.2	2025-05-14	LJZ		Optimized document format

1 Introduction

This document introduces the LTE-EC71X PING interface APIs. The API interfaces are declared in the file components/kernel/lierda_api/liot_ping/liot_ping.h.

2 API Function Overview

Function	Description
liot_ping_start()	Enable ping function

3 Type Descriptions

3.1 liot_ping_result_code_e

PING result error codes.

1. Declaration

typedef enum
{
    LIOT_PING_OK                      = 0,
    LIOT_PING_ERR_INVALID_PARAM       = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 552 /* Invalid parameters   */,
    LIOT_PING_ERR_SOCKET_NEW_FAILURE  = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 554 /* Create socket failed */,
    LIOT_PING_ERR_SOCKET_BIND_FAILURE = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 556 /* Socket bind failed   */,
    LIOT_PING_ERR_DNS_FAILURE         = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 565 /* DNS parse failed     */,
    LIOT_PING_ERR_TIMEOUT             = (LIOT_COMPONENT_LWIP_SOCKET << 16) | 569 /* Operation timeout    */,
} liot_ping_result_code_e;

2. Parameters

• LIOT_PING_OK: Execution successful.

• LIOT_PING_ERR_INVALID_PARAM: Parameter error.

• LIOT_PING_ERR_SOCKET_NEW_FAILURE: Failed to create socket.

• LIOT_PING_ERR_SOCKET_BIND_FAILURE: Socket bind failed.

• LIOT_PING_ERR_DNS_FAILURE: DNS resolution failed.

• LIOT_PING_ERR_TIMEOUT: Operation timeout.

3.2 liot_ping_event_type_e

Ping event type structure definition is as follows

1. Declaration

typedef enum
{
    LIOT_PING_STATS   = 1,
    LIOT_PING_SUMMARY = 2,
} liot_ping_event_type_e;

2. Parameters

• LIOT_PING_STATS: Events during ping process.

• LIOT_PING_SUMMARY: Events at ping completion.

3.3 liot_ping_config_type_s

Ping configuration information structure definition is as follows

1. Declaration

typedef struct
{
    uint32_t num_data_bytes;         /* Data byte size of the ping packet    */
    uint32_t ping_response_time_out; /* Wait time for ping response, ms      */
    uint32_t num_pings;              /* Number of times to ping              */
    uint32_t ttl;                    /* Time To Live for the ping packet     */
} liot_ping_config_type_s;

2. Parameters

Type	Parameter	Description
uint32_t	num_data_bytes	Ping packet payload size
uint32_t	ping_response_time_out	Maximum wait time for ping response
uint32_t	num_pings	Maximum number of ping requests
uint32_t	ttl	Ping response packet TTL

3.4 liot_ping_stats_type_s

Status structure during ping request process is as follows

1. Declaration

typedef struct
{
    uint32_t ping_rtt;
    uint32_t ping_size;
    uint32_t ping_ttl;
    char resolved_ip_addr[256];
} liot_ping_stats_type_s;

2. Parameters

Type	Parameter	Description
uint32_t	ping_rtt	Ping response packet RTT
uint32_t	ping_size	Sent ping request byte length
uint32_t	ping_ttl	Ping response packet TTL
char	resolved_ip_addr	Remote server IP address

3.5 liot_ping_summary_type_s

Final result status structure of ping request is as follows

1. Declaration

typedef struct
{
    uint32_t min_rtt;        /* Minimum RTT so far, in millisecs           */
    uint32_t max_rtt;        /* Maximum RTT so far, in millisecs           */
    uint32_t avg_rtt;        /* Average RTT so far, in millisecs           */
    uint32_t num_pkts_sent;  /* Number of pings sent so far          */
    uint32_t num_pkts_recvd; /* Number of responses received so far  */
    uint32_t num_pkts_lost;  /* Number of responses not received     */
} liot_ping_summary_type_s;

2. Parameters

Type	Parameter	Description
uint32_t	min_rtt	Minimum RTT during ping process
uint32_t	max_rtt	Maximum RTT during ping process
unt32_t	avg_rtt	Average RTT during ping process
uint32_t	num_pkts_sent	Number of Ping requests sent
uint32_t	num_pkts_recvd	Number of Ping requests that received response
uint32_t	num_pkts_lost	Number of timed out Ping requests

4 API Function Details

4.1 liot_ping_event_cb

Ping execution callback function

1. Declaration

typedef void (*liot_ping_event_cb)(ping_session_id ping_sess_id, uint16_t event_id, int evt_code, void *evt_param);

2. Parameters

• ping_sess_id: [In] Ping event session ID.

• event_id: [In] Ping event ID, range: liot_ping_event_type.

• evt_code: [In] Ping result code, range: liot_ping_result_code.

• evt_param: [In] Callback parameter.

4.2 liot_ping_start

This function is used to start ping operation.

1. Declaration

ping_session_id liot_ping_start(
    int cid, int sim_id, const char *host, liot_ping_config_type_s *ping_options, liot_ping_event_cb cb_fcn);

2. Parameters

• cid: [In] PDP CID information.

• sim_id: [In] SIM card index, value: 0-1.

• host: [In] Peer address for ping operation.

• ping_options: [In] Ping request data settings, request bytes, timeout, maximum request count, see liot_ping_config_type_s.

• cb_fcn: [In] Event callback function for ping operation, set event type as ping start and handle ping callback results.

3. Return Value

• ping_session_id: Event session ID.

New

5 Code Example

1. Sample code reference: examples/demo/src/demo_ping.c file.

• Running Result:

As shown in the figure above, it indicates that all information has been obtained normally.