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.

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

Description

Control functions for the WiFi module.

The WiFi Control functions setup and control the WiFi module.

---

Data Structure Documentation

ARM_WIFI_CAPABILITIES

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

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_WIFI_GetVersion()

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_GetCapabilities()

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
   :
}

ARM_WIFI_Initialize()

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);
}

ARM_WIFI_Uninitialize()

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 ();
}

ARM_WIFI_PowerControl()

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

ARM_WIFI_GetModuleInfo()

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));
}

ARM_WIFI_SignalEvent()

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

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.