Setting up an HTTP Server

In this exercise, we will learn how to set up and run an HTTP server on the nRF70 Series device. Then, we will communicate with the HTTP server by sending HTTP requests from an HTTP client running on a web browser or through a command line interface to control the LEDs on the board.

Exercise steps

In the GitHub repository for this course, go to the base code for this exercise, found in lesson5/wififund_less5_exer3.

1. Enable the necessary DNS configurations.

Enable the following DNS configurations in the prj.conf file

CONFIG_MDNS_RESPONDER=y
CONFIG_DNS_SD=y
CONFIG_MDNS_RESPONDER_DNS_SD=y
CONFIG_NET_HOSTNAME_ENABLE=y
CONFIG_NET_HOSTNAME_UNIQUE=n
CONFIG_NET_HOSTNAME="httpserver"

• CONFIG_MDNS_RESPONDER: Enables the server to respond to local <hostname> inquiries, which we will use in this exercise. This Kconfig symbol requires setting the CONFIG_NET_HOSTNAME symbol to a meaningful value, as seen in the last line of the above code snippet.
• CONFIG_DNS_SD: Enables DNS service discovery, which the server uses to advertise its service on a local network.
• CONFIG_MDNS_RESPONDER_DNS_SD: Enables service discovery via the MDNS responder enabled in the lines above.
• CONFIG_NET_HOSTNAME_ENABLE: Used to enable responding to a hostname.
• CONFIG_NET_HOSTNAME_UNIQUE: Disable the condition of having a unique hostname.

2. Enable Zephyr’s HTTP parser functionality.

HTTP parsing is important for the correct handling and interpreting of HTTP messages.

CONFIG_HTTP_PARSER=y

3. Include Zephyr’s HTTP parser header file.

Add the following line in main.c

#include <zephyr/net/http/parser.h>

4. Define the port number for the server.

Designate port number 8080 to be the port where the HTTP server listens to incoming messages.

#define SERVER_PORT 8080

5. Define a struct to represent the structure of HTTP requests.

Define a struct named http_req to represent the structure of HTTP requests.

struct http_req {
	struct http_parser parser;
	int socket;
	bool received_all;
	enum http_method method;
	const char *url;
	size_t url_len;
	const char *body;
	size_t body_len;
};

6. Define HTTP server response strings.

An HTTP server can respond to HTTP requests in 3 ways:

• 200 OK: This means the server approves the request and will respond by sending the required data.
• 403 Forbidden: This means the server understands the request but does not authorize it.
• 404 Not found: This means the server could not find the resource requested by the client.

In this step, we define strings for standard HTTP server responses. These responses will be printed on the HTTP client’s terminal, and they show the server’s response to the client’s request.

static const char response_200[] = "HTTP/1.1 200 OK\r\n";
static const char response_403[] = "HTTP/1.1 403 Forbidden\r\n\r\n";
static const char response_404[] = "HTTP/1.1 404 Not Found\r\n\r\n";

7. Set up threads for handling multiple incoming TCP connections simultaneously.

To handle multiple incoming TCP connections, each connection will need its own thread, and each thread needs its own stack to store its temporary data.

K_THREAD_STACK_ARRAY_DEFINE(tcp4_handler_stack, MAX_CLIENT_QUEUE, STACK_SIZE);
static struct k_thread tcp4_handler_thread[MAX_CLIENT_QUEUE];
static k_tid_t tcp4_handler_tid[MAX_CLIENT_QUEUE];
K_THREAD_DEFINE(tcp4_thread_id, STACK_SIZE,
		process_tcp4, NULL, NULL, NULL,
		THREAD_PRIORITY, 0, -1);

By using the macro K_THREAD_STACK_ARRAY_DEFINE, we define an array of stacks for handling TCP connections.

tcp4_handler_stack is the name of the array. MAX_CLIENT_QUEUE is the number of threads (and their corresponding stacks) we want to create. STACK_SIZE is the size of each stack.

The struct k_thread is defined by zephyr. We just declare the tcp4_handler_thread array of structs of size MAX_CLIENT_QUEUE. This array of structs will hold each thread’s temporary data of type k_thread.

To manage those threads, we will need to refer to them with their thread IDs. Therefore, we create a similar array of thread IDs of type k_tid_t with a maximum size of MAX_CLIENT_QUEUE.

Lastly, to start a thread, we use the macro K_THREAD_DEFINE to start the thread named tcp4_thread_id.

8. Declare and initialize structs and variables used in network management.

static int tcp4_listen_sock;
static int tcp4_accepted[MAX_CLIENT_QUEUE];

9. Define a function to update the LED state.

Define the function handle_led_update(), that takes in the HTTP request, and the target LED and updates the LED state accordingly.

