Webserver

Webserver Overview

A webserver is a software system that responds to HTTP requests from clients (such as browsers, applications, or devices) and delivers web content such as HTML pages, images, and API responses. Webservers form the backbone of web-based communication and are widely used in applications ranging from embedded systems to cloud services. They are responsible for handling multiple client connections simultaneously, processing requests, and sending back appropriate responses over TCP/IP networks.

RAPIDSEA offers a platform-independent webserver that can run on any system with TCP/IP support. The implementation provides all the core web-server functionalities and is optimized for embedded, desktop, and real-time operating systems.

Some of the salient features of RAPIDSEA Webserver are:

HTTP/1.0 support for GET, POST, PUT, DELETE requests.
Handles multiple simultaneous client connections.
Lightweight and highly optimized for MCUs and resource-constrained systems.
Configurable buffer sizes and connection timeouts.
Platform independent — runs on Linux, Windows, and RTOS-based systems.
Easy integration via callback APIs for custom webpages.

The implementation is fully configurable, supports both blocking and non-blocking operation modes, and can be integrated seamlessly into a variety of embedded and desktop applications.

Webserver

RAPIDSEA implements a lightweight, platform-independent webserver that allows multiple clients to connect and interact with the system through standard HTTP interfaces.

Application Interface

The below table captures the function that are to be called from the application logic.

API Functions
Function	Description
rs_webserver_open	To Initialize the socket configuration.
rs_webserver_run	To set the state to be open
rs_webserver_tcp_comm_handler	To be called to handle the socket connection states.
rs_webserver_process	To be called periodically to receive the request and prepare the client response.

The below table contains the RCB calls invoked by the server stack.

callback Functions
Function	Description
rcb_webserver_file_write	Called to write a specified amount of data to a web server file
rcb_webserver_file_read	Called to read a chunk of data from a web server file
rcb_webserver_file_download_open	Called to initialize the file download process by opening the specified file on the web server
rcb_webserver_file_upload_open	Called to start the process of uploading a file to the web server
rcb_webserver_file_close	Called to close the file session on the web server after completing file operations (upload or download)
rcb_webserver_handle_post_req	Called to validate the input post request data and performs respective action
rcb_webserver_get_file_data	Called to get the buffer and length of the file

Only a millisecond timer is sufficient for the stack to run.

Implementation Guide

This section explains how to implement the Webserver stack using the RAPIDSEA stack, the steps to be followed are

Initially start the webserver task from the application layer.
Then the server task state is in idle condition, until webserver starts.
Webserver starts and changes its state from idle to open.
In webserver process, process the client request and prepare the response for the client.

The below diagram captures the high level sequence of operations associated with the webserver.

Error Code

Every API’s for the webserver returns some success or failure values. Please refer below section,

RAPIDSEA ERROR CODES

Dependency

This stack depends on the below RAPIDSEA interfaces that can be obtained or custom implemented.

Socket Interface

Example demo

An example implementation is available along with the release and is described in Webserver Demo.

Webserver Header Details

Documentation from the relevant server header as follows:

Webserver Module.

This file contains the APIs for using Webserver feature

Author: Embien RAPIDSEA Team
Copyright: Embien Technologies India Pvt. Ltd.

Defines

RS_WEBSERVER_NUM_CONNECTIONS: Maximum concurrent RS_HTTP connections.

RS_WEBSERVER_RX_BUF_SIZE: Receive buffer size.

RS_WEBSERVER_TX_BUF_SIZE: Transmission buffer size.

RS_WEBSERVER_CT_SIZE: Content type size.

RS_BOUNDARY_SIZE: Default boundary field size.

RS_FLASH_SECTOR_SIZE: Flash sector size.

RS_COMMON_MEM_BLOCK_SIZE: Common memory block size.

RS_WEBSERVER_URI_SIZE: Max size of a URI (*URL) string.

RS_TRANSPORT_INTERFACE_ADDR_LEN: Modbus client transport interface(TCP) address length.

