Network Component  
MDK Middleware for IPv4 and IPv6 Networking
 
Loading...
Searching...
No Matches
Functions
User API
Interfaces » WiFi Interface

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].
 
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].
 
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].
 
netStatus netWiFi_Activate (uint32_t if_num, const NET_WIFI_CONFIG *config)
 Activate the WiFi interface. [thread-safe].
 
netStatus netWiFi_Deactivate (uint32_t if_num)
 Deactivate the WiFi interface. [thread-safe].
 
bool netWiFi_IsConnected (uint32_t if_num)
 Get the connection state of the WiFi interface. [thread-safe].
 
netStatus netWiFi_GetNetInfo (uint32_t if_num, NET_WIFI_NET_INFO *net_info)
 Get the network information of the WiFi interface. [thread-safe].
 

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, MLD and DHCP. In the Network Component, 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_numWiFi interface number.
[in]configpointer 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_numWiFi 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_numWiFi interface number.
[out]net_infostructure 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_numWiFi interface number.
[in]optiondriver option as specified by netWiFi_Option.
[out]bufbuffer to store the option value to.
[in]buf_lenlength 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_numWiFi 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_numWiFi interface number.
[out]scan_infoarray of structures for storing the scan information.
[in,out]scan_numinput 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_numWiFi interface number.
[in]optiondriver option as specified by netWiFi_Option.
[in]bufbuffer containing the option value.
[in]buf_lenlength 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));