User API

Functions of the WiFi interface. More...

Functions
netStatus	netWiFi_Scan (uint32_t if_num, NET_WIFI_SCAN_INFO scan_info[], uint32_t *scan_num)
	Search for available WiFi networks. [thread-safe]. More...
netStatus	netWiFi_GetOption (uint32_t if_num, netWiFi_Option option, void *buf, uint32_t buf_len)
	Get the value of the WiFi driver option. [thread-safe]. More...
netStatus	netWiFi_SetOption (uint32_t if_num, netWiFi_Option option, const void *buf, uint32_t buf_len)
	Set the value of the WiFi driver option. [thread-safe]. More...
netStatus	netWiFi_Activate (uint32_t if_num, const NET_WIFI_CONFIG *config)
	Activate the WiFi interface. [thread-safe]. More...
netStatus	netWiFi_Deactivate (uint32_t if_num)
	Deactivate the WiFi interface. [thread-safe]. More...
bool	netWiFi_IsConnected (uint32_t if_num)
	Get the connection state of the WiFi interface. [thread-safe]. More...
netStatus	netWiFi_GetNetInfo (uint32_t if_num, NET_WIFI_NET_INFO *net_info)
	Get the network information of the WiFi interface. [thread-safe]. More...

Description

Functions of the WiFi interface.

In the Network Component, the WiFi interface is, similar to an Ethernet interface, responsible for various Application/Internet/Link layer protocols such as ARP, NDP, IGMP, and DHCP. In the Network Component v7, these protocols are supported for IPv4 and IPv6 connections (where applicable).

Function Documentation

netWiFi_Activate()

netStatus netWiFi_Activate	(	uint32_t	if_num,
		const NET_WIFI_CONFIG *	config
	)

Activate the WiFi interface. [thread-safe].

Parameters

[in]	if_num	WiFi interface number.
[in]	config	pointer to the structure with configuration parameters.

Returns

status code that indicates the execution status of the function.

The function netWiFi_Activate activates the specified interface. In station mode, the function connects to the wireless network, which must be available or the operation will fail after the timeout. In the access point mode, the function creates a wireless network by activating the access point.

The argument if_num specifies the WiFi Interface to be activated.

The argument config is a pointer to the NET_WIFI_CONFIG structure, which provides information needed to activate the WiFi interface.

• ssid: specifies the name of the network you want to connect to, or the network that you want to create.
• password: specifies the password for accessing the wireless network.
• security: specifies the type of security that will be used for the connection, defined by netWiFi_Security.
• channel: specifies the WiFi channel which will be used for the connection.
  Valid channels for 2.4 GHz frequency are from 1 to 13. If the value for channel is 0, the system automatically selects the channel:
  • station: the channel of the AP being connected to is used.
  • access point: the module automatically selects the best channel for the WiFi connection.
• wps_method: specifies the WiFi Protected Setup (WPS) used, defined by netWiFi_WPS.
• wps_pin: specifies the PIN code used by WPS, when using the netWiFi_WPS_PIN method.

Possible netStatus return values:

• netOK: WiFi interface activated successfully.
• netError: WiFi driver operation not supported.
• netInvalidParameter: Invalid parameter provided.
• netDriverError: WiFi driver operation failed.
• netTimeout: WiFi driver operation timed out.

With the netWiFi_WPS_PBC method, you typically press the button, either real or virtual, both at the access point and the station. No credentials are needed.

With the netWiFi_WPS_PIN method, you must provide the PIN code that you read from the label or screen on the wireless device. WPS configuration for station is used when station connects to an access point. It enables to connect without specifying SSID, Password, Security Type or WiFi Channel. The actual network information can be retrieved once connected with netWiFi_GetNetInfo. WPS configuration for access point is used when access point is activated. Subsequent activate calls re-trigger the WPS procedure.

Code Example

NET_WIFI_CONFIG wifi_config;
 
wifi_config.ssid       = "GuestAccess";
wifi_config.password   = "guest";
wifi_config.security   = netWiFi_SecurityWPA2;
wifi_config.channel    = 0;
wifi_config.wps_method = netWiFi_WPS_None;
 
