SOCKET Development Guide_Rev1.1

中文

Revision History

Version	Date	Author	Reviewer	Revision Content
Rev1.0	2026-01-23	zw	zlc	Initial document creation
Rev1.1	2026-03-27	zw	zlc	Optimized document content

1 Overview

This document introduces the LTE-EC71X SOCKET2 interface APIs. The usage flow can refer to the following flowchart.

The above process is the Socket communication flow based on cellular network Cat1 module, mainly including initialization, network registration, data call, Socket connection establishment, data transmission and exception handling. The specific process is as follows:

1. SOCKET task startup: Program starts executing Socket communication task.

2. Network registration:

   • Check whether successfully registered to cellular network.

   • If registration fails, loop waiting or retry until registration succeeds.

3. Data Call:

   • After successful network registration, initiate data call to establish PS domain data connection.

   • If dial-up fails, stop and release resources, process ends; if successful, continue to next step.

4. Initialize Socket information: Prepare parameters required for Socket communication (such as server address, port, etc.).

5. Create Socket and connect to server: Call Liot_SocketOpen to create Socket and try to connect to server. Connection result is notified asynchronously through callback function.

6. Callback event handling: Handle according to different callback events:

   • LIOT_SOCKET_CONNECT_SUCCESS: Connection successful, enter data send/receive phase.

   • LIOT_SOCKET_RECV_DATA: Receive data from server, perform business processing.

   • LIOT_SOCKET_DNS_FAIL: Domain name resolution failed, trigger exception handling.

   • LIOT_SOCKET_CONNECT_FAIL: Failed to connect to server, trigger exception handling.

   • LIOT_SOCKET_DISCONNECT: Connection disconnected, trigger exception handling.

7. Data send/receive:

   • After successful connection, can send data to server through Liot_SocketSend interface.

   • When receiving data, handle in LIOT_SOCKET_RECV_DATA event.

8. Exception error handling: When exceptions such as DNS failure, connection failure or disconnection occur, enter exception handling process, stop data call, release resources, and end task.

9. Normal termination: When communication completes or exits abnormally, call liot_stop_data_call interface to stop data call, release related resources, process ends.

The entire process adopts asynchronous callback mechanism to ensure that network registration, data call and Socket connection execute in sequence, and has exception recovery capability.

2 API Function Overview

Function	Description
Liot_SocketOpen()	Create Socket connection and connect to server
Liot_SocketSend()	Send socket data
Liot_SocketGetStatus()	Get current status of socket
Liot_SocketClose()	Close socket

3 Type Descriptions

3.1 Liot_SocketEvent_e

1. Enumeration definition:

   typedef enum
   {
       LIOT_SOCKET_CONNECT_SUCCESS = 0,
       LIOT_SOCKET_DNS_FAIL = 1,
       LIOT_SOCKET_CONNECT_FAIL = 2,
       LIOT_SOCKET_RECV_DATA = 3,
       LIOT_SOCKET_DISCONNECT = 4,
   }Liot_SocketEvent_e;
   

2. Enumeration description

Variable	Description
LIOT_SOCKET_CONNECT_SUCCESS	Connect to server successfully event
LIOT_SOCKET_DNS_FAIL	DNS resolution failed event
LIOT_SOCKET_CONNECT_FAIL	Connect to server failed event
LIOT_SOCKET_RECV_DATA	Receive data event
LIOT_SOCKET_DISCONNECT	Disconnect from server event

3.2 Liot_Socket_Type_e

1. Enumeration definition:

   typedef enum
   {
       LIOT_SOCKET_TYPE_TCP = 0,
       LIOT_SOCKET_TYPE_UDP = 1,
   }Liot_Socket_Type_e;
   

2. Enumeration description

Variable	Description
LIOT_SOCKET_TYPE_TCP	Socket connection type is TCP
LIOT_SOCKET_TYPE_UDP	Socket connection type is UDP

3.3 Liot_SocketInfo_t

1. Structure definition:

   typedef struct
   {
       int socket_fd;          // socket fd 0-7
       uint8_t cid;            // cid 0-7
       uint8_t socket_type;    //TCP UDP
       uint8_t host[256];      //host name domain or IP
       uint16_t port;          //port number
       uint16_t local_port;    //local port
       int32_t keepidle;       //heartbeat detection interval
       int32_t keepinterval;   //heartbeat detection interval
       int32_t keepcount;      //heartbeat detection count
   }Liot_SocketInfo_t;
   

2. Structure variable description

Variable	Description
socket_fd	Socket file descriptor. Output parameter, valid after socket creation succeeds
cid	cid 0-7. Network dial-up channel number, usually default use CID 1. Input parameter
socket_type	TCP: LIOT_SOCKET_TYPE_TCP UDP: LIOT_SOCKET_TYPE_UDP Input parameter
host	host name domain or IP. Input parameter
port	Server port number. Input parameter
local_port	Local port number. Input parameter
keepidle	How long after connection idle to start probing. Unit: seconds. Range: between 1 and 0x7FFFFFFF (2,147,483,647) seconds, 0 is default value 7200 seconds (2 hours). Input parameter
keepinterval	Time interval between heartbeat probe packets. Unit: seconds. Input parameter
keepcount	Maximum heartbeat probe count. Input parameter

4 API Function Details

4.1 Liot_SocketOpen

Create Socket connection and connect to server.

1. Declaration

int32_t Liot_SocketOpen(Liot_SocketInfo_t *info, liot_socket_callback callback, void *userdata);

2. Parameters

info:

[In] Parameters used for creating socket, see structure Liot_SocketInfo_t.

callback:

[In] Socket event callback function. Callback function declaration is as follows:

typedef void (*liot_socket_callback)(Liot_SocketEvent_e event, int socket_fd, uint8_t *data, uint32_t data_len, void *user_data);

userdata:

[In] User data.

3. Return Value

0: Success.

<0: Failure.

4.2 Liot_SocketSend

Send socket data.

1. Declaration

int32_t Liot_SocketSend(int32_t fd, uint8_t *data, uint16_t len);

2. Parameters

fd:

[In] Socket file descriptor obtained through [Liot_SocketOpen].

data:

[In] Socket data to send.

len:

[In] Length of data to send.

3. Return Value

0: Success, returns number of bytes sent.

<0: Failure, returns negative value.

4.3 Liot_SocketGetStatus

Get current status of socket.

1. Declaration

int32_t Liot_SocketGetStatus(int32_t fd);

2. Parameters

fd:

[In] Socket file descriptor obtained through [Liot_SocketOpen].

3. Return Value

0: Socket is connected.

<0: Returns error code.

4.4 Liot_SocketClose

Close socket.

1. Declaration

int32_t Liot_SocketClose(int32_t fd);

2. Parameters

fd:

[In] Socket file descriptor obtained through [Liot_SocketOpen].

3. Return Value

0: Close successful.

<0: Failure, returns error code.