Page 2
MediaTek LinkIt™ Connect 7681 Developer's Guide Document Revision History Revision Date Description January 2015 Initial release January 2015 Update to code in 2.4.1, “Code your firmware” Correction to path names in 3.1, “make” Typo in FOTA FW description Appendix A January 2016 Updated instructions in 2.2.1, “Installing Cygwin”...
Join Our Ecosystem ............................5 Getting started .............................. 6 2.1. Environment ................................ 6 2.2. Installing MediaTek LinkIt Connect 7681 SDK for Windows ............7 2.3. Installing MediaTek LinkIt Connect 7681 SDK for Linux ..............15 2.4. Your First Project ............................. 15 Tools guide ..............................
Page 4
Figure 15 Click Finish to complete the installation ....................13 Figure 16 Compiling the MT7681 firmware on Linux....................17 Figure 17 Connect the LinkIt Connect 7681 development board to a USB cable ........18 Figure 18 The connected COM port identified in Device Manager ..............18 Figure 19 Example of the source files folder structure on Windows ..............
MediaTek LinkIt™ Connect 7681 Developer's Guide Introduction There is an increasing trend towards connecting every imaginable electrical or electronic device found in the home. For many of these applications developers simply want to add the ability to remotely control a device — turn on a table lamp, adjust the temperature setting of an air- conditioner or unlock a door.
MediaTek website. The MediaTek LinkIt Connect 7681 SDK, based on the Andes Development Kit, enables you to create firmware to control an IoT device in response to instructions received wirelessly over a WiFi connection. The key features of the MediaTek LinkIt Connect 7681 SDK are: •...
MediaTek LinkIt™ Connect 7681 Developer's Guide • example source code : IoT Server, AT Command Parser, Data Command Parser and X- Modem • versions available for Microsoft Windows (requires Cygwin) and Ubuntu Linux 1.3.1. Software Architecture The software architecture of the MT7681 provides for access to its hardware features through four APIs —...
GPIO pins and one UART port — each with an LED — of the MT7681, to quickly connect peripheral controllers and electronic circuits. The MT7681 is provided on the LinkIt Connect 7681 module, which was co-designed with AcSiP. This module, which is only 15 x 18mm, will also be available separately for direct integration into your product’s PCB.
MediaTek LinkIt™ Connect 7681 Developer's Guide The key specifications of the LinkIt Connect 7681 development board are shown in Table 4. Category Feature Spec PCB Size 50 x 31 mm Power USB 5V Input (micro USB) Pin Count GPIO Pins Voltage 3.3v...
2.1.1. Microsoft Windows To run MediaTek LinkIt Connect 7681 SDK for Windows the Cygwin environment is needed. Cygwin is a large collection of GNU and Open Source tools that provide functionality similar to a Linux distribution on Microsoft Windows. Cygwin is available for all recent, commercially released x86 32-bit and 64-bit versions of Windows, starting with Windows XP SP3.
MediaTek LinkIt™ Connect 7681 Developer's Guide 2.2. Installing MediaTek LinkIt Connect 7681 SDK for Windows 2.2.1. Installing Cygwin Download the appropriate Cygwin installation package to match your Windows environment from Cygwin website: namely setup-x86.exe for 32-bit machines or setup-x86-64.exe for 64-bit machines.
MediaTek LinkIt™ Connect 7681 Developer's Guide In the Select Root Install Directory screen, see Figure 5, click Next to accept the default setting. Figure 5 Accept the default installation settings In the Select Local Package Directory screen, see Figure 6, click Next to accept the default location.
MediaTek LinkIt™ Connect 7681 Developer's Guide In the Select Your Internet Connection screen, see Figure 7, define your proxy if you use one otherwise use Direct Connection and click Next. Figure 7 Use the direct connection unless you access the Internet using a proxy In the Choose A Download Site screen, see Figure 8, select a mirror site: for the best download speed select a site that you think is nearby.
MediaTek LinkIt™ Connect 7681 Developer's Guide The installer now downloads details and displays progress in the Progress screen, see Figure 9. Figure 9 The installer downloads information about Cygwin In the Select Package screen, select the make and gcc-core packages from the Devel category leaving other items at their default settings.
MediaTek LinkIt™ Connect 7681 Developer's Guide Click Next. The Resolving Dependencies screen, see Figure 12, displays showing details of any dependent packages for your selection, click Next. Figure 12 Details of any dependent packages are shown The Progress screen, see Figure 13, shows the progress of the download and installation of your selected components.
Figure 15 Click Finish to complete the installation Cygwin is now installed. You can now continue to install the MediaTek LinkIt Connect 7681 SDK. Adding the cygwin\bin and cygwin\lib folders to the system path is recommended. To do this, at the Windows command prompt (cmd) execute path %path%;C:\cygwin\bin;C:\cygwin\lib.
Page 19
MediaTek LinkIt™ Connect 7681 Developer's Guide 2.2.2. Installing the MediaTek LinkIt Connect 7681 SDK for Windows Download the MediaTek LinkIt Connect 7681 SDK for Windows from the MediaTek Labs website and extract its content to a suitable drive. Locate the tool chain file Andes_Windows_Toolchains.rar in the ToolChain folder, and extract its contents (folder nds32le-elf-newlib-v2j) to C:\cygwin, the root folder of the Cygwin installation.
Page 21
2.4.2. Compiling the application This section describes how to compile the iot_customer.c file into Wi-Fi station mode firmware for the LinkIt Connect 7681 development board. 2.4.2.1. Source Code Compilation on Windows In File Explorer open C:\Cygwin and double-click cygwin-andes.bat to start the Cygwin shell.
Uploading the firmware from Windows To upload the firmware from a Windows PC: connect the LinkIt Connect 7681 development board to your computer using a USB cable, as shown in Figure 17. Figure 17 Connect the LinkIt Connect 7681 development board to a USB cable 2) identify the COM port on which the development board is connected, by opening Device Manager from Control Panel, see Figure 18.
Page 25
For more details on using mt7681_uploader.py see section 3.2, ‘Firmware uploader’. 2.4.4. Run the application on the LinkIt Connect 7681 development board The LinkIt Connect 7681 development board will automatically reboot once the update process finishes successfully. You’ll see the LED2 (mapped to GPIO2) start to blink every second. 2.4.5.
MediaTek LinkIt™ Connect 7681 Developer's Guide Tools guide This section provides details on the use of the tools included in the MediaTek LinkIt Connect 7681 SDK. 3.1. make make provides for building a collection of source code files into firmware for MT7681. The utility provides for four types of builds: •...
MediaTek LinkIt™ Connect 7681 Developer's Guide Uploader works as follows: sends an AT#Reboot to reboot MT7681 and place it in recovery mode. 2) sends AT#UpdateFW. 3) sends the specified firmware over the X-modem protocol to MT7681. 4) once the firmware transmission is complete, MT7681 will reboot itself automatically to run the new firmware.
4.1. Creating software projects The coding style of MediaTek LinkIt Connect 7681 SDK is to modify existing source files stored in *:\LinkIt_Connect_7681_SDK\Src\ to create custom firmware. Therefore when you want to create a new software project, you simply take a copy of the Src folder and make the necessary modifications to file in the copy.
MediaTek LinkIt™ Connect 7681 Developer's Guide 4.2.1. Root Folder The files stored in the root folder of a firmware source project are shown in Table 7 File Purpose Makefile MT7681 Makefile libandesrecovery. Binary library for recovery mode libandessta.a Binary library for station mode libandesap.a Binary library for AP mode header.sh...
MediaTek LinkIt™ Connect 7681 Developer's Guide 4.3. Firmware boot up flow When source code is compiled the compiler generates MT7681_all.bin. — the software for MT7681. This software consists of four images that provide features related to Loader, Recover/Calibration, Station, and AP as described in Table 10. Function Image name Purpose...
MediaTek LinkIt™ Connect 7681 Developer's Guide PC) can connect to it, and it can create TCP/UDP connection with other devices in the LAN or WLAN Figure 20 The boot sequence of MT7681 4.3.2. UART log at Boot up stage During the boot sequence a log is written to UART, this is an example of the log for Station mode: ==>...
MediaTek LinkIt™ Connect 7681 Developer's Guide While this is an example of the log for AP mode: ==> Recovery Mode /*start to running recovery/Calibration image*/ <== Recovery Mode /* end to running recovery/Calibration image*/ /*start to running AP image*/ load_ap_cfg store_ap_cfg ===>...
MediaTek LinkIt™ Connect 7681 Developer's Guide 4.4.2. Callback flowchart The flowchart in Figure 21 shows the event timing and triggers for MT7681 callbacks. Figure 21 The flow of callback function in MT7681 4.4.3. iot_cust_preinit () iot_cust_preinit() is called once at system start-up. Code should NOT do anything related to UART or GPIO here, because they are not initialized at this stage.
Page 36
MediaTek LinkIt™ Connect 7681 Developer's Guide This code will result in the message “Hello world” being output from UART when MT7681 starts up, as follows: ==> Recovery Mode <== RecoveryMode SM=0, Sub=0 Hello world [WTask]5001 [WTask]10001 4.4.5. iot_cust_subtask1() iot_cust_subtask1() is called as a sub-task of wifiTASK_LowPrioTask(), which in turn executes approximately once every 1ms or less, but this will depend on how long this callback takes to execute.
MediaTek LinkIt™ Connect 7681 Developer's Guide 4.5. Wi-Fi State Machine (Station mode) When MT7681 is in Station mode it provides a Wi-Fi state machine for the Wi-Fi connection. The entry function for this state machine is wifi_state_machine(). 4.5.1. States There are in total 7 states, as shown in Figure 22: •...
Page 38
MediaTek LinkIt™ Connect 7681 Developer's Guide • WIFI_STATE_ASSOC MT7681 sends a Management frame (Assoc Request) to AP and waits for a response: if the Assoc Response is received with the status code =0 (Assoc successful), then: if AuthMode is 0 (Open mode), MT7681 goes to WIFI_STATE_CONNED. ...
Page 40
PWM frequency of 50Hz, there are 20 duty cycle options: 0% to 100% in 5% increments. • the frequency and duty cycle are defined by setting PWM_HIGHEST_LEVEL in the source file. Please refer to PWM section in the MediaTek LinkIt Connect 7681 API Reference more detail. 4.6.4. Timer MT7681 has 2 hardware timers.
MediaTek LinkIt™ Connect 7681 Developer's Guide 4.6.5. TCP/IP Stack MT7681 uses uIP (micro IP), which is an open source TCP/IP stack used in many embedded systems. It supports TCP, UDP, DNS, DHCP, and HTTP client. The maximum number of TCP/UDP connection supported by MT7681 is 4. The maximum TCP/UDP packet length is 600 Bytes.
MediaTek LinkIt™ Connect 7681 Developer's Guide The return values from the API are listed in Table 12. Returned value Meaning Success Other Error (reserved for future use). Table 12 Return value of StartSmartConnection API 4.7.1.2. StopSmartConnection This API stops the Wi-Fi broadcast of the Smart Connection packet. The syntax of this API are as follows: int StopSmartConnection(void);...
Page 43
MediaTek LinkIt™ Connect 7681 Developer's Guide When the user taps Start, the app runs to JNI_StartSmartConnection() that calls StartSmartConnection to begin broadcasting. The code for this is shown below: File: IoTManage_jni.cpp static jint JNI_StartSmartConnection(JNIEnv *env, jobject thiz, jstring nSSID, jstring nPassword, jbyte nAuth) int iRst = 0;...
Page 45
MediaTek LinkIt™ Connect 7681 Developer's Guide 4.7.2. Smart Connection API for iOS A similar interface to that provided for Android is offered for iOS. Compared to coding a Smart Connection app for Android, iOS requires an additional step Init before Start, as shown below: #ifndef _SMTIOT_H_ #define _SMTIOT_H_ int InitSmartConnection(void);...
MediaTek LinkIt™ Connect 7681 Developer's Guide Using the APIs This section provides information on how to use the MT7681 APIs. For details of the API please refer to the MediaTek LinkIt Connect 7681 API Reference. The topics covered in this section include: •...
Page 47
MediaTek LinkIt™ Connect 7681 Developer's Guide 3) IoT_Cust_SM_Smnt() is located in cust\Iot_custom.c. Modify the default value of SSID and Passphrase variables to match AP you wish to connect to, as follows: void IoT_Cust_SM_Smnt(void) /* Example for customer's smart connection implementation*/ /* Step1: create parameter to store the smnt information */ /* or it is better to create a structure*/...
MediaTek LinkIt™ Connect 7681 Developer's Guide 5.2. Configuring MT7681 as an AP This section describes how to code MT7681 so that it acts as an AP and lets other devices (such as mobile phones) connect to it and retrieve data. The steps to achieve this are as follows: Set the default configuration of MT7681 to AP mode.
MediaTek LinkIt™ Connect 7681 Developer's Guide This is the UART log for MT7681 AP mode after boot up: ==> Recovery Mode /*start to running recovery/Calibration image*/ <== Recovery Mode /*end to running recovery/Calibration image*/ /*start to running AP image*/ load_ap_cfg store_ap_cfg ===>...
Page 50
MediaTek LinkIt™ Connect 7681 Developer's Guide 5.3.1. Creating a TCP client that connects to a remote TCP server This section describes how to create a TCP client, connect to a remote TCP server and exchange data with that remote server. Initialize the connection Use uip_connect() to create the connection.
Page 51
MediaTek LinkIt™ Connect 7681 Developer's Guide 2) Exchange data with Remote Server uIP calls iot_tcp_appcall() whenever an event occurs, so this is where you write the code to handle events. First check to see if this event is related to the connection defined above, by checking whether the local port matches the one defined.
Page 52
MediaTek LinkIt™ Connect 7681 Developer's Guide The shell window at the remote server will start displaying “hello” periodically. You can also type characters back, these should be output on UART of MT7681. 5.3.2. Create a TCP server and allow others to connect This section describes how to create a TCP server, listen to a port and exchange data with a connection to that port.
Page 53
MediaTek LinkIt™ Connect 7681 Developer's Guide 2) Exchange data with TCP Client The logic and source code in iot_tcp_appcall is the same as used in section5.3.1. It prints out whenever data are received and sends back “hello” once every 5 seconds: File: iot_tcp_app.c void app_handle_connection(void)
Page 54
MediaTek LinkIt™ Connect 7681 Developer's Guide 5.3.3. Increasing available TCP/UDP connections The maximum number of connections that can be made at the same time is defined, as shown below, in uip-confg.h. While it isn’t recommended, the number of connections can be increased, however, be aware that doing so will use more memory and may cause run-time problems.
The most likely issues are that: • the toolchain is setup incorrectly. Refer to section 2.2, “Installing MediaTek LinkIt Connect 7681 SDK for Windows” or section 2.3, “Installing MediaTek LinkIt Connect 7681 SDK for Linux” as appropriate and confirm the setup is correct. •...
In these cases, use the reset switch to put the LinkIt Connect 7681 development board into recovery mode, as shown in Figure 25. The board should restart and run the firmware as expected.
MediaTek LinkIt™ Connect 7681 Developer's Guide Figure 25 The reset switch on the LinkIt Connect 7681 development board 6.3. Use Log to debug MT7681 provides features for outputting debug messages to a log on UART. To enable this feature, set PRINT_FLAG in iot_custom.c to TRUE as follows: bool PRINT_FLAG = TRUE;...
Page 58
MediaTek LinkIt™ Connect 7681 Developer's Guide However, if there are issues with the connection they may be identified as follows: • if the state switches from SM=1, Sub=0 to SM=0, Sub=0 Smart Connection has failed, possibly because the user did not click the button that fires start API: SartSmartConnection in the Android app.
Page 59
MediaTek LinkIt™ Connect 7681 Developer's Guide 6.3.2. Using log to debug in AP mode If MT7681 is in AP mode with PRINT_FLAG=TRUE the following is a typical debug log: ==> Recovery Mode /*start to running recovery/Calibration image*/ <== Recovery Mode /* end to running recovery/Calibration image*/ /* start to running station image*/ load_ap_cfg...
Page 60
MediaTek LinkIt™ Connect 7681 Developer's Guide If MT7681 is set to open mode (no WEP/WPA in use), PMK Update… and the log related to 4 way handshake should not be listed. You can check the AP setting from AP SETTING: SSID[****], AuthMode[*], WepStatus[*], Channel[*].
Page 61
MediaTek LinkIt™ Connect 7681 Developer's Guide The meaning of AuthMode and WepStatus can be found in iot_api.h as follows: File: iot_api.h typedef enum _NDIS_802_11_WEP_STATUS Ndis802_11WEPEnabled, Ndis802_11Encryption1Enabled = Ndis802_11WEPEnabled, Ndis802_11WEPDisabled, Ndis802_11EncryptionDisabled = Ndis802_11WEPDisabled, Ndis802_11WEPKeyAbsent, Ndis802_11Encryption1KeyAbsent = Ndis802_11WEPKeyAbsent, Ndis802_11WEPNotSupported, Ndis802_11EncryptionNotSupported = Ndis802_11WEPNotSupported, Ndis802_11Encryption2Enabled, /* TKIP mode*/ Ndis802_11Encryption2KeyAbsent,...
MediaTek LinkIt™ Connect 7681 Developer's Guide 6.4. Unresponsive board If your LinkIt Connect 7681 development board becomes unresponsive: 1) attempt to reboot the board using either AT#Reboot or the hardware reset button (see Figure 25). 2) reload the recovery firmware using the uploader.
MediaTek LinkIt™ Connect 7681 Developer's Guide Appendix A Flash Layout MT7681 firmware and configuration data are stored in external Flash. There are two types of Flash layout used: • Flash layout with XIP region size of 60KB. • Flash layout with XIP region size of 164KB. It’s acceptable to use external serial Flash of 512KB, but 1MB is recommended.
Page 64
MediaTek LinkIt™ Connect 7681 Developer's Guide The Flash layout setting is managed in the header file src\include\flash_map as follow: #if (FLASH_XIP_164_SUPPORT == 1) /************************************************************************** Flash Mapping **************************************************************************/ #define FLASH_OFFSET_BASE (0x0000) #define FLASH_OFFSET_LOADER_START (0x0000) //20KB #define FLASH_OFFSET_RESERVE_1_START (0x5000) //4KB #define FLASH_OFFSET_UPG_FW_START (0x6000) //64KB (RecoveryFW)
Page 65
MediaTek LinkIt™ Connect 7681 Developer's Guide Setting the specific Flash layout for XIP region (60KB or 164KB) is done in the Makefile, as follows: # After changing FLASH_XIP_164, # It is must compile all Firmwares (Recovery, STA, AP) # Then upgrade loader, recovery, ap, sta firmwares in order by uart, # or upgrade MT7681_all.bin / MT7681_all_xip164.bin by Flash writer FLASH_XIP_164 ifeq...
MediaTek LinkIt™ Connect 7681 Developer's Guide The layout for the Common Config region in Flash is shown in Table 16. These items are: • loaded when MT7681 calls load_com_cfg(). • reset by calling reset_com_cfg(). Offset Section Size (Byte) Offset 0x18000 Common Info Stored Flag 0x18001 Boot Firmware Index:...
MediaTek LinkIt™ Connect 7681 Developer's Guide The Station Mode Config region in Flash is shown in Table 17. These items are: • loaded when MT7681 calls load_sta_cfg(). • reset by calling reset_sta_cfg(). • stored from RAM by calling store_sta_cfg(). Offset Section Size (Byte)
MediaTek LinkIt™ Connect 7681 Developer's Guide The layout for the AP Mode Config region in Flash is shown in Table 18. These items are: • loaded when MT7861 calls load_ap_cfg(). • reset by calling reset_ap_cfg(). • stored from RAM by calling store_ap_cfg(). Offset Section Size...