// Connect to wireless network
status = netWiFi_Activate (0, &wifi_config);
if (status != netOK) {
  // error handling
}

netWiFi_Deactivate()

fn netStatus netWiFi_Deactivate

(

uint32_t

if_num

)

Deactivate the WiFi interface. [thread-safe].

Parameters

[in]

if_num

WiFi interface number.

Returns

status code that indicates the execution status of the function.

The function netWiFi_Deactivate deactivates the specified interface.

The argument if_num specifies the WiFi Interface to be deactivated.

Possible netStatus return values:

• netOK: WiFi interface deactivated successfully.
• netInvalidParameter: Invalid parameter provided.
• netDriverError: WiFi driver operation failed.

Code Example (see netWiFi_GetNetInfo)

netWiFi_GetNetInfo()

netStatus netWiFi_GetNetInfo	(	uint32_t	if_num,
		NET_WIFI_NET_INFO *	net_info
	)

Get the network information of the WiFi interface. [thread-safe].

Parameters

[in]	if_num	WiFi interface number.
[out]	net_info	structure for storing the network information.

Returns

status code that indicates the execution status of the function.

The function netWiFi_GetNetInfo retrieves wireless network information of a connected station. You can use the function to retrieve network information after the initial connection using WPS. Then use this network information for all the subsequent network connections to this wireless network.

The argument if_num specifies the WiFi Interface for obtaining the network information.

The argument net_info is a pointer to the NET_WIFI_NET_INFO structure, where the network information will be returned.

Possible netStatus return values:

• netOK: Network information successfully retrieved.
• netError: Retrieving not possible in WiFi Access Point mode.
• netInvalidParameter: Invalid parameter provided.
• netDriverError: WiFi driver operation failed.

Code Example

NET_WIFI_CONFIG wifi_config;
NET_WIFI_NET_INFO net_info;
 
memset(&wifi_config, 0, sizeof(wifi_config));
 
wifi_config.wps_method = netWiFi_WPS_PBC;
 
// Connect to wireless network (WPS)
status = netWiFi_Activate (0, &wifi_config);
if (status != netOK) {
  // error handling
}
 
// Retrieve network information
if (netWiFi_IsConnected (0)) {
  status = netWiFi_GetNetInfo (0, &net_info);
  if (status != netOK) {
    // error handling
  }
  printf("SSID=%s, Password=%s",net_info.ssid, net_info.pass);
}
 
// Disconnect from wireless network
netWiFi_Deactivate (0);

netWiFi_GetOption()

netStatus netWiFi_GetOption	(	uint32_t	if_num,
		netWiFi_Option	option,
		void *	buf,
		uint32_t	buf_len
	)

Get the value of the WiFi driver option. [thread-safe].

Parameters

[in]	if_num	WiFi interface number.
[in]	option	driver option as specified by netWiFi_Option.
[out]	buf	buffer to store the option value to.
[in]	buf_len	length of buffer.

Returns

status code that indicates the execution status of the function.

The function netWiFi_GetOption retrieves the current value of an option for the WiFi interface driver specified by if_num.

The argument if_num specifies the WiFi Interface for which an option should be obtained.

The argument option specifies the driver option netWiFi_Option that is to be retrieved (see netWiFi_SetOption).

The argument buf points to a buffer that will be used to store the value of the option.

The argument buf_len specifies the length of the buffer buf.

Possible netStatus return values:

• netOK: Option retrieved successfully.
• netInvalidParameter: Invalid parameter or not supported option provided.
• netError: WiFi driver operation not supported.
• netDriverError: WiFi driver operation failed.

Code Example

uint8_t bss_id[6];
 
netWiFi_GetOption (0, netWiFi_OptionBSSID, bss_id, sizeof (bss_id));

netWiFi_IsConnected()

bool netWiFi_IsConnected

(

uint32_t

if_num

)

Get the connection state of the WiFi interface. [thread-safe].

Parameters

[in]

if_num

WiFi interface number.

Returns

connection state:

• true = Station connected to access point.
• false = Station not connected.

