Microchip® Advanced Software Framework

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

        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_battery_voltage (uint16 u16BattVoltx100)
 Set the battery voltage to update the firmware calculations.
Not implemented in WINC3400 firmware. More...
 
sint8 m2m_wifi_set_cust_InfoElement (uint8 *pau8M2mCustInfoElement)
 Asynchronous API to add or remove a user-defined Information Element. More...
 
sint8 m2m_wifi_set_device_name (uint8 *pu8DeviceName, uint8 u8DeviceNameLength)
 Set the WINC3400 device name which is used as P2P device name. 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])
 Asynchronous API for assigning a MAC address to the WINC. 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
This function obtains the MAC address that is currently in use by the device. If the function
returns with @ref M2M_SUCCESS then the content of the memory referenced by pu8MacAddr will be
populated with the 6 byte MAC address; otherwise, that memory will be left unchanged.
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
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

Referenced by app_wifi_init(), and 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.

Synchronous API to query the MAC address programmed into the WINC 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 WINC. 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
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

Referenced by app_wifi_init(), and main().

NMI_API sint8 m2m_wifi_set_battery_voltage ( uint16  u16BattVoltx100)

Set the battery voltage to update the firmware calculations.
Not implemented in WINC3400 firmware.

Enable or Disable logs in run time (Disable Firmware logs will enhance the firmware start-up time and performance)

Set the battery voltage to update the firmware calculations.
Not implemented in WINC3400 firmware.

Parameters
[in]u16BattVoltx100battery voltage multiplied by 100
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
See Also
DISABLE_FIRMWARE_LOGS (build option to disable logs from initializations)
Precondition
m2m_wifi_init
Warning
Precondition
Must be called after initialization through the following function m2m_wifi_init.
Parameters
[in]u16BattVoltx100Battery voltage multiplied by 100
Returns
The function returns M2M_SUCCESS for success and a negative value otherwise.
See Also
m2m_wifi_init
Parameters
[in]u16BattVoltx100battery voltage multiplied by 100
Returns
The function SHALL return M2M_SUCCESS for success and a negative value otherwise.
See Also
DISABLE_FIRMWARE_LOGS (build option to disable logs from initializations)
Precondition
m2m_wifi_init
Warning
NMI_API sint8 m2m_wifi_set_cust_InfoElement ( uint8 *  pau8M2mCustInfoElement)

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

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

This function allows the application to provide a custom Information Element to the
WINC that will be included in all beacon and probe response frames, while in Access Point mode.
If it is required to delete these IEs, fill the buffer with zeros.
Parameters
[in]pau8M2mCustInfoElementPointer to Buffer containing the IE to be used. It is the application developer's responsibility to ensure on the correctness of the information element's ordering passed in. If the pointer is null, this removes any current custom IE. If non-null, the pointer must reference data in the following format:
    --------------- ---------- ---------- ------------------- -------- -------- ----------- -----------------------
    | 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)    |
    --------------- ---------- ---------- ------------------- -------- -------- ----------- -----------------------
Warning
Size of All elements combined must not exceed 255 byte. Used in Access Point Mode.
Note
IEs Format will follow the above format.
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;
}
m2m_wifi_set_cust_InfoElement(elementData);
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;
}
m2m_wifi_set_cust_InfoElement(elementData);
NMI_API sint8 m2m_wifi_set_device_name ( uint8 *  pu8DeviceName,
uint8  u8DeviceNameLength 
)

Set the WINC3400 device name which is used as P2P device name.

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

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

Asynchronous API to set the Wi-Fi Direct "Device Name" of the WINC.

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.
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.

Referenced by app_wifi_init(), and 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, ret, 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, NULL, and ret.

NMI_API sint8 m2m_wifi_set_mac_address ( uint8  au8MacAddress[6])

Asynchronous API for assigning a MAC address to the WINC.

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

This function is intended to allow non-production software to assign a MAC address to the WINC.
Warning
This function is intended for development use only and not for use in production software.
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.
    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.

Referenced by app_wifi_init(), and 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 returns M2M_SUCCESS for success and a negative value otherwise.
See Also
tenuM2mTxPwrLevel m2m_wifi_init
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
Generated on Fri Mar 4 2022 23:26:42 for SAMD21 by   doxygen 1.8.5