Mediatek Labs LinkIt Instruction Manual

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s). MediaTek cannot grant you

permission for any material that is owned by third parties. You may only use or reproduce this document if you have agreed to and been

bound by the applicable license agreement with MediaTek (“License Agreement”) and been granted explicit permission within the License

Agreement (“Permitted User”). If you are not a Permitted User, please cease any access or use of this document immediately. Any

unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited. THIS DOCUMENT IS PROVIDED ON AN

“AS-IS” BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES OF ANY KIND AND SHALL IN NO EVENT BE LIABLE FOR ANY

CLAIMS RELATING TO OR ARISING OUT OF THIS DOCUMENT OR ANY USE OR INABILITY TO USE THEREOF. Specifications contained herein are

subject to change without notice.

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Version: 1.7

Release date: 15 September 2017

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page i of iii

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

Document Revision History

Revision Date Description

1.0 7 March 2016 Initial release

1.1 22 April 2016 •Wi-Fi WPS connection support.

•Replaced NVRAM with NVDM.

•Changed the API naming to register and unregister an event handler, such

as replacing the wifi_connection_register_event_notifier()

with wifi_connection_register_event_handler().

1.2 30 June 2016 •The document is updated to include Wi-Fi initialization APIs and supported

library descriptions for the Wi-Fi module.

•Instructions on how to configure the Wi-Fi module in repeater mode.

•Updated the Scan APIs and Smart Connection APIs.

•Deleted the Wi-Fi Profile.

1.3 2 September 2016 •Updated Table 3 to list the functions that can be invoked before task

scheduler running.

•Instructions on how to configure the Wi-Fi connection with a specific

BSSID.

•Updated Smart Connection Overview and Figure 3.

1.4 4 November 2016 •Renamed “libbsp.a”to “libwifi.a”.

1.5 13 January 2017 •Updated the software architecture diagram.

•Added the monitor mode for raw Wi-Fi packets.

1.6 5 May 2017 •Updated the overview to add description for MT7686/MT7682/MT5932

chipsets.

•Added Table 1 to describe supported features of different chipsets.

•Updated supported libraries.

•Added detailed description about payload of each event in Wi-Fi event

Table 5.

•Added

wifi_config_set_country_code()/wifi_config_get_country_

code() APIs in Table 6.

•Modified the example code to process the WEP key length when the

device is in AP mode.

•Renamed “Elian APK” to “SmartConnection APK”.

•Modified the folder name for APK and Smart Connection libraries.

•Updated the supported version of Smart Connection protocol.

1.7 15 September

2017

•Updated the software architecture in Figure 1.

•Updated section 1.1, “Supported features” to include support for

MT7682/MT7687 STA WPS and repeater modes.

•Updated section 2.7, “WPS”. AP + Enrollee PIN method is only supported in

MT7687 and MT7697.

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page ii of iii

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

Table of Contents

1. Overview ............................................................................................................................................... 1

1.1. Supported features.............................................................................................................................1

1.2. Supported libraries .............................................................................................................................2

1.3. Software architecture of the Wi-Fi module........................................................................................2

2. Using the Module .................................................................................................................................. 4

2.1. Using the Wi-Fi module in STA mode .................................................................................................4

2.1.1. The AP router operates in open mode .............................................................................5

2.1.2. The AP router operates in WPA2PSK authentication mode .............................................6

2.1.3. The AP router operates in open WEP mode.....................................................................7

2.1.4. Two AP routers operate in WPA2PSK authentication mode ............................................8

2.1.5. Disable and enable auto connect option in STA mode.....................................................8

2.1.6. Wi-Fi connection support .................................................................................................9

2.2. Using the Wi-Fi module in AP mode.................................................................................................13

2.2.1. Use the device in AP open mode....................................................................................15

2.2.2. Use the device in AP mode with WPA2PSK method.......................................................16

2.2.3. Use the device in AP mode with open WEP method......................................................17

2.2.4. Wi-Fi connection support ...............................................................................................18

2.3. Using the Wi-Fi module in a repeater mode ....................................................................................19

2.3.1. Features in the repeater mode.......................................................................................19

2.3.2. Using the static method..................................................................................................20

2.3.3. Using the dynamic method.............................................................................................21

2.4. Scan ..................................................................................................................................................22

2.4.1. Scan APIs.........................................................................................................................23

2.5. Smart Connection .............................................................................................................................26

2.5.1. Smart Connection APIs ...................................................................................................26

2.5.2. How to use the Smart Connection API ...........................................................................27

2.6. Monitor mode and RX filter..............................................................................................................28

