Overview

The HTTP Server library provides an HTTP/HTTPS web server for Infineon platforms, enabling an application to serve web pages and handle RESTful client requests over Wi-Fi or Ethernet using secured (TLS) and non-secured connections.

It supports the RESTful GET, PUT, and POST methods, static and dynamically generated resources, multiple content types (HTML, plain text, and JSON), chunked transfer encoding, and Server-Sent Events (SSE) for pushing updates to connected HTTP clients.

Current release: v3.4.0 (see RELEASE.md and version.xml).

Features

RESTful HTTP methods — GET, PUT, and POST for client communication with the server
HTTP/1.1 protocol with secured (TLS) and non-secured modes of connection
Wi-Fi and Ethernet connectivity using the secure-sockets library and the RTOS abstraction layer
Flexible resource handling for static and dynamic resources and multiple content types (HTML, plain text, JSON)
Large payloads and chunked encoding — handles content larger than the MTU using the Content-Length header (for CY_RAW_DYNAMIC_URL_CONTENT and CY_DYNAMIC_URL_CONTENT) and supports chunked encoding for GET and POST
Server-Sent Events (SSE) — server push technology that lets an HTTP client receive automatic updates over the HTTP connection

Note: For a POST request, chunked encoding is supported only for data smaller than a single MTU; Content-Length headers are recommended for larger data.

When to Use

Use this library when your application needs to act as an HTTP/HTTPS web server on Infineon hardware, including:

Serving device status or configuration web pages over Wi-Fi or Ethernet
Handling RESTful GET/PUT/POST requests from browsers or HTTP clients
Secured (TLS) web server communication with certificate-based authentication
Pushing real-time updates to connected clients using Server-Sent Events (SSE)

Prerequisites

Hardware Requirements

This library runs on Infineon Wi-Fi- and Ethernet-capable device families:

PSOC™ 6 with CYW4343W / CYW43012 / CYW43439 connectivity
XMC7200 with CYW43xxx connectivity
CYW943907 / CYW954907 standalone Wi-Fi SoCs
CYW955913 single-chip Wi-Fi + Bluetooth®
PSOC™ Edge E84

Both Wi-Fi and Ethernet transports are supported (Ethernet on the PSOC™ 6 and XMC7200 device families). The set of validated kits grows over time; see RELEASE.md for the specific kits validated in each release.

Supported Software and Tools

The current version of the library was validated for compatibility with the following Software and Tools:

Software and Tools	Version
ModusToolbox™ Software Environment	3.9
ModusToolbox™ Device Configurator	5.90
GCC Compiler	14.2.1
IAR Compiler (only for ModusToolbox™)	9.50.2
Arm Compiler 6	6.22
LLVM compiler	22.1.0

Read Documentation First

HTTP Server Reference Manual - Full API reference
secure-sockets - Provides the secure socket layer used by the server
connectivity-utilities - Provides the cy-log logging module

Choose Starting Template

Create an Empty application and then add the required libraries for your target platform.

Add Required Libraries

The required libraries depend on your connection type. Add them using the ModusToolbox™ Library Manager (available in the ModusToolbox™ for VS Code extension and the Eclipse IDE), or by creating the corresponding .mtb files in the application's deps folder and running make getlibs.

For Wi-Fi kits on FreeRTOS, lwIP, and Mbed TLS — add http-server and wifi-core-freertos-lwip-mbedtls (which pulls in secure-sockets, wifi-connection-manager, FreeRTOS, lwIP, Mbed TLS, and other dependent modules):

# deps/wifi-core-freertos-lwip-mbedtls.mtb
https://github.com/Infineon/wifi-core-freertos-lwip-mbedtls#latest-v4.X#$$ASSET_REPO$$/wifi-core-freertos-lwip-mbedtls/latest-v4.X
 
# deps/http-server.mtb
https://github.com/Infineon/http-server#latest-v3.X#$$ASSET_REPO$$/http-server/latest-v3.X

