WebSocket Library

July 21, 2026 · View on GitHub

1. Introduction

The WebSocket Library is a comprehensive, enterprise-grade implementation designed specifically for ModusToolbox applications, providing robust WebSocket communication capabilities for Infineon embedded systems. This library enables developers to implement RFC 6455 compliant WebSocket clients and servers with full-duplex, real-time communication support across a wide range of Infineon microcontroller platforms.

Built with reliability and performance in mind, the library offers thread-safe operations, advanced connection management, and sophisticated event-driven architecture. It seamlessly integrates with ModusToolbox ecosystem components including FreeRTOS, Microsoft ThreadX, lwIP networking stack, NetXSecure stack, and mbedTLS security framework to deliver production-ready WebSocket functionality for IoT, industrial automation, and connected device applications.

2. Features

  • Dual-Role Architecture: Complete client and server implementations with role-specific optimizations
  • Enterprise Security: Full TLS/SSL support with certificate-based authentication and secure connection establishment
  • Multi-RTOS Support: Compatible with both FreeRTOS and Microsoft ThreadX real-time operating systems
  • Flexible Network Stacks: Support for lwIP and NetXSecure networking implementations
  • Scalable Server Design: Multi-client concurrent connection handling with configurable resource management
  • Real-Time Communication: Low-latency bidirectional messaging with automatic fragmentation and reassembly
  • Production-Ready Reliability: Comprehensive error handling, connection recovery, and resource cleanup
  • Event-Driven Programming Model: Asynchronous notification system for responsive application development

3. Architecture and Design Principles

  • Modular Design : The WebSocket Library uses a modular design that is easy to maintain, scale, and reuse. The design follows good software practices like separating different concerns and using clean interfaces.

  • Complete Feature Set: The WebSocket Library provides a full implementation of the RFC 6455 WebSocket protocol with all the features needed for both client and server applications.

  • Event-Based System: The library uses an event notification system that tells your application what's happening.

3.1 Client-Only Events:

  • MTB_WEBSOCKET_EVENT_CONNECTED - Connection successfully established to external server
  • MTB_WEBSOCKET_EVENT_CLOSE - Connection gracefully closed by either client or server

3.2 Server-Only Events:

  • MTB_WEBSOCKET_EVENT_SERVER_STARTED - Server successfully started and actively listening for connections
  • MTB_WEBSOCKET_EVENT_CLIENT_ACCEPTED - Server accepted new client connection after successful handshake
  • MTB_WEBSOCKET_EVENT_BROADCAST_COMPLETE - Mass broadcasting operation completed to all or selected clients
  • MTB_WEBSOCKET_EVENT_CLIENT_DISCONNECTED - Existing client disconnected from server
  • MTB_WEBSOCKET_EVENT_SERVER_STOPPED - Server stopped listening for new connections

3.3 Common Events (Client and Server):

  • MTB_WEBSOCKET_EVENT_MESSAGE - Data received from server/clients containing text or binary payload
  • MTB_WEBSOCKET_EVENT_PING - Ping control frame received requiring pong response
  • MTB_WEBSOCKET_EVENT_PONG - Pong control frame received in response to sent ping
  • MTB_WEBSOCKET_EVENT_ERROR - Critical error occurred during WebSocket operation
  • MTB_WEBSOCKET_EVENT_STATE_CHANGE - WebSocket connection state transitioned between operational phases

4. Core Configuration Parameters

Configure these parameters by defining them in your application's Makefile or by copying and modifying the configuration file (see step 7 in Quick Start Guide).

Instance Limits:

  • MTB_MAX_NUM_OF_WEBSOCKET_CLIENTS - Maximum number of client instances
  • MTB_WEBSOCKET_MAX_CLIENTS_PER_SERVER - Maximum connections per server instance

WebSocket Protocol Configuration:

  • MTB_WEBSOCKET_MAX_FRAME_SIZE - Maximum WebSocket frame size for security and memory management
  • MTB_WEBSOCKET_MAX_CHUNK_SIZE - Maximum frame chunk size during reception

Timeout Configuration:

  • MTB_WEBSOCKET_MESSAGE_SEND_TIMEOUT_MS - WebSocket message send timeout
  • MTB_WEBSOCKET_MESSAGE_RECEIVE_TIMEOUT_MS - WebSocket message receive timeout for partial data

Event System Configuration:

  • MTB_WEBSOCKET_EVENT_QUEUE_SIZE - Event queue size for WebSocket events
  • MTB_WEBSOCKET_EVENT_THREAD_PRIORITY - Event processing thread priority