RS_WEBSERVER_MAX_NUM_OF_CLIENT: Maximum number of client support.

RS_WEBSERVER_TCP_BUF_MAX_LEN: Maximum buffer length - TCP Mode.

RS_FILE_LOCATION_SD_CARD: File location details.

RS_FILE_LOCATION_INTERNAL_CODE

RS_FILE_LOCATION_INTERNAL_FLASH

RS_MAX_FILE_NAME_SIZE

RS_POST_RESP_CREATE_NEW_COOKIE_WITH_REDIRECT: Post response state macros.

RS_POST_RESP_AUTH_FAILURE

RS_POST_RESP_DELETE_COOKIE_WITH_REDIRECT

RS_POST_RESP_OK

RS_POST_RESP_CLOSE_WITH_NO_CONTENT

RS_POST_RESP_ACCESS_PROT

RS_POST_RESP_OK_WITH_0_CONTENT

RS_POST_RESP_OK_WITH_FW_UPGRADE

RS_JSON_BUFFER_SIZE

RS_WEBSERVER_DEBUG_TX_FRAME: Webserver debug states.

RS_WEBSERVER_DEBUG_RX_FRAME

RS_WEBSERVER_DEBUG_CRC_CHECKS

RS_WEBSERVER_STATE_READY

RS_WEBSERVER_STATE_PROCESS

RS_WEBSERVER_STATE_DATA

RS_WEBSERVER_STATE_COMPLETE

RS_WEBSERVER_STATE_RESET_CONN

RS_WEBSERVER_STATE_CLOSE

RS_WEBSERVER_ACTION_UNKNOWN

RS_WEBSERVER_ACTION_GET

RS_WEBSERVER_ACTION_POST

RS_WEBSERVER_ENCODING_COUNTED

RS_WEBSERVER_ENCODING_CHUNKED

RS_WEBSERVER_ENCODING_UNKNOWN_ENC

RS_FILE_UPLOAD_START

RS_FILE_UPLOAD_INPROGRESS

RS_FILE_UPLOAD_CLOSE

RS_FILE_DOWNLOAD_START

RS_FILE_DOWNLOAD_INPROGRESS

RS_FILE_DOWNLOAD_CLOSE

Typedefs

typedef struct tag_rs_webserver_entry rs_webserver_entry_t: Contains information about webserver data.

typedef struct tag_rs_webserver_config rs_webserver_config_t: Contains information about server configuration.

typedef struct tag_rs_http_socket_info rs_http_socket_info_t: Contains information about webserver socket configuration data.

typedef struct tag_rs_http_file_info rs_http_file_info_t: Contains information about HTTP file information.

typedef struct tag_rs_http_cookie_info rs_http_cookie_info_t: Contains information about webserver cookie.

typedef struct tag_rs_webserver_instance rs_webserver_instance_t: Contains information about server.

typedef struct tag_rs_webserver_http_conn_instance rs_webserver_http_conn_instance_t

typedef struct tag_rs_webserver_http_server_instance rs_webserver_http_server_instance_t: Contains information about TCP server.

Functions

rs_ret_val_t rs_webserver_process(rs_handle_t handle)

Starts Webserver communication once the webserver handle is valid.

This function handles the Webserver process functionality such as state machine etc. Must be called periodically

Parameters:: handle – [in] - Handle to the Webserver
Returns:: Returns zero on success or negative on failure

rs_ret_val_t rs_webserver_run(rs_handle_t handle, uint32_t u32_run)

Starts or Stops the Webserver.

This function starts the Webserver or stop w.r.t the input arguments. Though the instance will be running, It will be in idle state without attempting to incoming requests from clients

Parameters:

handle – [in] - Handle to the Webserver
u32_run – [in] - Start or Stop state requested

Returns:

Returns zero on success or negative on failure

rs_handle_t rs_webserver_open(rs_webserver_instance_t *ptr_instance, rs_webserver_config_t *ptr_config)

Initializes the Webserver Channel for further communication.