Note: TLS version 1.3 is supported on wifi-core-freertos-lwip-mbedtls library from latest-v2.X and above (supported on all platforms except the PSOC™ 64S0S2 Wi-Fi Bluetooth® pioneer kit (CY8CKIT-064S0S2-4343W)).

For CYW955913 (single-chip Wi-Fi + Bluetooth®) kits — add http-server and wifi-core-threadx-cat5:

# deps/wifi-core-threadx-cat5.mtb
https://github.com/Infineon/wifi-core-threadx-cat5#latest-v1.X#$$ASSET_REPO$$/wifi-core-threadx-cat5/latest-v1.X
 
# deps/http-server.mtb
https://github.com/Infineon/http-server#latest-v2.X#$$ASSET_REPO$$/http-server/latest-v2.X

For Ethernet kits on FreeRTOS, lwIP, and Mbed TLS — add http-server and ethernet-core-freertos-lwip-mbedtls:

# deps/ethernet-core-freertos-lwip-mbedtls.mtb
https://github.com/Infineon/ethernet-core-freertos-lwip-mbedtls#latest-v1.X#$$ASSET_REPO$$/ethernet-core-freertos-lwip-mbedtls/latest-v1.X
 
# deps/http-server.mtb
https://github.com/Infineon/http-server#latest-v2.X#$$ASSET_REPO$$/http-server/latest-v2.X

Note: To use TLS version 1.3 on Ethernet, upgrade ethernet-core-freertos-lwip-mbedtls to latest-v2.X.

After adding the libraries in the Library Manager (or creating the .mtb files), run make getlibs to fetch them.

Review and make the required changes to the pre-defined configuration files:

The configuration files are bundled with the network-core bundle library. For example, if the application uses the Wi-Fi core FreeRTOS lwIP Mbed TLS bundle library, the configuration files are in the wifi-core-freertos-lwip-mbedtls/configs folder. Similarly, for the Ethernet core FreeRTOS lwIP Mbed TLS library, the configuration files are in the ethernet-core-freertos-lwip-mbedtls/configs folder. See the "Quick Start" section in the wifi-core-freertos-lwip-mbedtls README for details.

Configure Makefile (if applicable)

Define the required components in the application's Makefile.

Standard components for Wi-Fi or Ethernet FreeRTOS applications:

COMPONENTS=FREERTOS MBEDTLS LWIP SECURE_SOCKETS

For CYW955913EVK-01:

COMPONENTS=SECURE_SOCKETS

See Configuration Reference for the full list of build defines (log enablement, maximum resources, MTU size, and socket receive timeout).

Add Headers

Add the following header in your application source:

#include "cy_http_server.h"

Quick Start

This quick start demonstrates a non-secured HTTP server that serves a static resource. Follow these steps to get from an Empty application to a working example:

Create an Empty application.
Add the required libraries for your platform profile using the Library Manager (or .mtb files in deps/), then run make getlibs.
Update the application Makefile with the required COMPONENTS and any DEFINES (see Configuration Reference).
Add #include "cy_http_server.h" and implement the network-init, create, register-resource, and start sequence.
Build, program the board, connect to the server IP from a browser, and observe the served page.

See Sample Code for a complete pattern.

Sample Code

This section provides a complete, runnable example. It demonstrates HTTP server network initialization, handle creation, static resource registration, and server start with proper error handling.

Applicable runtime environments:

FreeRTOS — supported on all Wi-Fi and Ethernet kits. Full example is shown below.
ThreadX — supported on the CYW955913EVK-01 kit using the wifi-core-threadx-cat5 library. Use the same API sequence shown in the FreeRTOS example; only the RTOS task-creation code differs.
Bare Metal — not applicable. This library requires an RTOS because it uses task, mutex, and queue primitives for the internal HTTP server thread.
Zephyr — not supported by this library. Use FreeRTOS or ThreadX on Infineon platforms.

FreeRTOS Example (main.c + task)

/* Complete example: non-secure HTTP server serving a static resource */
#include <stdio.h>
#include <string.h>
#include "cy_http_server.h"
 
#define HTTP_PORT           (80)
#define MAX_SOCKETS         (2)
 