static bool handle_led_update(struct http_req *request, size_t led_id)
{
	char new_state_tmp[2] = {0};
	uint8_t new_state;
	size_t led_index = led_id - 1;

	if (request->body_len < 1) {
		return false;
	}

	memcpy(new_state_tmp, request->body, 1);

	new_state = atoi(request->body);

	if (new_state <= 1) {
		led_states[led_index] = new_state;
	} else {
		LOG_WRN("The LED%d state was attempted updated to illegal value %d",
			led_id, new_state);
		return false;
	}

	(void)dk_set_led(led_index, led_states[led_index]);
	LOG_INF("LED state updated to %d", led_states[led_index]);

	return true;
}

10. Define a function to handle HTTP requests.

This function receives the HTTP request, checks whether it’s a PUT or GET, processes the requests, and responds accordingly.

static void handle_http_request(struct http_req *request)
{
	size_t len;
	const char *resp_ptr = response_403;
	char dynamic_response_buf[100];
	char url[100];
	size_t url_len = MIN(sizeof(url) - 1, request->url_len);

	memcpy(url, request->url, url_len);

	url[url_len] = '\0';

	if (request->method == HTTP_PUT) {
		size_t led_id;
		int ret = sscanf(url, "/led/%u", &led_id);

		LOG_DBG("PUT %s", url);

		/* Handle PUT requests to the "led" resource. It is safe to use strcmp() because we know that both strings are null-terminated. Otherwise, strncmp would be used. */
		if ((ret == 1) && (led_id > 0) && (led_id < (ARRAY_SIZE(led_states) + 1))) {
			if (handle_led_update(request, led_id)) {
				resp_ptr = response_200;
			}
		} else {
			LOG_INF("Attempt to update unsupported resource '%s'", url);
			resp_ptr = response_403;
		}
	}

	if (request->method == HTTP_GET) {
		size_t led_id;
		int ret = sscanf(url, "/led/%u", &led_id);

		LOG_DBG("GET %s", url);

		/* Handle GET requests to the "led" resource */
		if ((ret == 1) && (led_id > 0) && (led_id < (ARRAY_SIZE(led_states) + 1))) {
			char body[2];
			size_t led_index = led_id - 1;

			(void)snprintk(body, sizeof(body), "%d", led_states[led_index]);

			(void)snprintk(dynamic_response_buf,      sizeof(dynamic_response_buf),
				       "%sContent-Length: %d\r\n\r\n%s",
				       response_200, strlen(body), body);

			resp_ptr = dynamic_response_buf;
		} else {
			LOG_INF("Attempt to fetch unknown resource '%.*s'",
				request->url_len, request->url);

			resp_ptr = response_404;
		}
	}

	/* Get the total length of the HTTP response */
	len = strlen(resp_ptr);

	while (len) {
		ssize_t out_len;

		out_len = send(request->socket, resp_ptr, len, 0);

		if (out_len < 0) {
			LOG_ERR("Error while sending: %d", -errno);
			return;
		}

		resp_ptr = (const char *)resp_ptr + out_len;
		len -= out_len;
	}
}

11. Define and initialize callbacks for the HTTP parser.

11.1 Define the variable parser_settings of type struct http_parser_setting.

static struct http_parser_settings parser_settings;

11.2 Define the callbacks for the HTTP parser

The first five functions in this code snippet are callbacks to be called when different parts of the HTTP message are being parsed. Each function stores information retrieved from the parsed part in its corresponding part of the http_req struct.

The void parser_init() function at the end of the code snippet initializes the HTTP parser settings.

static int on_body(struct http_parser *parser, const char *at, size_t length)
{
	struct http_req *req = CONTAINER_OF(parser, struct http_req, parser);

	req->body = at;
	req->body_len = length;

	LOG_DBG("on_body: %d", parser->method);
	LOG_DBG("> %.*s", length, at);

	return 0;
}

static int on_headers_complete(struct http_parser *parser)
{
	struct http_req *req = CONTAINER_OF(parser, struct http_req, parser);

	req->method = parser->method;

	LOG_DBG("on_headers_complete, method: %s", http_method_str(parser->method));

	return 0;
}

static int on_message_begin(struct http_parser *parser)
{
	struct http_req *req = CONTAINER_OF(parser, struct http_req, parser);

	req->received_all = false;

	LOG_DBG("on_message_begin, method: %d", parser->method);

	return 0;
}

static int on_message_complete(struct http_parser *parser)
{
	struct http_req *req = CONTAINER_OF(parser, struct http_req, parser);

	req->received_all = true;

	LOG_DBG("on_message_complete, method: %d", parser->method);

	return 0;
}

static int on_url(struct http_parser *parser, const char *at, size_t length)
{
	struct http_req *req = CONTAINER_OF(parser, struct http_req, parser);

	req->url = at;
	req->url_len = length;

	LOG_DBG("on_url, method: %d", parser->method);
	LOG_DBG("> %.*s", length, at);

	return 0;
}