The function netWiFi_IsConnected determines the state of the wireless connection. It returns true if the WiFi station is connected to wireless access point and IP frames can be exchanged.

The argument if_num specifies the WiFi Interface to check if it is connected.

Note

• You can use the netWiFi_IsConnected function to continuously monitor the WiFi connection state.

Code Example

void connect_soc (void) {
  // Connect TCP socket when PPP is up. 
  if(netWiFi_IsConnected(0)) {
    netTCP_Connect (socket_tcp, remip, 1000, 0);
  }
}

netWiFi_Scan()

netStatus netWiFi_Scan	(	uint32_t	if_num,
		NET_WIFI_SCAN_INFO	scan_info[],
		uint32_t *	scan_num
	)

Search for available WiFi networks. [thread-safe].

Parameters

[in]	if_num	WiFi interface number.
[out]	scan_info	array of structures for storing the scan information.
[in,out]	scan_num	input maximum number, return number of WiFi networks found.

Returns

status code that indicates the execution status of the function.

The function netWiFi_Scan scans the WiFi networks within range. This function is usually executing for a long time, typically for a few seconds. The execution time is determined by the WiFi driver and the number of available WiFi networks.

The argument if_num specifies the WiFi Interface which is used for scanning.

The argument scan_info is a pointer to an array of NET_WIFI_SCAN_INFO structures, where the available network information will be returned.

The argument scan_num is a pointer to the length of scan_info array. It should initially contain the number of records available in scan_info. Upon return, it contains the actual number of WiFi networks found.

Possible netStatus return values:

• netOK: The search was successfully completed.
• netError: Scanning not possible in WiFi Access Point mode.
• netInvalidParameter: Invalid parameter provided.
• netDriverError: WiFi driver operation failed.

Note

It is common to call the netWiFi_Scan function at system start-up.

Code Example

NET_WIFI_SCAN_INFO scan_info[10];
uint32_t scan_num;
 
scan_num = 10;
if (netWiFi_Scan (0, scan_info, &scan_num) == netOK) {
  // Print SSIDs of available WiFi networks
  for (i = 0; i < scan_num; i++) {
    printf (%d. ssid=%s\n", i, scan_info[i].ssid);
  }
}

netWiFi_SetOption()

netStatus netWiFi_SetOption	(	uint32_t	if_num,
		netWiFi_Option	option,
		const void *	buf,
		uint32_t	buf_len
	)

Set the value of the WiFi driver option. [thread-safe].

Parameters

[in]	if_num	WiFi interface number.
[in]	option	driver option as specified by netWiFi_Option.
[in]	buf	buffer containing the option value.
[in]	buf_len	length of buffer.

Returns

status code that indicates the execution status of the function.

The function netWiFi_SetOption sets different options for the WiFi interface driver identified by the argument if_num.

The argument if_num specifies the WiFi Interface for which the option must be set.

The argument option specifies the driver option netWiFi_Option that is to be set (see below).

The argument buf points to a buffer containing the value of the option to be set.

The argument buf_len specifies the actual length of the buffer buf and must match the length of the corresponding option as specified with argument option (see below).

Option	Description	Length
netWiFi_OptionBSSID	BSSID of the WiFi Station or Access Point	6 bytes
netWiFi_OptionTxPower	WiFi transmit power	4 bytes
netWiFi_OptionLpTimer	Low-power deep-sleep time	4 bytes
netWiFi_OptionDTIM	DTIM interval	4 bytes
netWiFi_OptionBeacon	Beacon interval	4 bytes

Possible netStatus return values:

• netOK: Option successfully set.
• netInvalidParameter: Invalid parameter or not supported option provided.
• netError: WiFi driver operation not supported.
• netDriverError: WiFi driver operation failed.

Code Example

uint8_t  bss_id[6] = { 0x10, 0x11, 0x12, 0x13, 0x14, 0x15 };
uint32_t beacon_interval = 100;
 
// Set BSSID and beacon interval 100ms
netWiFi_SetOption (0, netWiFi_OptionBSSID, bss_id, sizeof (bss_id));
netWiFi_SetOption (0, netWiFi_OptionBeacon, &beacon_interval, sizeof(beacon_interval));