This function opens the underlying communication channel and prepares it for further communication with the client

Parameters:

ptr_instance – [in] - Pointer to the Webserver run time data
ptr_config – [in] - Pointer to the Webserver configuration information

Returns:

Handle on success or negative error code

rs_ret_val_t rs_webserver_tcp_comm_handler(rs_handle_t handle)

Perform maintenance TCP communication and client connection process on the Webserver instance.

This function handles the Webserver TCP communication and client connection process functionality such as state machine etc. Must be called periodically

Parameters:: handle – [in] - Handle to the Webserver
Returns:: Zero on success or error code on failure

rs_ret_val_t rcb_webserver_handle_post_req(rs_handle_t handle, int8_t *ptr_uri, int8_t *ptr_rx_data, void **ptr_location, int32_t s32_is_valid_session)

To handle the post request data.

This function validates input post request data and performs respective action.

Parameters:

handle – [in] - Handle to the Webserver
ptr_uri – [in] - URI details
ptr_rx_data – [in] - Received data buffer
ptr_location – [in] - Storage details
s32_is_valid_session – [in] - Session status either valid or not

Returns:

Returns zero on success or negative on failure

rs_ret_val_t rcb_webserver_file_write(rs_handle_t handle, int32_t s32_data_size)

Write data to a web server file.

This function is used to write a specified amount of data to a web server file.

Parameters:

handle – [in] A unique handle for the web server session.
s32_data_size – [in] The size of the data to be written, in bytes.

Returns:

Returns zero on success or a negative value on failure.

rs_ret_val_t rcb_webserver_file_read(rs_handle_t handle)

Read data from a web server file.

This function is used to read a chunk of data from a web server file.

Parameters:: handle – [in] A unique handle for the web server session.
Returns:: Returns zero on success or a negative value on failure.

rs_ret_val_t rcb_webserver_file_download_open(rs_handle_t handle, uint8_t *ptr_file_name)

Open a file for downloading from the web server.

This function initializes the file download process by opening the specified file on the web server.

Parameters:

handle – [in] A unique handle for the web server session.
ptr_file_name – [in] A pointer to the file name that needs to be downloaded.

Returns:

Returns zero on success or a negative value on failure.

rs_ret_val_t rcb_webserver_file_close(rs_handle_t handle)

Close the web server file session.

This function closes the file session on the web server after completing file operations (upload or download).

Parameters:: handle – [in] A unique handle for the web server session.
Returns:: Returns zero on success or a negative value on failure.

rs_ret_val_t rcb_webserver_file_upload_open(rs_handle_t handle)

Initialize the file upload process on the web server.

This function starts the process of uploading a file to the web server.

Parameters:: handle – [in] A unique handle for the web server session.
Returns:: Returns zero on success or a negative value on failure.

struct tag_rs_webserver_entry

#include <rs_webserver.h>

Contains information about webserver data.

Public Members

int8_t *ptr_name: Pointer to file name.

int32_t dummy: Reserved field.

uint8_t *ptr_data: Pointer to file content.

int32_t length: Length of the file content.

struct tag_rs_webserver_config

#include <rs_webserver.h>

Contains information about server configuration.

Public Members

uint8_t addr[RS_TRANSPORT_INTERFACE_ADDR_LEN]: IP Address or serial port name.

uint16_t port: Server Port number for TCP IP.

uint16_t num_conn_accept: Number of connections to accept for TCP.

rs_webserver_entry_t *ptr_ws_entries: Position we’ve kept webserver entries.

int8_t *ptr_http_401_response: Position we’ve write HTTP 401 error response.

int8_t *ptr_http_404_response: Position we’ve write HTTP 404 error response.

int8_t http_rx_buffer[RS_WEBSERVER_RX_BUF_SIZE]: HTTP receive buffer.

uint8_t http_tx_buffer[RS_WEBSERVER_TX_BUF_SIZE]: HTTP transmit buffer.

struct tag_rs_http_socket_info

#include <rs_webserver.h>

