Feedback

Socket API

The nRF Connect SDK uses Zephyr’s BSD Sockets API as its socket API, which is enabled through the Kconfig CONFIG_NET_SOCKETS.

The structure of the socket is determined by the API used for the networking architecture. Internet sockets are commonly based on the Berkeley sockets API, also known as BSD sockets.

Enabling the configuration CONFIG_POSIX_API, exposes all functions without the zsock_ prefix. This Kconfig is selected by default when the WPA supplicant enabled (CONFIG_WIFI_NM_WPA_SUPPLICANT=y).

Note

Notice that most of the signatures contain “See POSIX.1-2017 article for normative description.” This is the standard that the socket API adheres to, and more information about the API can also be found here.

Creating a socket

When creating a socket, you need to specify the socket family, the socket type, and the socket protocol.

You can create a socket using the API function socket(), which has the following signature:

Let’s briefly explain the three parameters passed to the socket() function.

Socket family: Specifies an address family in which addresses specified in later socket operations should be interpreted. AF_INET for IPv4 and AF_INET6 for IPv6.
Socket type: Specifies the semantics of communication. SOCK_STREAM is used for TCP connections and SOCK_DGRAM is used for UDP connections.
Socket protocol: Specifies the transport protocol to be used with the socket. IPPROTO_TCP for TCP connections and IPPROTO_UDP for UDP connections.

The following code snippet creates a datagram socket in the IPv4 family that uses UDP.

static int sock;
sock = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);

Copy

static int sock;
sock = socket(AF_INET, SOCK_DGRAM, IPPROTO_UDP);

If the function is completed successfully, it will return a non-negative integer which will be stored in the socket file descriptor int sock. This is to be used in other socket operations to refer to that socket.

Setting socket options

To set socket options, use the API function setsockopt(), which has the following signature

This function is used, for instance, when configuring TLS and DTLS for a socket, which we will see in Lesson 4 and 5.

Get socket address

To connect a socket, you need the socket address of the peer you want the socket to connect to.

You can obtain the address using the function getaddrinfo(), which has the following signature

Hostname (nodename): either a domain name, such as “google.com”, an address string, such as “81.24.249.2072”, or NULL
Service (servname): either a port number passed as a string, such as “80”, a service name, such as “echo”., or NULL.
Hints: hints concerning the desired return information, either the structure addrinfo with the type of service requested, or NULL
Result (res): pointer to a structure addrinfo containing the information requested

Zero or one of the arguments hostname and servname may be NULL.

getaddrinfo() can return multiple results in the form of a linked list in which struct addrinfo res is the first element in the list and the member struct addrinfo * ai_next points to the next element in the list of results.

The following code snippet resolves the address of example.com.

#define SERVER_HOSTNAME "example.com"
#define SERVER_PORT "80"

struct addrinfo *result;
struct addrinfo hints = {
	.ai_family = AF_INET,
	.ai_socktype = SOCK_STREAM
};

getaddrinfo(SERVER_HOSTNAME, SERVER_PORT, &hints, &result);

Copy

#define SERVER_HOSTNAME "example.com"
#define SERVER_PORT "80"

struct addrinfo *result;
struct addrinfo hints = {
	.ai_family = AF_INET,
	.ai_socktype = SOCK_STREAM
};

getaddrinfo(SERVER_HOSTNAME, SERVER_PORT, &hints, &result);

Note

Since the domain example.com supports multiple services (IPv4 and IPv6), we pass the hints parameter specifying the socket family to ensure we get the correct socket address.

After we have called getaddrinfo(), we need to get the relevant information from result and assign it to a variable of type sockaddr_in, the sockaddr structure to use for IPv4 addresses.

First, we define the variable server of type struct sockaddr_storage and then the pointer server4 of type struct sockaddr_in which points to the contents of server.

The reason for using struct sockaddr_storage instead of just struct sockaddr is that it supports protocol-family independence and is the recommended practice.

struct sockaddr_storage server;
struct sockaddr_in * server4 = ((struct sockaddr_in *)&server);

server4->sin_addr.s_addr = ((struct sockaddr_in *)result->ai_addr)->sin_addr.s_addr;
server4->sin_family = AF_INET;
server4->sin_port = ((struct sockaddr_in *)result->ai_addr)->sin_port;

Copy