2.6.1. How to use the RX filter API............................................................................................28

2.6.2. How to receive raw packets............................................................................................29

2.7. WPS...................................................................................................................................................30

2.7.1. Using the APIs .................................................................................................................31

2.7.2. Wi-Fi WPS connection support.......................................................................................34

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page iii of iii

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

Lists of Tables and Figures

Table 1. Supported features of different chipsets ..................................................................................................1

Table 2. Libraries for the Wi-Fi mode configuration ...............................................................................................2

Table 3. Configuration functions.............................................................................................................................4

Table 4. The supported security modes..................................................................................................................6

Table 5. Wi-Fi events.............................................................................................................................................10

Table 6. Configuration and connection APIs in the AP mode ...............................................................................14

Table 7. The functions not supported in repeater mode......................................................................................20

Table 8. Scan mode ...............................................................................................................................................22

Table 9. Scan option..............................................................................................................................................22

Table 10. Channels supporting 2.4G .....................................................................................................................22

Table 11. Channels supporting 5G ........................................................................................................................22

Table 12. Scan APIs ...............................................................................................................................................23

Table 13. Smart Connection APIs ..........................................................................................................................27

Table 14. RX filter definitions................................................................................................................................28

Table 15. WPS APIs................................................................................................................................................31

Figure 1. Software architecture ..............................................................................................................................3

Figure 2. Repeater mode topology .......................................................................................................................19

Figure 3. Communicating with an IoT device using Smart Connection.................................................................26

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page 1 of 36

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

1. Overview

MediaTek MT7687, MT7697, MT7686, MT7682 and MT5932 chipsets are based on Wi-Fi System-on-Chip (SOC)

with embedded TCP/IP stack for Internet of Things (IoT) devices that can connect to other smart devices or to

cloud applications and services directly. MediaTek LinkIt™ software development kit (SDK) provides API and

example applications for the Wi-Fi module.

This document guides you through the following:

•Initializing the Wi-Fi module in Access Point (AP) and Station (STA) modes.

•Configuring the module to operate in STA mode or AP mode.

•Scanning for the available stations.

•Using smart connection and the RX filter.

1.1. Supported features

The Wi-Fi module on LinkIt for RTOS platform supports the following features and modes.

•STA Open or wired equivalent privacy (WEP)/Wi-Fi protected access (WPA)/WPA2 personal.

•STA Wi-Fi power save mode and delivery traffic indication message (DTIM) configuration. Power save

mode and DTIM are essential in Wi-Fi connectivity support.

•STA Wi-Fi Protected Setup (WPS), is a network security standard to create a secure wireless home

network.

•Wi-Fi aggregated MAC protocol data unit (A-MPDU) support.It enables to pack multiple MPDUs together

to reduce the overheads and average them over multiple frames, thereby increasing the data rate.

•SoftAP Open/WEP-Open/WPA/WPA2 personal, the authentication modes are the same as for STA mode.

•SoftAP WPS.

•High throughput for 20 MHz and 40 MHz bandwidths or both (HT40/HT20/Mix). This module sets the Wi-

Fi bandwidth.

•Repeater Mode.

Supported features for each chipset are listed in Table 1.

Table 1. Supported features of different chipsets

Features MT7687 MT7697 MT7686 MT7682 MT5932

STA Open/WEP-Open/WPA/WPA2 Y Y Y Y Y

STA Wi-Fi power saving mode Y Y Y Y Y

STA WPS Y Y Y Y N

Wi-Fi (A-MPDU) Y Y Y Y Y

SoftAP Open/WEP-Open/WPA/WPA2 Y Y Y Y Y

HT40/HT20/Mix Y Y Y Y Y

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page 2 of 36

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

Features MT7687 MT7697 MT7686 MT7682 MT5932

Repeater Mode Y Y Y Y N

1.2. Supported libraries

The SDK provides configurable libraries to use in your projects. Simply link the corresponding library to your

project described in Table 2.

Table 2. Libraries for the Wi-Fi mode configuration

Wi-Fi Mode Library

MT7687 MT7697 MT7686 MT7682 MT5932

Station

SoftAP

Repeater

WPS

libwifi.a

libminisupp.a

libwifi.a

libwifi_ram.a

1.3. Software architecture of the Wi-Fi module

There are three software layers: Driver, Middleware and Application, as shown in Figure 1. The Wi-Fi module

is located in Middleware. For more details, refer to LinkIt for RTOS get started guide.

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page 3 of 36

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

Figure 1. Software architecture

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page 4 of 36

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

2. Using the Module