/* HTML page served in response to the client */
#define HTTP_PAGE_CONTENT \
  "<html><head></head><body>Hello, this is a reference HTTP server application</body></html>"
 
static cy_http_server_t        http_server;
static cy_network_interface_t  nw_interface;
static cy_socket_sockaddr_t    ip_address;
 
void http_server_task(void *arg)
{
  (void)arg;
  cy_rslt_t result;
  cy_resource_static_data_t static_resource;
 
  /* Step 1: Populate the server IP address (the interface must already be up,
   * for example after a successful Wi-Fi or Ethernet connection). */
  ip_address.ip_address.ip.v4  = /* server IPv4 address */ 0;
  ip_address.ip_address.version = CY_SOCKET_IP_VER_V4;
 
  nw_interface.object = (void *)&ip_address;
  nw_interface.type   = CY_NW_INF_TYPE_WIFI;
 
  /* Step 2: Initialize the HTTP server network */
  result = cy_http_server_network_init();
  if (result != CY_RSLT_SUCCESS) { printf("Network init failed!\n"); return; }
 
  /* Step 3: Create a non-secure HTTP server handle (pass security info for HTTPS) */
  result = cy_http_server_create(&nw_interface, HTTP_PORT, MAX_SOCKETS, NULL, &http_server);
  if (result != CY_RSLT_SUCCESS) { printf("HTTP server create failed!\n"); return; }
 
  /* Step 4: Register a static resource */
  static_resource.data   = HTTP_PAGE_CONTENT;
  static_resource.length = sizeof(HTTP_PAGE_CONTENT);
  result = cy_http_server_register_resource(http_server, (uint8_t *)"/",
              (uint8_t *)"text/html", CY_STATIC_URL_CONTENT, &static_resource);
  if (result != CY_RSLT_SUCCESS) { printf("Resource registration failed!\n"); }
 
  /* Step 5: Start the HTTP server */
  result = cy_http_server_start(http_server);
  if (result != CY_RSLT_SUCCESS) { printf("HTTP server start failed!\n"); return; }
  printf("HTTP server started on port %d.\n", HTTP_PORT);
 
  /* The server now serves requests. Keep the task alive. */
  for (;;)
  {
    cy_rtos_delay_milliseconds(1000);
  }
 
  /* Cleanup (reached only on shutdown) */
  cy_http_server_stop(http_server);
  cy_http_server_delete(http_server);
  cy_http_server_network_deinit();
}

For a secured (HTTPS) server, pass a populated cy_https_server_security_info_t (server certificate, private key, and optional Root CA) to cy_http_server_create() and use port 443.

Expected Outcome

When the Quick Start flow is configured correctly, you should observe:

Visual/Hardware Behavior:

The board brings up network connectivity and starts the HTTP server on the configured port.
A browser or HTTP client connecting to the server IP receives the registered page.
GET, PUT, and POST requests are served according to the registered resources.

Terminal Output:

HTTP server started on port 80.

Performance Metrics:

The maximum number of simultaneous client connections is bounded by the max_connection argument to cy_http_server_create() and, on memory-constrained devices, by available RAM (especially for secured connections).
The maximum number of registered resources is controlled by MAX_NUMBER_OF_HTTP_SERVER_RESOURCES.
The socket receive responsiveness is controlled by HTTP_SERVER_SOCKET_RECEIVE_TIMEOUT (default 10 ms).

Troubleshooting

Server restart fails with a bind error: If the HTTP server is stopped while clients (such as some browsers) are still connected, a TCP wait time of approximately 2-3 minutes must elapse before the server can be restarted; otherwise the socket bind can fail. To recover, wait for the TCP wait time to expire, then call cy_http_server_start() again on the same handle (or recreate the handle with cy_http_server_create()).
Incomplete data on PUT/POST larger than the MTU: lwIP may deliver Netconn receive events with a data length greater than HTTP_SERVER_MTU_SIZE (1460 bytes by default), so the server may not receive the complete client data. Increase the value with DEFINES+=HTTP_SERVER_MTU_SIZE=2812 (or another suitable size) in the application Makefile.
Limited simultaneous secure connections: On memory-constrained devices (such as CY8CKIT-062-WIFI-BT), the maximum number of simultaneous secure connections may be limited by available memory.
IAR 9.40.2 build errors: If the application explicitly includes iar_dlmalloc.h, add --advanced_heap to LDFLAGS in the application Makefile.
No debug logs: Logs are disabled by default. Add DEFINES+=ENABLE_HTTP_SERVER_LOGS and call cy_log_init() from the cy-log module (part of connectivity-utilities) to enable them.

