Microchip® Advanced Software Framework

 All Data Structures Files Functions Variables Typedefs Enumerations Enumerator Macros Groups Pages
Configuration

         Here are listed all the functions that implement the Wlan Configuration APIs.

Functions

NMI_API sint8 m2m_wifi_conf_auto_rate (tstrConfAutoRate *pstrConfAutoRate)
 Allow the host MCU app to configure auto TX rate selection algorithm. The application can use this API to tweak the algorithm performance. Moreover, it allows the application to force a specific WLAN PHY rate for transmitted data packets to favor range vs. throughput needs. More...
 
sint8 m2m_wifi_get_mac_address (uint8 *pu8MacAddr)
 Request the current MAC address of the device (the working mac address). (the function is Blocking until response received) More...
 
sint8 m2m_wifi_get_otp_mac_address (uint8 *pu8MacAddr, uint8 *pu8IsValid)
 Request the MAC address stored on the OTP (one time programmable) memory of the device. (the function is Blocking until response received) More...
 
sint8 m2m_wifi_set_cust_InfoElement (uint8 *pau8M2mCustInfoElement)
 API to add or remove a user-defined Information Element. More...
 
sint8 m2m_wifi_set_device_name (uint8 *pu8DeviceName, uint8 u8DeviceNameLength)
 Sets the WINC device name. The name string is used as a device name in DHCP hostname (option 12). More...
 
sint8 m2m_wifi_set_gain_table_idx (uint8 u8GainTableIdx)
 set the gain table index corresponding to a specific WiFi region More...
 
sint8 m2m_wifi_set_gains (tstrM2mWifiGainsParams *pstrM2mGain)
 Set the chip PPA gain for 11b/11gn. More...
 
sint8 m2m_wifi_set_mac_address (uint8 au8MacAddress[6])
 Synchronous API for assigning a MAC address to the WINC IC. More...
 
sint8 m2m_wifi_set_tx_power (uint8 u8TxPwrLevel)
 set the TX power tenuM2mTxPwrLevel More...
 

NMI_API sint8 m2m_wifi_conf_auto_rate ( tstrConfAutoRate pstrConfAutoRate)

Allow the host MCU app to configure auto TX rate selection algorithm. The application can use this API to tweak the algorithm performance. Moreover, it allows the application to force a specific WLAN PHY rate for transmitted data packets to favor range vs. throughput needs.

Configures WLAN automatic TX rate adaptation algorithm.

Parameters
[in]pstrConfAutoRateThe Auto rate configuration parameters as listed in tstrConfAutoRate.
See Also
tstrConfAutoRate
Returns
The function SHALL return 0 for success and a negative value otherwise.
Allow the host MCU app to configure auto TX rate selection algorithm. The application can use this 
API to tweak the algorithm performance. Moreover, it allows the application to force a specific WLAN 
PHY rate for transmitted data packets to favor range vs. throughput needs.
Parameters
[in]pstrConfAutoRateThe Auto rate configuration parameters as listed in tstrConfAutoRate.
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
See Also
tstrConfAutoRate

References hif_send(), M2M_ERR_FAIL, M2M_REQ_GROUP_WIFI, M2M_WIFI_REQ_CONG_AUTO_RATE, and NULL.

NMI_API sint8 m2m_wifi_get_mac_address ( uint8 pu8MacAddr)

Request the current MAC address of the device (the working mac address). (the function is Blocking until response received)

Synchronous API to retrieve the MAC address currently in use by the device.

Parameters
[out]pu8MacAddrOutput MAC address buffer of 6 bytes size.
Returns
The function shall return M2M_SUCCESS for success and a negative value otherwise.
See Also
m2m_wifi_get_otp_mac_address
Precondition
m2m_wifi_init required to call any WIFI/socket function
Function to retrieve the current MAC address. 
The function is blocking until the response is received.
Precondition
Prior call to m2m_wifi_init is required before any WIFI/socket function.
Parameters
[out]pu8MacAddrPointer to a buffer in memory containing a 6-byte MAC address (provided function returns M2M_SUCCESS).
Returns
The function returns M2M_SUCCESS for successful operation and a negative value otherwise.
See Also
m2m_wifi_get_otp_mac_address

References hif_chip_sleep(), hif_chip_wake(), M2M_SUCCESS, and nmi_get_mac_address().

Referenced by main().

NMI_API sint8 m2m_wifi_get_otp_mac_address ( uint8 pu8MacAddr,
uint8 pu8IsValid 
)

Request the MAC address stored on the OTP (one time programmable) memory of the device. (the function is Blocking until response received)