Contains information about webserver socket configuration data.

Public Members

uint8_t state

uint8_t action

uint8_t rx_encoding

int32_t close: Close the connection after we’re done?

int32_t content_length: Extracted content length.

int32_t content_received: Content we’ve received on this connection.

int32_t keep_alive_count: No. of files tx’d in single connection.

int32_t data_sent: Number of bytes already sent.

uint8_t *ptr_rx_rd_pos: position we’ve read up to

uint8_t *ptr_srec_start: place holder for the start of an SREC buffer

uint8_t *ptr_srec_end: place holder for the end of an SREC buffer

uint8_t *ptr_rx_buffer: pointer to global RX buffer

uint8_t *ptr_tx_buffer: pointer to global TX buffer

uint8_t flash_device[20]: Flash Device field.

uint8_t content_type[RS_WEBSERVER_CT_SIZE]: Content type for detecting multi-part forms.

uint8_t boundary[RS_BOUNDARY_SIZE]: Boundary between elements of a multi-part form.

uint8_t uri[RS_WEBSERVER_URI_SIZE]: URI buffer.

uint32_t cookie_id: To set an Cookie ID.

uint32_t activity_time: Time of last HTTP activity.

struct tag_rs_http_file_info

#include <rs_webserver.h>

Contains information about HTTP file information.

Public Members

void *file_handle: File handle for file we’re sending.

int32_t file_location: File location details.

int32_t file_length: Length of the current file being sent.

int32_t file_upload_flag: File upload flag.

int32_t file_uploaded_size: Size of an upload file.

uint8_t upload_filename_buff[RS_MAX_FILE_NAME_SIZE]: Filename for an uploaded file.

struct tag_rs_http_cookie_info

#include <rs_webserver.h>

Contains information about webserver cookie.

Public Members

uint32_t cookies_id: Cookie ID.

uint32_t login_time: Login time.

struct tag_rs_webserver_instance

#include <rs_webserver.h>

Contains information about server.

Public Members

rs_webserver_config_t *ptr_config: Pointer to containing server configuration.

rs_handle_t transport_handle: Handle to the Webserver interface (RTU/TCP)

uint32_t data_len: Data length of RX/TX packet.

uint8_t state: Webserver process state.

uint8_t run_state: Webserver run state.

uint8_t reconfigure: Webserver reconfiguration flag.

uint32_t comm_time_out: Webserver timeout for RX/TX.

uint16_t buf_len: Buffer length for RX/TX.

uint8_t *ptr_buff: Pointer to the buffer for RX.

rs_handle_t webserver_handle: Handle to the Webserver interface visible to the user.

struct tag_rs_webserver_http_conn_instance

Public Members

rs_webserver_instance_t server_instance: Common server instance(Information)

uint8_t rx_buff[RS_WEBSERVER_TCP_BUF_MAX_LEN]: TCP data buffer of RX/TX.

uint8_t tx_buff[RS_WEBSERVER_TCP_BUF_MAX_LEN]: TCP data buffer of RX/TX.

uint8_t download_filename_buff[RS_MAX_FILE_NAME_SIZE]: Download filename buffer.

int32_t s32_file_chunk_size

rs_http_socket_info_t http_socket_info: HTTP socket instance(Information)

rs_http_file_info_t http_file_info: HTTP File upload and download information.

rs_http_cookie_info_t cookie_info: Cookie information.

rs_handle_t client_handle: Handle to the Webserver connection instance per client connection.

struct tag_rs_webserver_http_server_instance

#include <rs_webserver.h>

Contains information about TCP server.

Public Members

rs_webserver_instance_t server_instance: Common server instance(Information)

rs_socket_config_t tcp_socket_config: TCP socket configuration.

rs_tcp_server_instance_t tcp_socket_instance: TCP socket instance(Information)

uint32_t num_of_clients: Number of client connection available.

rs_webserver_http_conn_instance_t client_inst[RS_WEBSERVER_MAX_NUM_OF_CLIENT]: TCP connection instance.