Related Code Examples

ModusToolbox™ HTTP server code examples - Includes the Wi-Fi web server and HTTPS server examples for the supported platforms

Configuration Reference

This section documents the build-time configuration macros for the library. Add them to the DEFINES in the application's Makefile.

Build Defines

Define	Default	Description
`ENABLE_HTTP_SERVER_LOGS`	Disabled	Enables debug log messages from the HTTP Server library. Requires calling `cy_log_init()` from the cy-log module (part of connectivity-utilities).
`MAX_NUMBER_OF_HTTP_SERVER_RESOURCES`	Library default	Maximum number of HTTP server resources that can be registered.
`HTTP_SERVER_SOCKET_RECEIVE_TIMEOUT`	10	Socket receive timeout in milliseconds.
`HTTP_SERVER_MTU_SIZE`	1460	HTTP server MTU size in bytes. Increase it if PUT/POST payloads larger than the MTU are truncated.

COMPONENT Flags

Component	Description
`FREERTOS`	Required for FreeRTOS-based Wi-Fi/Ethernet applications.
`MBEDTLS`	Required for TLS support via Mbed TLS.
`LWIP`	Required for the lwIP network stack.
`SECURE_SOCKETS`	Required for all platforms. The only COMPONENT needed for CYW955913EVK-01.

Resource Content Types

The content type passed to cy_http_server_register_resource() is one of the following cy_url_resource_type values:

Content type	Description
`CY_STATIC_URL_CONTENT`	Page is constant data in a memory-addressable area.
`CY_DYNAMIC_URL_CONTENT`	Page is dynamically generated by a URL processor function.
`CY_RAW_STATIC_URL_CONTENT`	Same as `CY_STATIC_URL_CONTENT`, but the HTTP header is supplied as part of the content.
`CY_RAW_DYNAMIC_URL_CONTENT`	Same as `CY_DYNAMIC_URL_CONTENT`, but the HTTP header is supplied as part of the content.

Note: CY_RESOURCE_URL_CONTENT and CY_RAW_RESOURCE_URL_CONTENT are defined but currently not supported.

API Call Sequence

Use the following API call sequence to start an HTTP server, serve resources, and shut it down:

+-------------------------------------+
|   cy_http_server_network_init()     |
+-------------------------------------+
                  |
                  v
+-------------------------------------+
|      cy_http_server_create()        |
+-------------------------------------+
                  |
                  v
+-------------------------------------+
| cy_http_server_register_resource()  |
+-------------------------------------+
                  |
                  v
+-------------------------------------+
|       cy_http_server_start()        |
+-------------------------------------+
                  |
                  v
+-------------------------------------+
|        cy_http_server_stop()        |
+-------------------------------------+
                  |
                  v
+-------------------------------------+
|       cy_http_server_delete()       |
+-------------------------------------+
                  |
                  v
+-------------------------------------+
|  cy_http_server_network_deinit()    |
+-------------------------------------+

Industry Standards and Compliance

Communication Standards:

HTTP/1.1

Release Notes and Changelog

RELEASE.md - Detailed release notes for all versions

License

This library is provided under Infineon software license terms. It builds on the secure-sockets library and, through the selected network-core bundle (wifi-core-freertos-lwip-mbedtls, ethernet-core-freertos-lwip-mbedtls, or wifi-core-threadx-cat5), pulls in third-party components such as FreeRTOS, lwIP, and Mbed TLS, which are governed by their respective license terms. You are responsible for reviewing and accepting all applicable third-party license terms.

LICENSE