iot_wifi.h File Reference

Wi-Fi Interface. More...

#include <stdint.h>
#include "portmacro.h"
#include "aws_wifi_config.h"
#include "types/iot_network_types.h"

Go to the source code of this file.

Data Structures
struct	WIFINetworkParams_t
	Parameters passed to the WIFI_ConnectAP API for connection. More...
struct	WIFIScanResult_t
	Wi-Fi scan results. More...
struct	WIFINetworkProfile_t
	Wi-Fi network parameters passed to the WIFI_NetworkAdd API. More...

Enumerations
enum	WIFIReturnCode_t { eWiFiSuccess = 0, eWiFiFailure = 1, eWiFiTimeout = 2, eWiFiNotSupported = 3 }
	Return code denoting API status. More...
enum	WIFISecurity_t {   eWiFiSecurityOpen = 0, eWiFiSecurityWEP, eWiFiSecurityWPA, eWiFiSecurityWPA2,   eWiFiSecurityWPA2_ent, eWiFiSecurityNotSupported }
	Wi-Fi Security types. More...
enum	WIFIDeviceMode_t { eWiFiModeStation = 0, eWiFiModeAP, eWiFiModeP2P, eWiFiModeNotSupported }
	Wi-Fi device modes. More...
enum	WIFIPMMode_t { eWiFiPMNormal = 0, eWiFiPMLowPower, eWiFiPMAlwaysOn, eWiFiPMNotSupported }
	Wi-Fi device power management modes. More...

Functions
WIFIReturnCode_t	WIFI_On (void)
	Turns on Wi-Fi. More...
WIFIReturnCode_t	WIFI_Off (void)
	Turns off Wi-Fi. More...
WIFIReturnCode_t	WIFI_ConnectAP (const WIFINetworkParams_t *const pxNetworkParams)
	Connects to the Wi-Fi Access Point (AP) specified in the input. More...
WIFIReturnCode_t	WIFI_Disconnect (void)
	Disconnects from the currently connected Access Point. More...
WIFIReturnCode_t	WIFI_Reset (void)
	Resets the Wi-Fi Module. More...
WIFIReturnCode_t	WIFI_SetMode (WIFIDeviceMode_t xDeviceMode)
	Sets the Wi-Fi mode. More...
WIFIReturnCode_t	WIFI_GetMode (WIFIDeviceMode_t *pxDeviceMode)
	Gets the Wi-Fi mode. More...
WIFIReturnCode_t	WIFI_NetworkAdd (const WIFINetworkProfile_t *const pxNetworkProfile, uint16_t *pusIndex)
	Add a Wi-Fi Network profile. More...
WIFIReturnCode_t	WIFI_NetworkGet (WIFINetworkProfile_t *pxNetworkProfile, uint16_t usIndex)
	Get a Wi-Fi network profile. More...
WIFIReturnCode_t	WIFI_NetworkDelete (uint16_t usIndex)
	Delete a Wi-Fi Network profile. More...
WIFIReturnCode_t	WIFI_Ping (uint8_t *pucIPAddr, uint16_t usCount, uint32_t ulIntervalMS)
	Ping an IP address in the network. More...
WIFIReturnCode_t	WIFI_GetIP (uint8_t *pucIPAddr)
	Retrieves the Wi-Fi interface's IP address. More...
WIFIReturnCode_t	WIFI_GetMAC (uint8_t *pucMac)
	Retrieves the Wi-Fi interface's MAC address. More...
WIFIReturnCode_t	WIFI_GetHostIP (char *pcHost, uint8_t *pucIPAddr)
	Retrieves the host IP address from a host name using DNS. More...
WIFIReturnCode_t	WIFI_Scan (WIFIScanResult_t *pxBuffer, uint8_t ucNumNetworks)
	Perform a Wi-Fi network Scan. More...
WIFIReturnCode_t	WIFI_StartAP (void)
	Start SoftAP mode. More...
WIFIReturnCode_t	WIFI_StopAP (void)
	Stop SoftAP mode. More...
WIFIReturnCode_t	WIFI_ConfigureAP (const WIFINetworkParams_t *const pxNetworkParams)
	Configure SoftAP. More...
WIFIReturnCode_t	WIFI_SetPMMode (WIFIPMMode_t xPMModeType, const void *pvOptionValue)
	Set the Wi-Fi power management mode. More...
WIFIReturnCode_t	WIFI_GetPMMode (WIFIPMMode_t *pxPMModeType, void *pvOptionValue)
	Get the Wi-Fi power management mode. More...
