1.7.4 Web Socket System Service Developer's Guide

The purpose of this document is to explain the Web Socket system service design to enable the developer to make changes in the service code as per his/ her requirements if the need be.

Overview

The WSS service provides an application programming interface (API) to manage the Web Socket functionalities over TCP/IP Networking. The WSS service uses the MPLAB Harmony NET system service to achieve the TCPIP functionalities.

Key Features:

  • Implements the WSS protocol as a service

  • Supports both Server and Client modes

  • Supports multiple client connections simultaneously in Server mode

Abstraction_new

Detailed Design

WSS system service is a background service with which the application can interact using the APIs provided. The idea of the WSS service is to reduce the code size for the application and simplifying the state machine that the application may need to maintain by abstracting out the complexity of the Web Socket protocol in the system service.

State Machine

The various states of the WSS service are of the enum type SYS_WSS_STATE.

The WSS system service runs a finite state machine with the following states:

  1. SYS_WSS_STATE_CLOSED : Initial State of the WSS service, at the initialization.

  2. SYS_WSS_STATE_CLOSING : An intermediate state which handles the processing of the closing handshake .

  3. SYS_WSS_STATE_CONNECTING : An intermediate state which handles the processing of the opening handshake.

  4. SYS_WSS_STATE_CONNECTED : The state which handles all the data transmissions.

StateMachine

Number of Clients Supported

The maximum number of Clients supported in the server mode by WSS service currently is 8. The user can change the value via the MCC. Default the value is set to 2.

Connection time out

The user can configure a timeout value which will be considered as a maximum idle time for a connection. The default timeout value is 30s.

API Implementation

This section describes the high level implementation details of the WSS APIs.

SYS_WSS_register_callback()

The API is used for registering the application callback function with the WSS service.

SYS_WSS_register_callback_new

SYS_WSS_CloseConnection()

This API is used to close the Web Socket connection to the client indicated by the parameter clientIndex. This will initiate the closing handshake from the server.

SYS_WSS_CloseConnection_new

SYS_WSS_PingClient()

This API is used to send a ping message to the client indicated by the parameter clientIndex.

SYS_WSS_PingClient_new

SYS_WSS_sendMessage()

This API is used to send a message to the client indicated by the parameter clientIndex.

SYS_WSS_sendMessage_new

SYS_WSS_Initialize() / SYS_WSS_Deinitialize()

These functions are used for initializing/ deinitializing the data structures of the WSS system service.

Code location

The base code for the WSS system service can be found in the wireless_system_pic32mzw1_wfi32e01\system\wss

The same shall be copied to the following location after the code for the application is generated – my_application\firmware\src\config\pic32mz_w1_curiosity\system\wss

The core includes two files:

  1. Header file: sys_wss.h

  2. Source file: src/sys_wss.c

The WSS component can also optinoally generate two application template files. The template file includes a callback that can be modified as required by the end user application.

  1. Header file: app_wss.h

  2. Source file: src/app_wss.c