The Wi-Fi module can only be applied once the settings are configured at system reboot. Apply your settings in the

wifi_init() API to initialize the driver in STA or AP mode. To configure the board as a repeater, see section 2.2,

“Using the Wi-Fi module in AP mode”.

Starting from the SDK v4, initialize the Wi-Fi settings by calling the wifi_init() function. The legacy Wi-Fi profile

API is disabled by default. To enable the legacy Wi-Fi profile API, define compile option

MTK_WIFI_PROFILE_ENABLE.

Most of the Wi-Fi APIs in wifi_api.h require FreeRTOS up and running. These APIs should be invoked in a task

triggered by vTaskStartScheduler(). The APIs in Table 3 are invoked in the main() function as an exception.

Table 3. Configuration functions

API

wifi_init() wifi_connection_register_event_handler()

wifi_config_get_mac_address () wifi_connection_unregister_event_handler ()

You can register an event handler to complete the initialization and call the Wi-Fi APIs, as shown in the example

code below.

/* Register wifi initialization event handler in main() function */

wifi_connection_register_event_handler(WIFI_EVENT_IOT_INIT_COMPLETE,

user_wifi_init_callback);

/* User-defined wifi initialization callback function */

bool g_wifi_init_ready = false;

void user_wifi_init_callback() { g_wifi_init_ready = true; }

void user_wifi_init_qurey_status(){

while(g_wifi_init_ready == false) {

vTaskDelay(20);

}

/* User-defined task */

user_task()

{

user_wifi_init_query_status();

/* Call APIs to connect only after Wi-Fi is initialized. */

wifi_config_set_ssid(WIFI_PORT_STA, "REMOTE_AP", sizeof("REMOTE_AP"));

wifi_config_set_wpa_psk_key(WIFI_PORT_STA, "12345678",

sizeof("12345678"));

wifi_config_reload_setting();

}

2.1. Using the Wi-Fi module in STA mode

In most cases, the configuration to initialize the Wi-Fi in STA mode takes effect immediately. However, some

settings can only take effect by calling the wifi_config_reload_setting() after calling the following APIs:

•wifi_config_set_pmk()

•wifi_config_set_security_mode()

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page 5 of 36

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

•wifi_config_set_ssid()

•wifi_config_set_wep_key()

•wifi_config_set_wpa_psk_key()

The configuration APIs use in-band mechanism for Wi-Fi driver and Wi-Fi firmware communication, thus these APIs

must be called after the OS task scheduler has started, to make sure an in-band task is running. The function

wifi_config_register_rx_handler() registers wifi_rx_handler() to manage the raw packets. There is

a limitation on calling this handler as it's using an in-band mechanism. It's restricted to call any in-band functions

like Wi-Fi configuration APIs or Wi-Fi connection APIs inside wifi_rx_handler().

Note 1. There is no need to configure the security mode in STA mode, as the security mode of the STA

can automatically match to the security mode of the AP.

Note 2. If AP’s security mode is unknown, call the wifi_config_set_wpa_psk_key() and

wifi_config_set_wep_key() APIs to set the password.

To use the module in a STA mode, apply any of the examples described below.

2.1.1. The AP router operates in open mode

1) In this example, the AP router operates in open mode with an SSID of "REMOTE_AP". Initialize the module

in STA mode, as shown below.

a) Define the operation mode (config.opmode) and the SSID (config.sta_config.ssid) in the

wifi_config_t structure.

wifi_config_t config = {0};

config.opmode = WIFI_MODE_STA_ONLY;

strcpy((char *)config.sta_config.ssid, "REMOTE_AP");

config.sta_config.ssid_length = strlen((char *)config.sta_config.ssid);

b) Call the wifi_init() function to initialize the Wi-Fi driver.

wifi_init(&config, NULL);

You’ve now successfully initialized the Wi-Fi module in STA mode.

2) To use configuration APIs in STA mode to connect to the AP router:

a) Call the wifi_config_set_opmode() function to set the opmode to WIFI_MODE_STA_ONLY.

wifi_config_set_opmode(WIFI_MODE_STA_ONLY);

b) Call the wifi_config_set_ssid() function to set the port to WIFI_PORT_STA and the SSID to

"REMOTE_AP".

wifi_config_set_ssid(WIFI_PORT_STA, "REMOTE_AP", strlen("REMOTE_AP"));

c) Apply the parameters by calling the wifi_config_reload_setting() function.

wifi_config_reload_setting();

You’ve successfully configured the Wi-Fi settings.

MediaTek LinkIt™ Development

Platform for RTOS Wi-Fi Developer's