WIFIReturnCode_t	WIFI_RegisterNetworkStateChangeEventCallback (IotNetworkStateChangeEventCallback_t xCallback)
	Registers application callback for network state change events from WiFi layer. More...
BaseType_t	WIFI_IsConnected (void)
	Check if the Wi-Fi is connected. More...

Detailed Description

Wi-Fi Interface.

Enumeration Type Documentation

WIFIReturnCode_t

enum WIFIReturnCode_t

Return code denoting API status.

Note

Codes other than eWiFiSuccess are failure codes.

Enumerator
eWiFiSuccess	Success.
eWiFiFailure	Failure.
eWiFiTimeout	Timeout.
eWiFiNotSupported	Not supported.

WIFISecurity_t

enum WIFISecurity_t

Wi-Fi Security types.

Enumerator
eWiFiSecurityOpen	Open - No Security.
eWiFiSecurityWEP	WEP Security.
eWiFiSecurityWPA	WPA Security.
eWiFiSecurityWPA2	WPA2 Security.
eWiFiSecurityWPA2_ent	WPA2 Enterprise Security.
eWiFiSecurityNotSupported	Unknown Security.

WIFIDeviceMode_t

enum WIFIDeviceMode_t

Wi-Fi device modes.

Device roles/modes supported.

Enumerator
eWiFiModeStation	Station mode.
eWiFiModeAP	Access point mode.
eWiFiModeP2P	P2P mode.
eWiFiModeNotSupported	Unsupported mode.

WIFIPMMode_t

enum WIFIPMMode_t

Wi-Fi device power management modes.

Device power management modes supported.

Enumerator
eWiFiPMNormal	Normal mode.
eWiFiPMLowPower	Low Power mode.
eWiFiPMAlwaysOn	Always On mode.
eWiFiPMNotSupported	Unsupported PM mode.

Function Documentation

WIFI_On()

WIFIReturnCode_t WIFI_On

(

void

)

Turns on Wi-Fi.

This function turns on Wi-Fi module,initializes the drivers and must be called before calling any other Wi-Fi API

Returns

eWiFiSuccess if Wi-Fi module was successfully turned on, failure code otherwise.

WIFI_Off()

WIFIReturnCode_t WIFI_Off

(

void

)

Turns off Wi-Fi.

This function turns off the Wi-Fi module. The Wi-Fi peripheral should be put in a low power or off state in this routine.

Returns

eWiFiSuccess if Wi-Fi module was successfully turned off, failure code otherwise.

WIFI_ConnectAP()

WIFIReturnCode_t WIFI_ConnectAP

(

const WIFINetworkParams_t *const

pxNetworkParams

)

Connects to the Wi-Fi Access Point (AP) specified in the input.

The Wi-Fi should stay connected when the same Access Point it is currently connected to is specified. Otherwise, the Wi-Fi should disconnect and connect to the new Access Point specified. If the new Access Point specifed has invalid parameters, then the Wi-Fi should be disconnected.

Parameters

[in]

pxNetworkParams

Configuration to join AP.

Returns

eWiFiSuccess if connection is successful, failure code otherwise.

Example

WIFINetworkParams_t xNetworkParams;
WIFIReturnCode_t xWifiStatus;
xNetworkParams.pcSSID = "SSID String";
xNetworkParams.ucSSIDLength = SSIDLen;
xNetworkParams.pcPassword = "Password String";
xNetworkParams.ucPasswordLength = PassLength;
xNetworkParams.xSecurity = eWiFiSecurityWPA2;
xWifiStatus = WIFI_ConnectAP( &( xNetworkParams ) );
if(xWifiStatus == eWiFiSuccess)
{
    //Connected to AP.
}

See also

WIFINetworkParams_t

WIFI_Disconnect()

WIFIReturnCode_t WIFI_Disconnect

(

void

)

Disconnects from the currently connected Access Point.

Returns

eWiFiSuccess if disconnection was successful or if the device is already disconnected, failure code otherwise.

WIFI_Reset()

WIFIReturnCode_t WIFI_Reset

(

void

)

Resets the Wi-Fi Module.

Returns

eWiFiSuccess if Wi-Fi module was successfully reset, failure code otherwise.

WIFI_SetMode()

WIFIReturnCode_t WIFI_SetMode

(

WIFIDeviceMode_t

xDeviceMode

)

Sets the Wi-Fi mode.

Parameters

[in]

xDeviceMode

- Mode of the device Station / Access Point /P2P.

Example

WIFIReturnCode_t xWifiStatus;
xWifiStatus = WIFI_SetMode(eWiFiModeStation);
if(xWifiStatus == eWiFiSuccess)
{
    //device Set to station mode
}