Synchronous API to query the MAC address programmed into the WINC ICs OTP memory.

Parameters
[out]pu8MacAddrOutput MAC address buffer of 6 bytes size. Valid only if *pu8Valid=1.
[out]pu8IsValidA output boolean value to indicate the validity of pu8MacAddr in OTP. Output zero if the OTP memory is not programmed, non-zero otherwise.
Returns
The function shall return M2M_SUCCESS for success and a negative value otherwise.
See Also
m2m_wifi_get_mac_address
Precondition
m2m_wifi_init required to call any WIFI/socket function
This function attempts to read the device's MAC address from the One Time Programmable (OTP)
memory on the IC. The presence (yes or no) of a MAC address in the OTP memory and, in the case
of it being present, its value is returned via RAM pointed to by the input arguments.

Request the MAC address stored on the One Time Programmable(OTP) memory of the device.
The function is blocking until the response is received.
Precondition
Prior call to m2m_wifi_init is required before any WIFI/socket function.
Parameters
[out]pu8MacAddrOutput MAC address buffer 6 bytes in size. Valid only if *pu8Valid=1.
[out]pu8IsValidA boolean value set by the callee to indicate the validity of pu8MacAddr in OTP. If no MAC has been programmed in the OTP the value of this parameter will be zero; otherwise it will be non-zero.
Returns
The function returns M2M_SUCCESS for success and a negative value otherwise.
See Also
m2m_wifi_get_mac_address

References hif_chip_sleep(), hif_chip_wake(), M2M_SUCCESS, and nmi_get_otp_mac_address().

Referenced by main().

NMI_API sint8 m2m_wifi_set_cust_InfoElement ( uint8 pau8M2mCustInfoElement)

API to add or remove a user-defined Information Element.

Synchronous function to Add/Remove user-defined Information Element to the WIFIBeacon and Probe Response frames while chip mode is Access Point Mode.\n
According to the information element layout shown bellow, if it is required to set new data for the information elements, pass in the buffer with the
information according to the sizes and ordering defined bellow. However, if it's required to delete these IEs, fill the buffer with zeros.
Parameters
[in]pau8M2mCustInfoElementPointer to Buffer containing the IE to be sent. It is the application developer's responsibility to ensure on the correctness of the information element's ordering passed in.
Warning
Size of All elements combined must not exceed 255 byte. Used in Access Point Mode.
Note
IEs Format will be follow the following layout:
    --------------- ---------- ---------- ------------------- -------- -------- ----------- -----------------------
              | Byte[0]       | Byte[1]  | Byte[2]  | Byte[3:length1+2] | ..... | Byte[n] | Byte[n+1] | Byte[n+2:lengthx+2]  | 
    |---------------|----------|----------|-------------------|-------- --------|-----------|---------------------|
              | #of all Bytes | IE1 ID   | Length1  | Data1(Hex Coded)  | ..... | IEx ID  | Lengthx   | Datax(Hex Coded)     | 
    --------------- ---------- ---------- ------------------- -------- -------- ----------- -----------------------
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
See Also
m2m_wifi_enable_sntp

Example

The example demonstrates how the information elements are set using this function.

char elementData[21];
static char state = 0; // To Add, Append, and Delete
if(0 == state) { //Add 3 IEs
state = 1;
//Total Number of Bytes
elementData[0]=12;
//First IE
elementData[1]=200; elementData[2]=1; elementData[3]='A';
//Second IE
elementData[4]=201; elementData[5]=2; elementData[6]='B'; elementData[7]='C';
//Third IE
elementData[8]=202; elementData[9]=3; elementData[10]='D'; elementData[11]=0; elementData[12]='F';
} else if(1 == state) {
//Append 2 IEs to others, Notice that we keep old data in array starting with\n
//element 13 and total number of bytes increased to 20
state = 2;
//Total Number of Bytes
elementData[0]=20;
//Fourth IE
elementData[13]=203; elementData[14]=1; elementData[15]='G';
//Fifth IE
elementData[16]=204; elementData[17]=3; elementData[18]='X'; elementData[19]=5; elementData[20]='Z';
} else if(2 == state) { //Delete All IEs
state = 0;
//Total Number of Bytes
elementData[0]=0;
}

References hif_send(), M2M_CUST_IE_LEN_MAX, M2M_ERR_FAIL, M2M_REQ_DATA_PKT, M2M_REQ_GROUP_WIFI, M2M_WIFI_REQ_CUST_INFO_ELEMENT, and NULL.