Guide

Page 6 of 36

This document contains information that is proprietary to MediaTek Inc. (“MediaTek”) and/or its licensor(s).

Any unauthorized use, reproduction or disclosure of this document in whole or in part is strictly prohibited.

2.1.2. The AP router operates in WPA2PSK authentication mode

1) In this example, the AP router operates in WPA2PSK authentication mode with AES encryption type, the

password is "12345678" and the SSID of the AP router is "REMOTE_AP". Initialize the module in STA mode,

as shown below.

a) Define the operation mode (config.opmode), password (config.sta_config.password) and

the SSID (config.sta_config.ssid) in the wifi_config_t structure.

wifi_config_t config = {0};

config.opmode = WIFI_MODE_STA_ONLY;

strcpy((char *)config.sta_config.ssid, "REMOTE_AP");

config.sta_config.ssid_length = strlen((char *)config.sta_config.ssid);

strcpy((char *)config.sta_config.password, "12345678");

config.sta_config.password_length = strlen((char

*)config.sta_config.password);

b) Call the wifi_init() function to initialize the Wi-Fi driver.

wifi_init(&config, NULL);

The STA mode supports various types of security modes, as shown in Table 4. For more information about the

authentication mode and encryption group types, refer to wifi_auth_mode_t and wifi_encrypt_type_t

types in the Wi-Fi API reference guide.

Table 4. The supported security modes

Authentication mode Encryption type

WIFI_AUTH_MODE_OPEN WIFI_ENCRYPT_TYPE_WEP_ENABLED

WIFI_AUTH_MODE_WPA_PSK WIFI_ENCRYPT_TYPE_TKIP_ENABLED

WIFI_AUTH_MODE_WPA_PSK WIFI_ENCRYPT_TYPE_AES_ENABLED

WIFI_AUTH_MODE_WPA_PSK WIFI_ENCRYPT_TYPE_TKIP_AES_MIX

WIFI_AUTH_MODE_WPA2_PSK WIFI_ENCRYPT_TYPE_TKIP_ENABLED

WIFI_AUTH_MODE_WPA2_PSK WIFI_ENCRYPT_TYPE_AES_ENABLED

WIFI_AUTH_MODE_WPA2_PSK WIFI_ENCRYPT_TYPE_TKIP_AES_MIX

WIFI_AUTH_MODE_WPA_PSK_WPA2_PSK WIFI_ENCRYPT_TYPE_TKIP_ENABLED

WIFI_AUTH_MODE_WPA_PSK_WPA2_PSK WIFI_ENCRYPT_TYPE_AES_ENABLED

WIFI_AUTH_MODE_WPA_PSK_WPA2_PSK WIFI_ENCRYPT_TYPE_TKIP_AES_MIX

2) To use configuration APIs in STA mode to connect to the AP router:

a) Call the wifi_config_set_opmode() function to set the opmode to WIFI_MODE_STA_ONLY.

wifi_config_set_opmode(WIFI_MODE_STA_ONLY);

b) Call the wifi_config_set_ssid() function to set the port to WIFI_PORT_STA and the SSID to

"REMOTE_AP".

wifi_config_set_ssid(WIFI_PORT_STA, "REMOTE_AP", strlen("REMOTE_AP"));

c) Set the password to "12345678" by calling the wifi_config_set_wpa_psk_key() function.

wifi_config_set_wpa_psk_key(WIFI_PORT_STA, "12345678",

strlen("12345678"));

d) Apply the parameters by calling the wifi_config_reload_setting() function.

Table of contents

Popular Motherboard manuals by other brands

DFI

DFI SD170 user manual

ASROCK

ASROCK ROMED8-2T user manual

Asus

Asus P2L97A user manual

Winmate

Winmate IC70 user manual

Asus

Asus MES-B user manual

Grantech

Grantech SYS8F377VGGA-3OMN user manual

Telit Wireless Solutions

Telit Wireless Solutions SL869-3DR user guide

Gigabyte

Gigabyte GA-9IVDT user manual

Texas Instruments

Texas Instruments ADS8372EVM user guide

Commell

Commell MS-C73 user manual

IBT Technologies

IBT Technologies MB860 user manual

Nvidia

Nvidia TEGRA DG-04927-001_V01 user guide

Biostar

Biostar M7VIT Bravo Description

Intel

Intel D33217CK specification

Asus

Asus F1A55-M LX PLUS R2.0 user manual

EPC

EPC EPC9147C quick start guide

Asus

Asus EX-B760M-V5 D4 quick start guide

EPOX

EPOX MU-8KHA0010 user manual