Threading Configuration:

  • MTB_WEBSOCKET_EVENT_THREAD_STACK_SIZE - Event processing thread stack size

5. Supported Hardware Platforms

The WebSocket Library is optimized and validated for the following Infineon evaluation and development platforms, providing comprehensive support for advanced wireless connectivity and edge computing applications:

6. Dependencies

The WebSocket Library uses the WSLAY library, a publicly available WebSocket protocol implementation that provides RFC 6455 compliant frame parsing and message handling. The library integrates with ModusToolbox and supports multiple RTOS and networking stack combinations.

7. Quick Start Guide

This comprehensive guide provides step-by-step instructions for integrating the WebSocket Library into your ModusToolbox project and configuring it for optimal performance with your chosen RTOS and networking stack.

  1. To use websocket library with Wi-Fi kits on FreeRTOS, lwIP, and Mbed TLS combination, the application should pull websocket library and wifi-core-freertos-lwip-mbedtls library which will internally pull secure-sockets, wifi-connection-manager, FreeRTOS, lwIP, Mbed TLS and other dependent modules. To pull wifi-core-freertos-lwip-mbedtls and websocket libraries create the following .mtb files in deps folder.

  2. To use websocket library with CYW955913EVK-01 kit, the application should pull websocket library and wifi-core-threadx-cat5 library which will internally pull secure-sockets, wifi-connection-manager and other dependent modules. To pull wifi-core-threadx-cat5 and websocket libraries create the following .mtb files in deps folder.

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

  • The configuration files are bundled with the wifi-mw-core library for FreeRTOS, lwIP, and Mbed TLS. See README.md for details.
  • If the application is using bundle library then the configuration files are in the bundle library. For example if the application is using Wi-Fi core freertos lwip mbedtls bundle library, the configuration files are in wifi-core-freertos-lwip-mbedtls/configs folder. Note: Configuration file changes are not required for CYW955913EVK-01.

  1. Define the following COMPONENTS in the application's Makefile for FreeRTOS based platforms.

    COMPONENTS=FREERTOS MBEDTLS LWIP SECURE_SOCKETS

  2. Define the following COMPONENTS in the application's Makefile for ThreadX based platforms.

    COMPONENTS=SECURE_SOCKETS

  3. By default, the websocket Library disables all the debug log messages. To enable log messages, the application must perform the following:

    1. Add the ENABLE_WEBSOCKET_LOGS macro to the DEFINES in the code example's Makefile. The Makefile entry would look like as follows:

      DEFINES+=ENABLE_WEBSOCKET_LOGS

    2. Call the cy_log_init() function provided by the cy-log module. cy-log is part of the connectivity-utilities library.

      See connectivity-utilities library API documentation for cy-log details.

  4. The WebSocket library provides a configuration file to customize behavior and performance parameters:

    • Copy the configuration file from the library to your project:
    cp mtb_shared/websocket/configs/mtb_websocket_config.h ./
    • Adjust configuration parameters as needed for your application:
    // mtb_websocket_config.h - Key configuration options
#define MTB_MAX_NUM_OF_WEBSOCKET_CLIENTS          2
#define MTB_WEBSOCKET_MAX_CLIENTS_PER_SERVER      5
#define MTB_WEBSOCKET_EVENT_QUEUE_SIZE            50
#define MTB_WEBSOCKET_MAX_FRAME_SIZE              65536
#define MTB_WEBSOCKET_MAX_CHUNK_SIZE              8192
#define MTB_WEBSOCKET_MESSAGE_SEND_TIMEOUT_MS     1000
#define MTB_WEBSOCKET_MESSAGE_RECEIVE_TIMEOUT_MS  500

  5. The application utilizing the WebSocket library, which leverages the secure-sockets library for socket operations and runs on the CM55 core of the PSoC™ Edge E84 kits, requires 64KB of non-cacheable memory per TLS connection. By default, the secure-sockets supports a single TLS connection. To enable support for multiple TLS connections, the following modifications are necessary:

    • To support TLS connections, a minimum of 64KB of non-cacheable memory is required per connection. To enable support for multiple TLS connections, it is necessary to define the CYCFG_MBEDTLS_BUFFER_SIZE macro in the Makefile. Specifically, the macro should be set to a value that is a multiple of 64KB, where the multiplier corresponds to the desired number of concurrent TLS connections. For instance, to support five TLS connections, the macro should be defined with a value of 320KB (5 x 64KB). The corresponding Makefile entry would be:
    DEFINES+=CYCFG_MBEDTLS_BUFFER_SIZE=320*1024

9. Additional information