CMSIS-Driver: WiFi Control

| CMSIS-Driver Version 2.7.1 Peripheral Interface for Middleware and Application Code

- Main Page
- Usage and Description
- Reference

All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Content | Data Structures | Typedefs | Functions
WiFi Control
WiFi Interface

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:

- ARM_WIFI_GetCapabilities

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:

- ARM_WIFI_Initialize

## 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) {
ARM_DRIVER_VERSION version;
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_event | Pointer to ARM_WIFI_SignalEvent_t

Returns
  execution status
  - ARM_DRIVER_OK : Operation successful
  - ARM_DRIVER_ERROR : Operation failed

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);
wifi->PowerControl (ARM_POWER_FULL);
// 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
  - ARM_DRIVER_OK : Operation successful
  - ARM_DRIVER_ERROR : Operation failed

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->PowerControl (ARM_POWER_OFF);
wifi->Uninitialize ();
}

int32_t ARM_WIFI_PowerControl | ( | ARM_POWER_STATE | state | ) |

Control WiFi Module Power.

Parameters

  [in] | state | Power state ARM_POWER_OFF : Power off: no operation possible ARM_POWER_LOW : Low-power mode: sleep or deep-sleep depending on ARM_WIFI_LP_TIMER option set ARM_POWER_FULL : Power on: full operation at maximum performance

Returns
  execution status
  - ARM_DRIVER_OK : Operation successful
  - ARM_DRIVER_ERROR : Operation failed
  - ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
  - ARM_DRIVER_ERROR_PARAMETER : Parameter error (invalid state)

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:

- see ARM_WIFI_Initialize
- see ARM_WIFI_Uninitialize

int32_t ARM_WIFI_GetModuleInfo | ( | char * | module_info,
|  | uint32_t | max_len
| ) |  |

Get Module information.

Parameters

  [out] | module_info | Pointer to character buffer were info string will be returned
  [in] | max_len | Maximum length of string to return (including null terminator)

Returns
  execution status
  - ARM_DRIVER_OK : Operation successful
  - ARM_DRIVER_ERROR : Operation failed
  - ARM_DRIVER_ERROR_UNSUPPORTED : Operation not supported
  - ARM_DRIVER_ERROR_PARAMETER : Parameter error (NULL module_info pointer or max_len equals to 0)

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);
wifi->PowerControl (ARM_POWER_FULL);
// Retrieve module information
wifi->GetModuleInfo(&info, sizeof(info));
}

void ARM_WIFI_SignalEvent | ( | uint32_t | event,
|  | void * | arg
| ) |  |

Signal WiFi Events.

Parameters

  [in] | event | WiFi Events notification mask
  [in] | arg | Pointer 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.