CMSIS-Driver  Version 2.8.0
Peripheral Interface for Middleware and Application Code
 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
WiFi Control

Control functions for the WiFi module. More...

Content

 WiFi Events
 The WiFi driver generates call back events that are notified via the function ARM_WIFI_SignalEvent.
 

Data Structures

struct  ARM_WIFI_CAPABILITIES
 WiFi Driver Capabilities. More...
 

Typedefs

typedef void(* ARM_WIFI_SignalEvent_t )(uint32_t event, void *arg)
 Pointer to ARM_WIFI_SignalEvent : Signal WiFi Event. More...
 

Functions

ARM_DRIVER_VERSION ARM_WIFI_GetVersion (void)
 Get driver version. More...
 
ARM_WIFI_CAPABILITIES ARM_WIFI_GetCapabilities (void)
 Get driver capabilities. More...
 
int32_t ARM_WIFI_Initialize (ARM_WIFI_SignalEvent_t cb_event)
 Initialize WiFi Module. More...
 
int32_t ARM_WIFI_Uninitialize (void)
 De-initialize WiFi Module. More...
 
int32_t ARM_WIFI_PowerControl (ARM_POWER_STATE state)
 Control WiFi Module Power. More...
 
int32_t ARM_WIFI_GetModuleInfo (char *module_info, uint32_t max_len)
 Get Module information. More...
 
void ARM_WIFI_SignalEvent (uint32_t event, void *arg)
 Signal WiFi Events. More...
 

Description

Control functions for the WiFi module.

The WiFi Control functions setup and control the WiFi module.


Data Structure Documentation

struct ARM_WIFI_CAPABILITIES

WiFi Driver Capabilities.

A WiFi driver can be implemented with different capabilities. The data fields of this structure encode the capabilities implemented by this driver.

Returned by:

Data Fields
uint32_t station: 1 Station.
uint32_t ap: 1 Access Point.
uint32_t station_ap: 1 Concurrent Station and Access Point.
uint32_t wps_station: 1 WiFi Protected Setup (WPS) for Station.
uint32_t wps_ap: 1 WiFi Protected Setup (WPS) for Access Point.
uint32_t event_ap_connect: 1 Access Point: event generated on Station connect.
uint32_t event_ap_disconnect: 1 Access Point: event generated on Station disconnect.
uint32_t event_eth_rx_frame: 1 Event generated on Ethernet frame reception in bypass mode.
uint32_t bypass_mode: 1 Bypass or pass-through mode (Ethernet interface)
uint32_t ip: 1 IP (UDP/TCP) (Socket interface)
uint32_t ip6: 1 IPv6 (Socket interface)
uint32_t ping: 1 Ping (ICMP)
uint32_t reserved: 20 Reserved (must be zero)

Typedef Documentation

ARM_WIFI_SignalEvent_t

Pointer to ARM_WIFI_SignalEvent : Signal WiFi Event.

Provides the typedef for the callback function ARM_WIFI_SignalEvent.

Parameter for:

Function Documentation

ARM_DRIVER_VERSION ARM_WIFI_GetVersion ( void  )

Get driver version.

Returns
ARM_DRIVER_VERSION

The function ARM_WIFI_GetVersion returns version information of the driver implementation in ARM_DRIVER_VERSION.

API version is the version of the CMSIS-Driver specification used to implement this driver. Driver version is source code version of the actual driver implementation.

Example:

extern ARM_DRIVER_WIFI Driver_WiFi0;
static ARM_DRIVER_WIFI *wifi;
void get_wifi_version (void) {
wifi= &Driver_WiFi0;
version = wifi->GetVersion ();
if (version.api < 0x100U) { // requires at minimum API version 1.0 or higher
// error handling
return;
}
}
ARM_WIFI_CAPABILITIES ARM_WIFI_GetCapabilities ( void  )

Get driver capabilities.

Returns
ARM_WIFI_CAPABILITIES

The function ARM_WIFI_GetCapabilities retrieves information about capabilities in this driver implementation. The data fields of the struct ARM_WIFI_CAPABILITIES encode various capabilities, for example if a WiFi module supports the Access Point mode or the bypass mode, or is capable to signal events using the ARM_WIFI_SignalEvent callback function.

Example:

extern ARM_DRIVER_WIFI Driver_WiFi0;
static ARM_DRIVER_WIFI *wifi;
void get_wifi_capabilities (void) {
ARM_WIFI_CAPABILITIES capabilities;
wifi = &Driver_WiFi0;
capabilities = wifi->GetCapabilities ();
// interrogate capabilities
:
}
int32_t ARM_WIFI_Initialize ( ARM_WIFI_SignalEvent_t  cb_event)

Initialize WiFi Module.