Returns

eWiFiSuccess if Wi-Fi mode was set successfully, failure code otherwise.

WIFI_GetMode()

WIFIReturnCode_t WIFI_GetMode

(

WIFIDeviceMode_t *

pxDeviceMode

)

Gets the Wi-Fi mode.

Parameters

[out]

pxDeviceMode

- return mode Station / Access Point /P2P

Example

WIFIReturnCode_t xWifiStatus;
WIFIDeviceMode_t xDeviceMode;
xWifiStatus = WIFI_GetMode(&xDeviceMode);
if(xWifiStatus == eWiFiSuccess)
{
   //device mode is xDeviceMode
}

Returns

eWiFiSuccess if Wi-Fi mode was successfully retrieved, failure code otherwise.

WIFI_NetworkAdd()

WIFIReturnCode_t WIFI_NetworkAdd	(	const WIFINetworkProfile_t *const	pxNetworkProfile,
		uint16_t *	pusIndex
	)

Add a Wi-Fi Network profile.

Adds a Wi-fi network to the network list in Non Volatile memory.

Parameters

[in]	pxNetworkProfile	- Network profile parameters
[out]	pusIndex	- Network profile index in storage

Returns

Index of the profile storage on success, or failure return code on failure.

Example

WIFINetworkProfile_t xNetworkProfile = {0};
WIFIReturnCode_t xWiFiStatus;
uint16_t usIndex;
strncpy( xNetworkProfile.cSSID, "SSID_Name", SSIDLen));
xNetworkProfile.ucSSIDLength = SSIDLen;
strncpy( xNetworkProfile.cPassword, "PASSWORD",PASSLen );
xNetworkProfile.ucPasswordLength = PASSLen;
xNetworkProfile.xSecurity = eWiFiSecurityWPA2;
WIFI_NetworkAdd( &xNetworkProfile, &usIndex );

WIFI_NetworkGet()

WIFIReturnCode_t WIFI_NetworkGet	(	WIFINetworkProfile_t *	pxNetworkProfile,
		uint16_t	usIndex
	)

Get a Wi-Fi network profile.

Gets the Wi-Fi network parameters at the given index from network list in non-volatile memory.

Note

The WIFINetworkProfile_t data returned must have the the SSID and Password lengths specified as the length without a null terminator.

Parameters

[out]	pxNetworkProfile	- pointer to return network profile parameters
[in]	usIndex	- Index of the network profile, must be between 0 to wificonfigMAX_NETWORK_PROFILES

Returns

eWiFiSuccess if the network profile was successfully retrieved, failure code otherwise.

See also

WIFINetworkProfile_t

Example

WIFINetworkProfile_t xNetworkProfile = {0};
uint16_t usIndex = 3;  //Get profile stored at index 3.
WIFI_NetworkGet( &xNetworkProfile, usIndex );

WIFI_NetworkDelete()

WIFIReturnCode_t WIFI_NetworkDelete

(

uint16_t

usIndex

)

Delete a Wi-Fi Network profile.

Deletes the Wi-Fi network profile from the network profile list at given index in non-volatile memory

Parameters

[in]

usIndex

- Index of the network profile, must be between 0 to wificonfigMAX_NETWORK_PROFILES.

If wificonfigMAX_NETWORK_PROFILES is the index, then all network profiles will be deleted.

Returns

eWiFiSuccess if successful, failure code otherwise. If successful, the interface IP address is copied into the IP address buffer.

Example

uint16_t usIndex = 2; //Delete profile at index 2
WIFI_NetworkDelete( usIndex );

WIFI_Ping()

WIFIReturnCode_t WIFI_Ping	(	uint8_t *	pucIPAddr,
		uint16_t	usCount,
		uint32_t	ulIntervalMS
	)

Ping an IP address in the network.

Parameters

[in]	pucIPAddr	IP Address array to ping.
[in]	usCount	Number of times to ping
[in]	ulIntervalMS	Interval in mili-seconds for ping operation

Returns

eWiFiSuccess if ping was successful, other failure code otherwise.

WIFI_GetIP()

WIFIReturnCode_t WIFI_GetIP

(

uint8_t *

pucIPAddr

)

Retrieves the Wi-Fi interface's IP address.

Parameters

[out]

pucIPAddr

IP Address buffer.

Returns

eWiFiSuccess if successful and IP Address buffer has the interface's IP address, failure code otherwise.

Example

uint8_t ucIPAddr[ 4 ];
WIFI_GetIP( &ucIPAddr[0] );