struct sockaddr_storage server;
struct sockaddr_in * server4 = ((struct sockaddr_in *)&server);

server4->sin_addr.s_addr = ((struct sockaddr_in *)result->ai_addr)->sin_addr.s_addr;
server4->sin_family = AF_INET;
server4->sin_port = ((struct sockaddr_in *)result->ai_addr)->sin_port;

Address: We cast sockaddr * ai_addr, in result to a pointer of type sockaddr_in and retrieve the address.
Family: We know the socket family is IPv4, because that’s what we passed as a hint to getaddrinfo().
Port: We again cast sockaddr * ai_addr, in result, to a pointer of type sockaddr_in and retrieve the port.

Connecting

To connect a socket, use the API function connect(), which has the following signature

Notice that this function takes the address information as struct sockaddr. This is a generic socket address structure, used in most of the socket function calls with addresses, to support both IPv4 and IPv6.

When calling this function, you need to cast the address information you have (usually struct sockaddr_in for IPv4 or struct sockaddr_in6 for IPv6) to the generic struct sockaddr. Then pass the length of the address struct, in our case sizeof(struct sockaddr_in).

Note

Since UDP is a connection-less protocol, connect() doesn’t actually connect a UDP socket, it just tells the socket which address to send to. You can also use sendto() to specify the destination address when sending instead of calling connect(), see below.

The function below connects the socket with the file descriptor sock to the server with the information found in sockaddr_storage server from the previous step. For the last parameter addrlen we pass the size of the sockaddr_in structure.

connect(sock, (struct sockaddr *)&server, sizeof(struct sockaddr_in));

Copy

connect(sock, (struct sockaddr *)&server, sizeof(struct sockaddr_in));

Binding

On the server side of things, after creating the socket descriptor using socket(), we must bind the socket to a local network address for it to be accessible from the network. bind() has the following signature

Listening

Once bound to a specific IP and port, we want to listen for incoming connection requests on that socket, using listen() which has the following signature

To accept a client connection request on a listening socket, use accept(), which has the following signature

Sending

You can send a message on a connected socket using send(), which has the following signature

char message[1024] = {"Hello\0"};
send(sock, message, sizeof(message), 0);

Copy

char message[1024] = {"Hello\0"};
send(sock, message, sizeof(message), 0);

When using datagram sockets with UDP, you can also use sendto(), instead of calling connect() and then send().

char message[1024] = {"Hello\0"};
sendto(sock, message, sizeof(message), (struct sockaddr *)&server, sizeof(struct sockaddr_in));

Copy

char message[1024] = {"Hello\0"};
sendto(sock, message, sizeof(message), (struct sockaddr *)&server, sizeof(struct sockaddr_in));

Receiving

You can receive a message on a connected socket using recv(), which has the following signature

static uint8_t recv_buf[MESSAGE_SIZE];
recv(sock, recv_buf, sizeof(recv_buf), 0);

Copy

static uint8_t recv_buf[MESSAGE_SIZE];
recv(sock, recv_buf, sizeof(recv_buf), 0);

Polling

If you have multiple sockets you want to listen to simultaneously, you can use poll() to poll multiple sockets for events, then call recv() only when there is data to be read.

The function poll(), which has the following signature

This function takes an array of struct pollfd, one for each socket to monitor, the number of elements in the array and a timeout in milliseconds. struct pollfd has the following signature

Set the field fd to the socket file descriptor you want to poll (recall the return value from socket(), int sock), and the field events to a bitmask OR’ing the event flags you want to monitor. In the events field, the two most common event flags are POLLIN and POLLOUT (see below). The last field, revents, is filled by poll(), and is also a bitmask of event flags. The three most common are listed below.

POLLIN – there is data to be read from the socket
POLLOUT – data can be written to the socket
(revents only) POLLERR – an error has occurred
(revents only) POLLHUP – the device has been disconnected
(revents only) POLLNVAL – invalid fd member

Calling poll() will block until an event specified in events occurs on any of the monitored sockets, or the function times out, based on the timeout parameter.

Note that poll() will set the POLLHUP, POLLERR, and POLLNVAL flag in revents if the condition is true, even if the corresponding bit is not set in the events fields.

The following code snippet polls the socket sock for the event POLLIN with timeout -1, meaning it will block until the event occurs or the call is interrupted.

