Connections
Connections are essential feature of WiFi device and middleware. It is developed with strong focus on its performance and since it may interact with huge amount of data, it tries to use zero-copy (when available) feature, to decrease processing time.
GSM AT Firmware by default supports up to 5
connections being active at the same time and supports:
Up to
5
TCP connections active at the same timeUp to
5
UDP connections active at the same timeUp to
1
SSL connection active at a time
Note
Client or server connections are available. Same API function call are used to send/receive data or close connection.
Architecture of the connection API is using callback event functions. This allows maximal optimization in terms of responsiveness on different kind of events.
Example below shows bare minimum implementation to:
Start a new connection to remote host
Send HTTP GET request to remote host
Process received data in event and print number of received bytes
1#include "client.h"
2#include "lwgsm/lwgsm.h"
3#include "lwgsm/lwgsm_network_api.h"
4
5/* Host parameter */
6#define CONN_HOST "example.com"
7#define CONN_PORT 80
8
9static lwgsmr_t conn_callback_func(lwgsm_evt_t* evt);
10
11/**
12 * \brief Request data for connection
13 */
14static const
15uint8_t req_data[] = ""
16 "GET / HTTP/1.1\r\n"
17 "Host: " CONN_HOST "\r\n"
18 "Connection: close\r\n"
19 "\r\n";
20
21/**
22 * \brief Start a new connection(s) as client
23 */
24void
25client_connect(void) {
26 lwgsmr_t res;
27
28 /* Attach to GSM network */
29 lwgsm_network_request_attach();
30
31 /* Start a new connection as client in non-blocking mode */
32 if ((res = lwgsm_conn_start(NULL, LWGSM_CONN_TYPE_TCP, "example.com", 80, NULL, conn_callback_func, 0)) == lwgsmOK) {
33 printf("Connection to " CONN_HOST " started...\r\n");
34 } else {
35 printf("Cannot start connection to " CONN_HOST "!\r\n");
36 }
37}
38
39/**
40 * \brief Event callback function for connection-only
41 * \param[in] evt: Event information with data
42 * \return \ref lwgsmOK on success, member of \ref lwgsmr_t otherwise
43 */
44static lwgsmr_t
45conn_callback_func(lwgsm_evt_t* evt) {
46 lwgsm_conn_p conn;
47 lwgsmr_t res;
48 uint8_t conn_num;
49
50 conn = lwgsm_conn_get_from_evt(evt); /* Get connection handle from event */
51 if (conn == NULL) {
52 return lwgsmERR;
53 }
54 conn_num = lwgsm_conn_getnum(conn); /* Get connection number for identification */
55 switch (lwgsm_evt_get_type(evt)) {
56 case LWGSM_EVT_CONN_ACTIVE: { /* Connection just active */
57 printf("Connection %d active!\r\n", (int)conn_num);
58 res = lwgsm_conn_send(conn, req_data, sizeof(req_data) - 1, NULL, 0); /* Start sending data in non-blocking mode */
59 if (res == lwgsmOK) {
60 printf("Sending request data to server...\r\n");
61 } else {
62 printf("Cannot send request data to server. Closing connection manually...\r\n");
63 lwgsm_conn_close(conn, 0); /* Close the connection */
64 }
65 break;
66 }
67 case LWGSM_EVT_CONN_CLOSE: { /* Connection closed */
68 if (lwgsm_evt_conn_close_is_forced(evt)) {
69 printf("Connection %d closed by client!\r\n", (int)conn_num);
70 } else {
71 printf("Connection %d closed by remote side!\r\n", (int)conn_num);
72 }
73 break;
74 }
75 case LWGSM_EVT_CONN_SEND: { /* Data send event */
76 lwgsmr_t res = lwgsm_evt_conn_send_get_result(evt);
77 if (res == lwgsmOK) {
78 printf("Data sent successfully on connection %d...waiting to receive data from remote side...\r\n", (int)conn_num);
79 } else {
80 printf("Error while sending data on connection %d!\r\n", (int)conn_num);
81 }
82 break;
83 }
84 case LWGSM_EVT_CONN_RECV: { /* Data received from remote side */
85 lwgsm_pbuf_p pbuf = lwgsm_evt_conn_recv_get_buff(evt);
86 lwgsm_conn_recved(conn, pbuf); /* Notify stack about received pbuf */
87 printf("Received %d bytes on connection %d..\r\n", (int)lwgsm_pbuf_length(pbuf, 1), (int)conn_num);
88 break;
89 }
90 case LWGSM_EVT_CONN_ERROR: { /* Error connecting to server */
91 const char* host = lwgsm_evt_conn_error_get_host(evt);
92 lwgsm_port_t port = lwgsm_evt_conn_error_get_port(evt);
93 printf("Error connecting to %s:%d\r\n", host, (int)port);
94 break;
95 }
96 default:
97 break;
98 }
99 return lwgsmOK;
100}
Sending data
Receiving data flow is always the same. Whenever new data packet arrives, corresponding event is called to notify application layer.
When it comes to sending data, application may decide between 2
options (*this is valid only for non-UDP connections):
Write data to temporary transmit buffer
Execute send command for every API function call
Temporary transmit buffer
By calling lwgsm_conn_write()
on active connection, temporary buffer is allocated and input data are copied to it.
There is always up to 1
internal buffer active. When it is full (or if input data length is longer than maximal size),
data are immediately send out and are not written to buffer.
GSM AT Firmware allows (current revision) to transmit up to 2048
bytes at a time with single command.
When trying to send more than this, application would need to issue multiple send commands on AT commands level.
Write option is used mostly when application needs to write many different small chunks of data. Temporary buffer hence prevents many send command instructions as it is faster to send single command with big buffer, than many of them with smaller chunks of bytes.
Transmit packet manually
In some cases it is not possible to use temporary buffers,
mostly because of memory constraints.
Application can directly start send data instructions on AT level by using lwgsm_conn_send()
or lwgsm_conn_sendto()
functions.
- group LWGSM_CONN
Connection API functions.
Typedefs
-
typedef struct lwgsm_conn *lwgsm_conn_p
Pointer to lwgsm_conn_t structure.
Enums
Functions
-
lwgsmr_t lwgsm_conn_start(lwgsm_conn_p *conn, lwgsm_conn_type_t type, const char *const host, lwgsm_port_t port, void *const arg, lwgsm_evt_fn conn_evt_fn, const uint32_t blocking)
Start a new connection of specific type.
- Parameters
conn – [out] Pointer to connection handle to set new connection reference in case of successful connection
type – [in] Connection type. This parameter can be a value of lwgsm_conn_type_t enumeration
host – [in] Connection host. In case of IP, write it as string, ex. “192.168.1.1”
port – [in] Connection port
arg – [in] Pointer to user argument passed to connection if successfully connected
conn_evt_fn – [in] Callback function for this connection
blocking – [in] Status whether command should be blocking or not
- Returns
lwgsmOK on success, member of lwgsmr_t enumeration otherwise
-
lwgsmr_t lwgsm_conn_close(lwgsm_conn_p conn, const uint32_t blocking)
Close specific or all connections.
-
lwgsmr_t lwgsm_conn_send(lwgsm_conn_p conn, const void *data, size_t btw, size_t *const bw, const uint32_t blocking)
Send data on already active connection either as client or server.
- Parameters
conn – [in] Connection handle to send data
data – [in] Data to send
btw – [in] Number of bytes to send
bw – [out] Pointer to output variable to save number of sent data when successfully sent. Parameter value might not be accurate if you combine lwgsm_conn_write and lwgsm_conn_send functions
blocking – [in] Status whether command should be blocking or not
- Returns
lwgsmOK on success, member of lwgsmr_t enumeration otherwise
-
lwgsmr_t lwgsm_conn_sendto(lwgsm_conn_p conn, const lwgsm_ip_t *const ip, lwgsm_port_t port, const void *data, size_t btw, size_t *bw, const uint32_t blocking)
Send data on active connection of type UDP to specific remote IP and port.
Note
In case IP and port values are not set, it will behave as normal send function (suitable for TCP too)
- Parameters
conn – [in] Connection handle to send data
ip – [in] Remote IP address for UDP connection
port – [in] Remote port connection
data – [in] Pointer to data to send
btw – [in] Number of bytes to send
bw – [out] Pointer to output variable to save number of sent data when successfully sent
blocking – [in] Status whether command should be blocking or not
- Returns
lwgsmOK on success, member of lwgsmr_t enumeration otherwise
-
lwgsmr_t lwgsm_conn_set_arg(lwgsm_conn_p conn, void *const arg)
Set argument variable for connection.
See also
-
void *lwgsm_conn_get_arg(lwgsm_conn_p conn)
Get user defined connection argument.
See also
- Parameters
conn – [in] Connection handle to get argument
- Returns
User argument
-
uint8_t lwgsm_conn_is_client(lwgsm_conn_p conn)
Check if connection type is client.
- Parameters
conn – [in] Pointer to connection to check for status
- Returns
1
on success,0
otherwise
-
uint8_t lwgsm_conn_is_active(lwgsm_conn_p conn)
Check if connection is active.
- Parameters
conn – [in] Pointer to connection to check for status
- Returns
1
on success,0
otherwise
-
uint8_t lwgsm_conn_is_closed(lwgsm_conn_p conn)
Check if connection is closed.
- Parameters
conn – [in] Pointer to connection to check for status
- Returns
1
on success,0
otherwise
-
int8_t lwgsm_conn_getnum(lwgsm_conn_p conn)
Get the number from connection.
- Parameters
conn – [in] Connection pointer
- Returns
Connection number in case of success or -1 on failure
-
lwgsm_conn_p lwgsm_conn_get_from_evt(lwgsm_evt_t *evt)
Get connection from connection based event.
- Parameters
evt – [in] Event which happened for connection
- Returns
Connection pointer on success,
NULL
otherwise
-
lwgsmr_t lwgsm_conn_write(lwgsm_conn_p conn, const void *data, size_t btw, uint8_t flush, size_t *const mem_available)
Write data to connection buffer and if it is full, send it non-blocking way.
Note
This function may only be called from core (connection callbacks)
- Parameters
conn – [in] Connection to write
data – [in] Data to copy to write buffer
btw – [in] Number of bytes to write
flush – [in] Flush flag. Set to
1
if you want to send data immediately after copyingmem_available – [out] Available memory size available in current write buffer. When the buffer length is reached, current one is sent and a new one is automatically created. If function returns lwgsmOK and
*mem_available = 0
, there was a problem allocating a new buffer for next operation
- Returns
lwgsmOK on success, member of lwgsmr_t enumeration otherwise
-
lwgsmr_t lwgsm_conn_recved(lwgsm_conn_p conn, lwgsm_pbuf_p pbuf)
Notify connection about received data which means connection is ready to accept more data.
Once data reception is confirmed, stack will try to send more data to user.
Note
Since this feature is not supported yet by AT commands, function is only prototype and should be used in connection callback when data are received
Note
Function is not thread safe and may only be called from connection event function
-
size_t lwgsm_conn_get_total_recved_count(lwgsm_conn_p conn)
Get total number of bytes ever received on connection and sent to user.
- Parameters
conn – [in] Connection handle
- Returns
Count of received bytes on connection
-
uint8_t lwgsm_conn_get_remote_ip(lwgsm_conn_p conn, lwgsm_ip_t *ip)
Get connection remote IP address.
- Parameters
conn – [in] Connection handle
ip – [out] Pointer to IP output handle
- Returns
1
on success,0
otherwise
-
lwgsm_port_t lwgsm_conn_get_remote_port(lwgsm_conn_p conn)
Get connection remote port number.
- Parameters
conn – [in] Connection handle
- Returns
Port number on success,
0
otherwise
-
lwgsm_port_t lwgsm_conn_get_local_port(lwgsm_conn_p conn)
Get connection local port number.
- Parameters
conn – [in] Connection handle
- Returns
Port number on success,
0
otherwise
-
typedef struct lwgsm_conn *lwgsm_conn_p