11.3 Define parser_init() to initialize the HTTP parser and the callbacks.

static void parser_init(void)
{
	http_parser_settings_init(&parser_settings);

	parser_settings.on_body = on_body;
	parser_settings.on_headers_complete = on_headers_complete;
	parser_settings.on_message_begin = on_message_begin;
	parser_settings.on_message_complete = on_message_complete;
	parser_settings.on_url = on_url;
}

12. Set up the HTTP server.

This function creates a TCP socket, calls bind() to bind the socket to the server address then listens for incoming requests on the socket.

static int setup_server(int *sock, struct sockaddr *bind_addr, socklen_t bind_addrlen)
{
	int ret;

		*sock = socket(bind_addr->sa_family, SOCK_STREAM, IPPROTO_TCP);

	if (*sock < 0) {
		LOG_ERR("Failed to create TCP socket: %d", errno);
		return -errno;
	}

	ret = bind(*sock, bind_addr, bind_addrlen);
	if (ret < 0) {
		LOG_ERR("Failed to bind TCP socket %d", errno);
		return -errno;
	}

	ret = listen(*sock, MAX_CLIENT_QUEUE);
	if (ret < 0) {
		LOG_ERR("Failed to listen on TCP socket %d", errno);
		ret = -errno;
	}

	return ret;
}

13. Set up the TCP client connection handler.

This function is responsible for receiving, processing, and parsing HTTP messages sent over TCP.

static void client_conn_handler(void *ptr1, void *ptr2, void *ptr3)
{
	ARG_UNUSED(ptr1);
	int *sock = ptr2;
	k_tid_t *in_use = ptr3;
	int received;
	int ret;
	char buf[1024];
	size_t offset = 0;
	size_t total_received = 0;
	struct http_req request = {
		.socket = *sock,
	};

	http_parser_init(&request.parser, HTTP_REQUEST);

	while (1) {
		received = recv(request.socket, buf + offset, sizeof(buf) - offset, 0);
		if (received == 0) {
			/* Connection closed */
			LOG_DBG("[%d] Connection closed by peer", request.socket);
			break;
		} else if (received < 0) {
			/* Socket error */
			ret = -errno;
			LOG_ERR("[%d] Connection error %d", request.socket, ret);
			break;
		}

		/* Parse the received data as HTTP request */
		(void)http_parser_execute(&request.parser,
					  &parser_settings, buf + offset, received);

		total_received += received;
		offset += received;

		if (offset >= sizeof(buf)) {
			offset = 0;
		}

		if (request.received_all) {
			handle_http_request(&request);
			break;
		}
	};

	(void)close(request.socket);

	*sock = -1;
	*in_use = NULL;
}

14. Setup functions to handle incoming TCP connections

The process_tcp function accepts incoming TCP connections and creates a new thread to handle that connection.

While the process_tcp4 function calls the setup_server function to initialize the TCP server.

static int process_tcp(int *sock, int *accepted)
{
	static int counter;
	int client;
	int slot;
	struct sockaddr_in6 client_addr;
	socklen_t client_addr_len = sizeof(client_addr);
	char addr_str[INET6_ADDRSTRLEN];

	client = accept(*sock, (struct sockaddr *)&client_addr,
			&client_addr_len);
	if (client < 0) {
		LOG_ERR("Error in accept %d, stopping server", -errno);
		return -errno;
	}

	slot = get_free_slot(accepted);
	if (slot < 0 || slot >= MAX_CLIENT_QUEUE) {
		LOG_ERR("Cannot accept more connections");
		close(client);
		return 0;
	}

	accepted[slot] = client;

	if (client_addr.sin6_family == AF_INET) {
		tcp4_handler_tid[slot] = k_thread_create(
			&tcp4_handler_thread[slot],
			tcp4_handler_stack[slot],
			K_THREAD_STACK_SIZEOF(tcp4_handler_stack[slot]),
			(k_thread_entry_t)client_conn_handler,
			INT_TO_POINTER(slot),
			&accepted[slot],
			&tcp4_handler_tid[slot],
			THREAD_PRIORITY,
			0, K_NO_WAIT);
	}

	net_addr_ntop(client_addr.sin6_family, &client_addr.sin6_addr, addr_str, sizeof(addr_str));

	LOG_INF("[%d] Connection #%d from %s", client, ++counter, addr_str);

	return 0;
}

/* Processing incoming IPv4 clients */
static void process_tcp4(void)
{
	int ret;
	struct sockaddr_in addr4 = {
		.sin_family = AF_INET,
		.sin_port =  htons(SERVER_PORT),
	};

	ret = setup_server(&tcp4_listen_sock, (struct sockaddr *)&addr4, sizeof(addr4));
	if (ret < 0) {
		return;
	}

	LOG_DBG("Waiting for IPv4 HTTP connections on port %d, sock %d", SERVER_PORT, tcp4_listen_sock);


	while (ret == 0) {
		ret = process_tcp(&tcp4_listen_sock, tcp4_accepted);
	}
}