static struct pollfd fds;
fds.fd = sock;
fds.events = POLLIN;

int err = poll(&fds, ARRAYSIZE(fds), -1);
if (err < 0) {
	LOG_ERR("poll: %d", errno);
	break;
}

Copy

static struct pollfd fds;
fds.fd = sock;
fds.events = POLLIN;

int err = poll(&fds, ARRAYSIZE(fds), -1);
if (err < 0) {
	LOG_ERR("poll: %d", errno);
	break;
}

Successful completion is indicated by a non-negative return value, in which case we can examine the revents field for error flags. Lastly, check that POLLIN flag is set, i.e that the function didn’t just return due to timing out, and then call recv() to read the data.

if ((fds.revents & POLLERR) == POLLERR) {
	LOG_ERR("POLLERR");
	break;
}

if ((fds.revents & POLLNVAL) == POLLNVAL) {
	LOG_ERR("POLLNVAL");
	break;
}

if ((fds.revents & POLLHUP) == POLLHUP) {
	LOG_ERR("POLLHUP");
	break;
}

if ((fds.revents & POLLIN) == POLLIN) {
	err = recv(sock, recv_buf, sizeof(recv_buf), 0);
}

Copy

if ((fds.revents & POLLERR) == POLLERR) {
	LOG_ERR("POLLERR");
	break;
}

if ((fds.revents & POLLNVAL) == POLLNVAL) {
	LOG_ERR("POLLNVAL");
	break;
}

if ((fds.revents & POLLHUP) == POLLHUP) {
	LOG_ERR("POLLHUP");
	break;
}

if ((fds.revents & POLLIN) == POLLIN) {
	err = recv(sock, recv_buf, sizeof(recv_buf), 0);
}

Closing

You can close a socket using close(), which has the following signature

Closing a socket shuts down the socket associated with the socket descriptor and frees the resources allocated to the socket. It’s always good practice to close a socket at the end of an application, or if an error occurs.

close(sock);

Copy

close(sock);

Errors

If a function call from the socket API fails, most of them will not actually return the error but rather return -1 and then set the global variable errno to the relevant error.

These errno‘s get converted to errno‘s that adhere to the selected C library implementation:

(default) Libc minimal: errors found here: <install_path>\zephyr\lib\libc\minimal\include\errno.h
Newlib (CONFIG_NEWLIB_LIBC): errors found here

Nordic Developer Academy Terms of Service

1. Introduction

‍These terms and conditions (“Terms of Use”) apply to the use of the Nordic Developer Academy, provided by Nordic Semiconductor ASA, org. nr. 966 011 726, a public limited liability company registered in Norway (“Nordic Semiconductor”). ‍

Nordic Developer Academy allows the user to take technical courses related to Nordic Semiconductor products, software and services, and obtain a certificate certifying completion of these courses. By completing the registration process for the Nordic Developer Academy, you are agreeing to be bound by these Terms of Use.

These Terms of Use are applicable as long as you have a user account giving you access to Nordic Developer Academy.‍

‍2. Access to and use of Nordic Developer Academy

‍‍Upon acceptance of these Terms of Use you are granted a non-exclusive right of access to, and use of Nordic Developer Academy, as it is provided to you at any time. Nordic Semiconductor provides Nordic Developer Academy to you free of charge, subject to the provisions of these Terms of Use and the Nordic Developer Academy Privacy Policy.

To access select features of Nordic Developer Academy, you need to create a user account. You are solely responsible for the security associated with your user account, including always keeping your login details safe.

You will able to receive an electronic certificate from Nordic Developer Academy upon completion of courses. By issuing you such a certificate, Nordic Semiconductor certifies that you have completed the applicable course, but does not provide any further warrants or endorsements for any particular skills or professional qualifications.

Nordic Semiconductor will continuously develop Nordic Developer Academy with new features and functionality, but reserves the right to remove or alter any existing functions without notice.

‍3. Acceptable use

You undertake that you will use Nordic Developer Academy in accordance with applicable law and regulations, and in accordance with these Terms of Use.‍ You must not modify, adapt, or hack Nordic Developer Academy or modify another website so as to falsely imply that it is associated with Nordic Developer Academy, Nordic Semiconductor, or any other Nordic Semiconductor product, software or service.

