Wireless Manager API Implementation

Owned by Former user (Deleted)
Last updated: Dec 10, 2020 by WES Admin

µC/TCP-IP supports only wireless devices which include an integrated wireless supplicant (i.e., the client-side software that performs scan and login requests). This kind of hardware requires you to send management commands to the device to accomplish some operation such as scan, join, set MAC address, etc. Some of these management commands may take a while to be completed. For those commands most of the wireless devices return the command result via a management frame which must be received like a packet. So, the Wireless Manager must provide mechanisms to send management commands, and then return once the management command is completed.

The Wireless Manager API should be implemented as follows:

Listing - Wireless Manager
const  NET_WIFI_MGR_API  NetWiFiMgr_API_Generic = {
                                                   &NetWiFiMgr_Init,            (1)
                                                   &NetWiFiMgr_Start,           (2)
                                                   &NetWiFiMgr_Stop,            (3)
                                                   &NetWiFiMgr_AP_Scan,         (4)
                                                   &NetWiFiMgr_AP_Join,         (5)
                                                   &NetWiFiMgr_AP_Leave,        (6)
                                                   &NetWiFiMgr_IO_Ctrl,         (7)
                                                   &NetWiFiMgr_Mgmt,            (8)
                                                   &NetWiFiMgr_Signal           (9)
                                                  };

(1) Wireless Manager initialization function pointer

(2) Wireless Manager start function pointer

(3) Wireless Manager stop function pointer

(4) Wireless Manager access point scan pointer

(5) Wireless Manager access point join pointer

(6) Wireless Manager access point leave pointer

(7) Wireless Manager IO control pointer

(8) Wireless Manager device driver management pointer

(9) Wireless Manager signal response signal pointer

μC/TCP-IP provides code that is compatible with most wireless devices that embed the wireless supplicant. However, extended functionality must be implemented on a per wireless device basis. If additional functionality is required, it may be necessary to create an application specific Wireless Manager.

Note: It is the Wireless Manager developers’ responsibility to ensure that all of the functions listed within the API are properly implemented and that the order of the functions within the API structure is correct.

The sections that follow describe the interactions between the device driver and the Wireless Manager layer provided with µC/TCP-IP.

Figure - Interactions between the device driver and the Wireless Manager layer

(1) All management functionality present in the Wireless Manager API uses a simple state machine context to be set and updated by the device driver. The state machine context contains some fields used by the state machine to know what should be done after the call. Essentially, the state machine is implemented in NetWiFiMgr_MgmtHadler() which calls NetDev_MgmtExecuteCmd() to start and execute the management command. Following the state machine context, the state machine can wait to receive the response and then calls NetDev_MgmtProcessResp() to analyze the response data and rearrange the data.

(2) NetDev_MgmtExecuteCmd() can execute a management command directly if it doesn’t require receiving a response or it can just initialize the management command when a response is needed to complete the command. The function lets the state machine know what should be done next by setting the state machine context that is passed as a pointer argument to the function.

(3) If no response is needed to complete the command then the NetWiFiMgr_MgmtHandler() returns immediately. If the management command requires a response to complete the command then it returns only if the timeout has expired (i.e. the response not received) or if the Wireless Manager has been signalled and the response is analyzed and translated.

(4) When the response of the management command is received NetDev_MgmtProcessResp() is called to analyze and to translate the data for upper layers. Also this function must update the state machine context to let know if the management command is completed or if more data must be sent to complete the current management command.

(5) The device driver can also use the Wireless Manager to send management commands defined within the driver during start and stop of the interface especially when a response is needed to complete the management command such as updating the wireless device firmware. Note that it’s not possible to use the Wireless Manager during initialization since receiving packets and managing frames cannot be done before the initialization is completed.

(6) When data ready ISR occurs and the interface is signalled, the function NetIF_RxPkt() calls the driver to read the data from the wireless device regardless if it's a management frame or a data packet.

(7) NetDev_Rx() must determine if the data received is a management frame or a packet and must set at least the frame type within the offset of the network buffer. See Receiving Packets and Management Frames. If the data read is a management frame it’s not a response and the processing must be done in NetDev_DemuxMgmt() to let the stack increment its statistics.

(8) Once the data is read and the frame type set by the device driver then the buffer is passed to the wireless interface layer to be processed.

(9) NetIF_WiFi_Rx() uses the frame type within the buffer offset and set previously by the device driver to know which layer to call and pass the network buffer.

(10) If the data received is a packet then the 802x layer is called to process the packet as it’s should done for an Ethernet packet.

(11) If the data received is a management frame then 8 is called to determine what to do with the data. If it’s a response for a management command initialized previously then the Wireless Manager must be signalled. If it’s information about the wireless device state, then some operation on the stack could be done such as updating the link state of the interface. Note that the buffer offset section could be used by the device driver to help determine what kind of data is contained in the data section of the buffer.

(12) When the data is a management response previously initialized then the Wireless Manager must be signalled by using the Wireless Manager API.