15. Start listening.

15.1 Define the function to listening on the TCP socket

void start_listener(void)
{
	for (size_t i = 0; i < MAX_CLIENT_QUEUE; i++) {
		tcp4_accepted[i] = -1;
		tcp4_listen_sock = -1;

	}
	k_thread_start(tcp4_thread_id);
}

15.2 Call the start_listener() function in main().

start_listener();

16. Build and flash the application to your board.

This exercise uses the PSA backend for storing the Wi-Fi credentials. Therefore, you must build with TF-M.

If necessary, input the commands to connect to Wi-Fi, as we have done in previous exercises.

When you have connected to Wi-Fi, observe the messages printed on the terminal.

*** Booting nRF Connect SDK v2.5.0 ***
[00:00:00.531,127] <inf> net_config: Initializing network
[00:00:00.539,093] <inf> net_config: Waiting interface 1 (0x200011e8) to be up...
uart:~$ OK
OK
wifi connect <SSID> <password>
OK

OK
Connection requested
[00:00:13.927,459] <inf> net_config: Interface 1 (0x200011e8) coming up
[00:00:13.941,101] <inf> net_config: Running dhcpv4 client...
Connected
[00:00:14.011,230] <inf> net_dhcpv4: Received: 192.168.50.191
[00:00:14.019,805] <inf> net_config: IPv4 address: 192.xxx.xxx.xxx
[00:00:14.028,503] <inf> net_config: Lease time: 86400 seconds
[00:00:14.036,956] <inf> net_config: Subnet: 255.255.255.0
[00:00:14.045,013] <inf> net_config: Router: 192.xxx.xxx.xxx
[00:00:14.060,852] <inf> http_server: Network connected
[00:00:14.069,183] <dbg> http_server: process_tcp4: Waiting for IPv4 HTTP connections on port 8080, sock 9

17. Setup an HTTP Client to send messages to the server we created

There are several ways to setup an HTTP client. In this exercise, we will examine three simple ways. Either using, the CLI of httpie, the developer environment of the Mozilla Firefox web browser, or the Postman application.

• httpie CLI
• Mozilla Firefox
• Postman

httpie CLI

1. Download the CLI of httpie

Open up a PowerShell or command prompt terminal in administrator mode

Download Chocolatey from here

Download Python 3 from here

Download the CLI of httpie from here

2. Send an HTTP message

Launch a PowerShell or command prompt terminal

Enter the following command to control LED 1 and set it to On

http PUT httpserver.local:8080/led/1 --raw="1"

3. Observe the server response on your terminal window as we discussed in step 6

4. Send a GET request to inquire about the state of LED 1

Enter the following command

http GET httpserver.local:8080/led/1

C:\WINDOWS\system32>http PUT httpserver.local:8080/led/1 --raw="1"
HTTP/1.1 200 OK




C:\WINDOWS\system32>http GET httpserver.local:8080/led/1
HTTP/1.1 200 OK
Content-Length: 1

1


C:\WINDOWS\system32>

Mozilla Firefox

1. Download Mozilla Firefox

2. Enter this web address http://httpserver:8080/

3. Launch the developer tools panel by pressing Ctrl + Shift + E

4. Click on the Network tab, then the + sign

5. Choose PUT requests, then enter this command http://httpserver:8080/led/1

This command, as seen at the end of the line, controls the resource LED 1

6. Scroll down to the Body tab and enter the value 1 to turn that LED on. Then click send

7. Observe LED 1 on your device turning on

8. Observe the HTTP server response.

9. Now let’s try sending a GET request to inquire about the status of LED 1

Send the same command, but this time as a GET request and without anything in the Body section.

10. On the right-hand side of your Firefox window, navigate to the Response tab, and observe the response body

Postman

Postman is free desktop application, supporting Windows, macOS, and Linux, which allows you test and develop various APIs. In this exercise, we will use it to send HTTP PUT and GET requests and view the response.

1. Download the Postman desktop application from here.

2. Launch the Postman desktop application and create a user account.

3. Select a workspace, then click New, then choose HTTP, as shown below

4. Send your Nordic device a GET message, inquiring about the state of LED 1, by sending the command: http://httpserver:8080/led/1

5. Observe the body of the response being set to 0 as shown in the above picture, indicating that the LED is Off.

6. Send a PUT request to turn LED 1 On, using this command httpserver.local:8080/led/1 in addition to setting the body of the message to 1, as seen in the below illustration.

7. Try setting LED 2 to On by changing the last digit in the previous command to “2”.