You agree not to reproduce, duplicate, copy, sell, resell or in any other way exploit any portion of Nordic Developer Academy, use of Nordic Developer Academy, or access to Nordic Developer Academy without the express written permission by Nordic Semiconductor. You must not upload, post, host, or transmit unsolicited email, SMS, or \”spam\” messages.

You are responsible for ensuring that the information you post and the content you share does not;

contain false, misleading or otherwise erroneous information
infringe someone else’s copyrights or other intellectual property rights
contain sensitive personal data or
contain information that might be received as offensive or insulting.
Such information may be removed without prior notice.

‍Nordic Semiconductor reserves the right to at any time determine whether a use of Nordic Developer Academy is in violation of its requirements for acceptable use.

Violation of the at any time applicable requirements for acceptable use may result in termination of your account. We will take reasonable steps to notify you and state the reason for termination in such cases.

‍4. Routines for planned maintenance

‍Certain types of maintenance may imply a stop or reduction in availability of Nordic Developer Academy. Nordic Semiconductor does not warrant any level of service availability but will provide its best effort to limit the impact of any planned maintenance on the availability of Nordic Developer Academy.

5. Intellectual property rights

‍Nordic Semiconductor retains all rights to all elements of Nordic Developer Academy. This includes, but is not limited to, the concept, design, trademarks, know-how, trade secrets, copyrights and all other intellectual property rights.

Nordic Semiconductor receives all rights to all content uploaded or created in Nordic Developer Academy. You do not receive any license or usage rights to Nordic Developer Academy beyond what is explicitly stated in this Agreement.

‍6. Liability and damages

‍Nothing within these Terms of Use is intended to limit your statutory data privacy rights as a data subject, as described in the Nordic Developer Academy Privacy Policy. ‍You acknowledge that errors might occur from time to time and waive any right to claim for compensation as a result of errors in Nordic Developer Academy. When an error occurs, you shall notify Nordic Semiconductor of the error and provide a description of the error situation.

You agree to indemnify Nordic Semiconductor for any loss, including indirect loss, arising out of or in connection with your use of Nordic Developer Academy or violations of these Terms of Use. ‍Nordic Semiconductor shall not be held liable for, and does not warrant that (i) Nordic Developer Academy will meet your specific requirements, (ii) Nordic Developer Academy will be uninterrupted, timely, secure, or error-free, (iii) the results that may be obtained from the use of Nordic Developer Academy will be accurate or reliable, (iv) the quality of any products, services, information, or other material purchased or obtained by you through Nordic Developer Academy will meet your expectations, or that (v) any errors in Nordic Developer Academy will be corrected.

You accept that this is a service provided to you without any payment and hence you accept that Nordic Semiconductor will not be held responsible, or liable, for any breaches of these Terms of Use or any loss connected to your use of Nordic Developer Academy. Unless otherwise follows from mandatory law, Nordic Semiconductor will not accept any such responsibility or liability.

‍7. Change of terms

‍Nordic Semiconductor may update and change the Terms of Use from time to time. Nordic Semiconductor will seek to notify you about significant changes before such changes come into force and give you a possibility to evaluate the effects of proposed changes. Continued use of Nordic Developer Academy after any such changes shall constitute your acceptance of such changes. You can review the current version of the Terms of Use at any time at https://academy.nordicsemi.com/terms-of-service/

‍8. Transfer of rights

‍Nordic Semiconductor is entitled to transfer its rights and obligation pursuant to these Terms of Use to a third party as part of a merger or acquisition process, or as a result of other organizational changes.

‍9. Third Party Services

‍‍To the extent Nordic Developer Academy facilitates access to services provided by a third party, you agree to comply with the terms governing such third party services. Nordic Semiconductor shall not be held liable for any errors, omissions, inaccuracies, etc. related to such third party services.

‍10. Dispute resolution

‍‍The Terms of Use and any other legally binding agreement between yourself and Nordic Semiconductor shall be subject to Norwegian law and Norwegian courts’ exclusive jurisdiction.

Wi-Fi Fundamentals

Socket API

Note

Creating a socket

Setting socket options

Get socket address

Note

Connecting

Note

Binding

Listening

Sending

Receiving

Polling

Closing

Errors

Switch language?

Change summary

What's new in the latest version

Wi-Fi

MCUboot & Partition Manager