NMI_API sint8 m2m_wifi_set_device_name ( uint8 pu8DeviceName,
uint8  u8DeviceNameLength 
)

Sets the WINC device name. The name string is used as a device name in DHCP hostname (option 12).

Asynchronous API to set the "Device Name" of the WINC IC.

Parameters
[in]pu8DeviceNameBuffer holding the device name.
[in]u8DeviceNameLengthLength of the device name.
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
Warning
The Function called once after initialization.
Sets the WINC device name. The name string is used as a device name in DHCP
hostname (option 12).
If a device is not set through this function a default name is assigned.
The default name is WINC-XX-YY, where XX and YY are the last 2 octets of the OTP 
MAC address. If OTP (eFuse) is programmed, then the default name is WINC-00-00.
Warning
The function called once after initialization.
Used for DHCP client hostname option (12).
Device name shall contain only characters allowed in valid internet host name as defined in RFC 952 and 1123.
Parameters
[in]pu8DeviceNameBuffer holding the device name. Device name is a null terminated C string.
[in]u8DeviceNameLengthLength of the device name. Should not exceed the maximum device name's length M2M_DEVICE_NAME_MAX (including null character).
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

References tstrM2MDeviceNameConfig::au8DeviceName, hif_send(), M2M_DEVICE_NAME_MAX, m2m_memcpy(), M2M_REQ_GROUP_WIFI, M2M_WIFI_REQ_SET_DEVICE_NAME, and NULL.

Referenced by main().

NMI_API sint8 m2m_wifi_set_gain_table_idx ( uint8  u8GainTableIdx)

set the gain table index corresponding to a specific WiFi region

Set the Gain table index corresponding to specific WiFi region.

Parameters
[in]u8GainTableIdxchange the gain table index
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
Precondition
The gain tables must be written to the flash through gain builder tool. m2m_wifi_init
Warning
Parameters
[in]u8GainTableIdxchange the gain table index based on the WiFi region it is suppose to be used.
Precondition
Must be called after the initialization and before any connection request. The corresponding gain tables must be present in the flash.
Returns
The function returns M2M_SUCCESS for successful operations and a negative value otherwise.
See Also
m2m_wifi_init

References hif_send(), M2M_REQ_GROUP_WIFI, M2M_SUCCESS, M2M_WIFI_REQ_SET_GAIN_TABLE_IDX, NULL, and tstrM2mWiFiGainIdx::u8GainTableIdx.

sint8 m2m_wifi_set_gains ( tstrM2mWifiGainsParams pstrM2mGain)

Set the chip PPA gain for 11b/11gn.

Parameters
[in]pstrM2mGaintstrM2mWifiGainsParams contain gain parameters as implemented in rf document.
Precondition
Must be called after initialization through the following function m2m_wifi_init.
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.
See Also
m2m_wifi_init

References hif_send(), M2M_ERR_FAIL, M2M_REQ_GROUP_WIFI, M2M_WIFI_REQ_SET_GAINS, and NULL.

NMI_API sint8 m2m_wifi_set_mac_address ( uint8  au8MacAddress[6])

Synchronous API for assigning a MAC address to the WINC IC.

    This function override the already assigned MAC address of the WINC board with a user provided one. This is for experimental 
    use only and should never be used in the production SW.
Parameters
[in]au8MacAddressMAC Address to be provisioned to the WINC.
Returns
The function returns M2M_SUCCESS if the command has been successfully queued to the WINC and a negative value otherwise.

References tstrM2mSetMacAddress::au8Mac, hif_send(), m2m_memcpy(), M2M_REQ_GROUP_WIFI, M2M_WIFI_REQ_SET_MAC_ADDRESS, and NULL.

Referenced by main().

NMI_API sint8 m2m_wifi_set_tx_power ( uint8  u8TxPwrLevel)

set the TX power tenuM2mTxPwrLevel

Set the TX power tenuM2mTxPwrLevel.

Parameters
[in]u8TxPwrLevelchange the TX power tenuM2mTxPwrLevel
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
See Also
tenuM2mTxPwrLevel
Precondition
m2m_wifi_init
Warning
Parameters
[in]u8TxPwrLevelChange the TX power based on the enumeration tenuM2mTxPwrLevel.
Precondition
Must be called after the initialization and before any connection request and can't be changed in runtime.
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
See Also
tenuM2mTxPwrLevel m2m_wifi_init

References hif_send(), M2M_REQ_GROUP_WIFI, M2M_SUCCESS, M2M_WIFI_REQ_SET_TX_POWER, NULL, and tstrM2mTxPwrLevel::u8TxPwrLevel.