Parameters
[in]cb_eventPointer to ARM_WIFI_SignalEvent_t
Returns
execution status

The function ARM_WIFI_Initialize initializes the WiFi module.

It is called when the middleware component starts operation.

The ARM_WIFI_Initialize function performs the following operations:

  • Initializes the resources and peripherals required for the WiFi module.
  • Registers the ARM_WIFI_SignalEvent callback function.

The parameter cb_event is a pointer to the ARM_WIFI_SignalEvent callback function; use a NULL pointer when no callback signals are required.

Example:

extern ARM_DRIVER_WIFI Driver_WiFi0;
static ARM_DRIVER_WIFI *wifi;
static ARM_ETH_MAC_ADDR own_mac_address;
void initialize_wifi (void) {
wifi = &Driver_WiFi0;
// Initialize and Power-on WiFi Module
wifi->Initialize (NULL);
// Populate own_mac_address with the address to use
wifi->SetOption(ARM_WIFI_MAC, &own_mac_address, 6U);
}
int32_t ARM_WIFI_Uninitialize ( void  )

De-initialize WiFi Module.

Returns
execution status

The function ARM_WIFI_Uninitialize de-initializes the resources of the WiFi module.

It is called when the middleware component stops operation and releases the software resources used by the module.

Example:

extern ARM_DRIVER_WIFI Driver_WiFi0;
static ARM_DRIVER_WIFI *wifi;
void uninitialize_wifi (void) {
wifi = &Driver_WiFi0;
// Power off and De-initialize WiFi Module
wifi->Uninitialize ();
}
int32_t ARM_WIFI_PowerControl ( ARM_POWER_STATE  state)

Control WiFi Module Power.

Parameters
[in]statePower state
Returns
execution status

The function ARM_WIFI_PowerControl allows you to configure the power modes of the WiFi module.

The parameter state specifies the ARM_POWER_STATE.

Low-power mode depends on additional options set by ARM_WIFI_SetOption :

  • Deep-sleep mode is entered when ARM_WIFI_LP_TIMER option is set to a value different than 0
  • Sleep mode is entered otherwise

Deep-sleep mode (only for station): Module turns off the radio and also internal CPU thus reducing power consumption to minimum, only the timer is running that wakes-up the module after specified time. When timer expires the module reconnects to the access point.

This mode is used when power consumption is a priority (battery powered devices) and when WiFi is used in short intervals that do not occur very often (example: sending a temperature from a sensor to a cloud every 10 seconds).

Sleep mode (only for station): Module reduces power consumption by going into sleep and waking up periodically to listen for beacons.

Delivery Traffic Indication Message (DTIM) interval can be configured with option ARM_WIFI_DTIM (station and access point) and beacon interval with option ARM_WIFI_BEACON (only for access point).

Default module intervals are used when those options are not explicitly set.

If power state specifies an unsupported mode, the function returns ARM_DRIVER_ERROR_UNSUPPORTED as status information and the previous power state of the peripheral is unchanged. Multiple calls with the same state generate no error.

Example:

int32_t ARM_WIFI_GetModuleInfo ( char *  module_info,
uint32_t  max_len 
)

Get Module information.

Parameters
[out]module_infoPointer to character buffer were info string will be returned
[in]max_lenMaximum length of string to return (including null terminator)
Returns
execution status

The function ARM_WIFI_GetModuleInfo retrieves string containing information about the WiFi module.

The information might include module name, firmware version, ...

Note
Module must be initialized and powered before module information can be retrieved.

Example:

extern ARM_DRIVER_WIFI Driver_WiFi0;
static ARM_DRIVER_WIFI *wifi;
void initialize_wifi (void) {
char info[32];
wifi = &Driver_WiFi0;
// Initialize and Power-on WiFi Module
wifi->Initialize (NULL);
// Retrieve module information
wifi->GetModuleInfo(&info, sizeof(info));
}
void ARM_WIFI_SignalEvent ( uint32_t  event,
void *  arg 
)

Signal WiFi Events.

Parameters
[in]eventWiFi Events notification mask
[in]argPointer to argument of signaled event
Returns
none

The function ARM_WIFI_SignalEvent is a callback function registered by the function ARM_WIFI_Initialize. It is called by the WiFi driver to notify the application about WiFi Events occurred during operation.

The parameter event indicates the event that occurred during driver operation.

The parameter arg provides additional information about the event.

The following events can be generated:

Parameter event Description
ARM_WIFI_EVENT_AP_CONNECT Occurs in access point mode when a station has connected to the access point.
ARM_WIFI_EVENT_AP_DISCONNECT Occurs in access point mode when a station has disconnected from the access point.
ARM_WIFI_EVENT_ETH_RX_FRAME Occurs in WiFi Bypass Mode when an ethernet frame is received.