WIFI_GetMAC()

WIFIReturnCode_t WIFI_GetMAC

(

uint8_t *

pucMac

)

Retrieves the Wi-Fi interface's MAC address.

Parameters

[out]

pucMac

MAC Address buffer sized 6 bytes.

Example

uint8_t ucMacAddressVal[ wificonfigMAX_BSSID_LEN ];
WIFI_GetMAC( &ucMacAddressVal[0] );

Returns

eWiFiSuccess if the MAC address was successfully retrieved, failure code otherwise. The returned MAC address must be 6 consecutive bytes with no delimitters.

WIFI_GetHostIP()

WIFIReturnCode_t WIFI_GetHostIP	(	char *	pcHost,
		uint8_t *	pucIPAddr
	)

Retrieves the host IP address from a host name using DNS.

Parameters

[in]	pcHost	- Host (node) name.
[in]	pucIPAddr	- IP Address buffer.

Returns

eWiFiSuccess if the host IP address was successfully retrieved, failure code otherwise.

Example

uint8_t ucIPAddr[ 4 ];
WIFI_GetHostIP( "amazon.com", &ucIPAddr[0] );

WIFI_Scan()

WIFIReturnCode_t WIFI_Scan	(	WIFIScanResult_t *	pxBuffer,
		uint8_t	ucNumNetworks
	)

Perform a Wi-Fi network Scan.

Parameters

[in]	pxBuffer	- Buffer for scan results.
[in]	ucNumNetworks	- Number of networks to retrieve in scan result.

Returns

eWiFiSuccess if the Wi-Fi network scan was successful, failure code otherwise.

Note

The input buffer will have the results of the scan.

Example

const uint8_t ucNumNetworks = 10; //Get 10 scan results
WIFIScanResult_t xScanResults[ ucNumNetworks ];
WIFI_Scan( xScanResults, ucNumNetworks );

WIFI_StartAP()

WIFIReturnCode_t WIFI_StartAP

(

void

)

Start SoftAP mode.

Returns

eWiFiSuccess if SoftAP was successfully started, failure code otherwise.

WIFI_StopAP()

WIFIReturnCode_t WIFI_StopAP

(

void

)

Stop SoftAP mode.

Returns

eWiFiSuccess if the SoftAP was successfully stopped, failure code otherwise.

WIFI_ConfigureAP()

WIFIReturnCode_t WIFI_ConfigureAP

(

const WIFINetworkParams_t *const

pxNetworkParams

)

Configure SoftAP.

Parameters

[in]

pxNetworkParams

- Network parameters to configure AP.

Returns

eWiFiSuccess if SoftAP was successfully configured, failure code otherwise.

Example

WIFINetworkParams_t xNetworkParams;
xNetworkParams.pcSSID = "SSID_Name";
xNetworkParams.pcPassword = "PASSWORD";
xNetworkParams.xSecurity = eWiFiSecurityWPA2;
xNetworkParams.cChannel = ChannelNum;
WIFI_ConfigureAP( &xNetworkParams );

WIFI_SetPMMode()

WIFIReturnCode_t WIFI_SetPMMode	(	WIFIPMMode_t	xPMModeType,
		const void *	pvOptionValue
	)

Set the Wi-Fi power management mode.

Parameters

[in]	xPMModeType	- Power mode type.
[in]	pvOptionValue	- A buffer containing the value of the option to set depends on the mode type example - beacon interval in sec

Returns

eWiFiSuccess if the power mode was successfully configured, failure code otherwise.

WIFI_GetPMMode()

WIFIReturnCode_t WIFI_GetPMMode	(	WIFIPMMode_t *	pxPMModeType,
		void *	pvOptionValue
	)

Get the Wi-Fi power management mode.

Parameters

[out]	pxPMModeType	- pointer to get current power mode set.
[out]	pvOptionValue	- optional value

Returns

eWiFiSuccess if the power mode was successfully retrieved, failure code otherwise.

WIFI_RegisterNetworkStateChangeEventCallback()

WIFIReturnCode_t WIFI_RegisterNetworkStateChangeEventCallback

(

IotNetworkStateChangeEventCallback_t

xCallback

)

Registers application callback for network state change events from WiFi layer.

Parameters

[in]

xCallback

Application callback for network state change events.

Returns

eWiFiSuccess if application callback registration was successful, failure code if otherwise.

WIFI_IsConnected()

BaseType_t WIFI_IsConnected

(

void

)

Check if the Wi-Fi is connected.

Returns

pdTRUE if the link is up, pdFalse otherwise.