MT2523 API Reference  LinkIt SDK v4
Introduction

Overview

MediaTek LinkIt™ Development Platform for RTOS provides a comprehensive software solution for devices based on the MediaTek MT2523x SOC, including the LinkIt™ 2523 hardware development kit (HDK). The platform supports hardware abstraction layers, peripheral drivers, FreeRTOS, Bluetooth / Bluetooth Low Energy (BT/BLE), Sensor subsystem and GNSS. This API reference describes the features of and how to use the APIs for each of the supported modules. Each module has a readme.txt under the module root directory. It contains the information about the module dependency, feature options, notes and brief introduction. Please refer to the readme.txt to learn the basic usage of the module.

Architecture

LinkIt™ SDK for RTOS consists of several software modules, as shown below:

MT2523_SDK_architecture.PNG

The architecture layers are described below.

  • BSP
    • Hardware drivers provide peripheral drivers for the development platform, such as ADC, I2S, I2C, SPI, RTC, GPIO, UART, Flash, Security Engine, TRNG, GDMA, PWM, WTD and IRDA TX/RX.
    • Hardware Abstraction Layer (HAL) provides driver Application Programming Interface (API) encapsulating the low-level functions of peripheral drivers for the operating system (OS), middleware features and applications.
    • FreeRTOS provides an OS with open source software for middleware and projects.
  • Middleware
    • ATCI provides the interface for target communication with command line tools operating through the UART.
    • BT/BLE provides protocol-layers, access features and profiles, such as Generic Access Profile (GAP), Serial Port Profile (SPP) and Generic Attribute Profile (GATT).
    • Battery management provides charging flow control mechanism and more precise battery information.
    • Sensor subsystem provides the sensor drivers and the latest libraries for fusion algorithms.
    • Firmware update Over-The-Air (FOTA) provides a mechanism to update the firmware.
    • GNSS provides APIs to control the GNSS APIs.
    • File system provides API to control data storage and and retrieval in a file system.
    • LZMA decoder provides functions to decompress the compressed data encoded by LZMA encoder.
    • Advanced features include Non-Volatile Random Access Memory (NVRAM), JavaScript Object Notation (JSON) and other features that are dependent on the HAL and the OS.
  • Example project
    • Pre-configured projects, using features of middleware and HAL.

Major Features

The SDK supports the following features when used with the LinkIt 2523 HDK or devices based on the MT2523x:

  • ATCI
    ATCI module provides the interface for target communication with command line tools operating through the UART. ATCI also provides functions to register the AT command handler, receive/send UART data and a parser to search the registered AT command handler. The command handler gets and parses all the input AT command data, then handles the corresponding action.
  • Battery management
    Battery management system is a battery monitor mechanism that controls the charging and discharging of rechargeable batteries and provides APIs to acquire battery information including capacity, temperature, charging current, cable status, etc.

  • Bluetooth/Bluetooth Low Energy
    Bluetooth/Bluetooth Low Energy contains two modules: Basic Rate / Enhanced Data Rate (BR/EDR) and Bluetooth Low Energy, released as a single library.

    BR/EDR module includes the following profiles: GAP, SPP, Hands Free Profile (HFP), Advanced Audio Distribution Profile (A2DP), Audio Video Remote Control Profile (AVRCP) and Phone Book Access Profile (PBAP).

    Bluetooth Low Energy module includes the following profiles: GAP, GATT and Security Manager (SM).

  • HAL
    HAL provides convenient and easy-to-use driver APIs encapsulating the low-level functionality of the peripheral drivers. These APIs can interact with the upper layers, such as the middleware and the OS. In addition, HAL also includes several system modules, such as cache, micro processor unit (MPU), flash, etc.
  • Sensor subsystem
    The sensor subsystem provides information on human activity statistics, gesture detection and pedestrian dead reckoning. The components included in the driver module are the physical sensor driver, fusion algorithm library and APIs for applications that require obtaining driver and algorithm data. The SDK enables to port third party sensor drivers. Different fusion algorithm libraries can also be plugged-in, instead of the source libraries provided by MediaTek.
  • FOTA
    FOTA enables updating the firmware of an IoT device using wireless communication, such as Bluetooth. It offers full and separate bin firmware update mechanisms. LinkIt SDK includes a demo reference design on how to push packages using Bluetooth communication.
  • GNSS
    GNSS is part of All-in-GNSS (Global Navigation Satellite System) offered by MediaTek. The GNSS module provides a unified method to interpret the received GNSS data based on the National Marine Electronics Association (NMEA) specification. It also enables sending commands to an on-board GNSS chip.
  • Other features
    The SDK provides utilities, such as XML supporting Entity, Index, Search and JSON supporting string parser.

Folder Structure

The folder structure of the LinkIt SDK is shown below:

SDK_folder_structure.PNG

The details of the folder contents:

  • doc
    • The platform related documentation, such as getting started and module development guides.
  • driver
    • board. Includes driver files associated with the board, such as capacitive touch panel and the LCD.
    • chip. Includes common drivers for the modules associated with the chip, such as UART and I2C.
    • CMSIS. Includes Cortex Microcontroller Software Interface Standard (CMSIS-CORE).
  • kernel
    • rtos. Includes third party open source FreeRTOS.
    • service. Includes system service, such as the system log and exception handler.
  • middleware
    • MTK
      • atci. Includes the interface for target communication with command line tools operating through the UART.
      • battery_management. Includes a battery monitor, charging flow control and battery capacity algorithms.
      • bluetooth. Includes Bluetooth/Bluetooth Low Energy stack and related profiles, such as GAP and GATT.
      • fota. Includes firmware update functionality.
      • gnss. Includes APIs to receive GNSS data and send commands to an on-board GNSS chip.
      • sensor_subsys. Includes sensor drivers and fusion algorithms.
    • third_party
      • fatfs. Includes generic FAT file system to control data storage and retrieval.
  • project
    • The SDK includes example projects with pre-configured module features.
  • tools
    • gcc. Includes GCC compiler.

Terms and acronyms

Terms Details
FOTA Firmware Over-The-Air (FOTA) is a Mobile Software Management technology in which the operating firmware of a mobile device is wirelessly upgraded and updated by its manufacturer. Please refer to FOTA in Techopedia.
GNSS Global navigation satellite system is a satellite navigation system with global coverage, such as GPS. .
HAL Hardware Abstraction Layer, to guarantee the uniform SDK API for the different hardware and the different chips.
A2DP Advanced Audio Distribution Profile (A2DP). This profile defines how multimedia audio can be streamed from one device to another over a Bluetooth connection (it is also called Bluetooth Audio Streaming), please refer to A2DP in Wikipedia.
AVRCP Audio/Video Remote Control Profile (AVRCP). This profile is designed to provide a standard interface to control TVs, Hi-fi equipment, etc. to allow a single remote control (or other device) to control all of the A/V equipment to which a user has access to. It may be used in concert with A2DP or VDP. It is commonly used in car navigation systems to control streaming Bluetooth audio. Please refer to AVRCP in Wkipedia.
HFP Hands-Free Profile (HFP). This is commonly used to allow car hands-free kits to communicate with mobile phones in the car. It commonly uses Synchronous Connection Oriented link (SCO) to carry a monaural audio channel with continuously variable slope delta modulation or pulse-code modulation, and with logarithmic a-law or ŠÌ-law quantization. Please refer to HFP in WikiPedia.
PBAP Phone Book Access Profile (PBAP). This is a profile that allows exchange of Phone Book Objects between devices. It is likely to be used between a car kit and a mobile phone to allow the car kit to display the name of the incoming caller or allow the car kit to download the phone book so the user can initiate a call from the car display. Please refer to PBAP in Wikipedia.
GAP Generic Access Profile (GAP), provides the basis for all other profiles. GAP defines how two Bluetooth units discover and establish a connection with each other. Please refer to GAP in Wikipedia.
SPP Serial Port Profile (SPP). This profile is based on ETSI 07.10 and the RFCOMM protocol. It emulates a serial cable to provide a simple substitute for existing RS-232, including the familiar control signals. Please refer to SPP in Wikipedia.
GATT Generic Attribute Profile (GATT), provides profile discovery and description services for Bluetooth Low Energy protocol. It defines how ATT attributes are grouped together into sets to form services. Please refer to GATT in Wikipedia.
SM The SMP (Security Manager Protocol) defines the procedures for pairing, authentication, and encryption between LE devices. Please refer to SM introduction in artechhouse.

License

Copyright Statement:

(C) 2005-2016 MediaTek Inc. All rights reserved.

This software/firmware and related documentation ("MediaTek Software") are protected under relevant copyright laws. The information contained herein is confidential and proprietary to MediaTek Inc. ("MediaTek") and/or its licensors. Without the prior written permission of MediaTek and/or its licensors, any reproduction, modification, use or disclosure of MediaTek Software, and information contained herein, in whole or in part, shall be strictly prohibited. You may only use, reproduce, modify, or distribute (as applicable) MediaTek Software if you have agreed to and been bound by the applicable license agreement with MediaTek ("License Agreement") and been granted explicit permission to do so within the License Agreement ("Permitted User"). If you are not a Permitted User, please cease any access or use of MediaTek Software immediately. BY OPENING THIS FILE, RECEIVER HEREBY UNEQUIVOCALLY ACKNOWLEDGES AND AGREES THAT MEDIATEK SOFTWARE RECEIVED FROM MEDIATEK AND/OR ITS REPRESENTATIVES ARE PROVIDED TO RECEIVER ON AN "AS-IS" BASIS ONLY. MEDIATEK EXPRESSLY DISCLAIMS ANY AND ALL WARRANTIES, EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE IMPLIED WARRANTIES OF MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE OR NONINFRINGEMENT. NEITHER DOES MEDIATEK PROVIDE ANY WARRANTY WHATSOEVER WITH RESPECT TO THE SOFTWARE OF ANY THIRD PARTY WHICH MAY BE USED BY, INCORPORATED IN, OR SUPPLIED WITH MEDIATEK SOFTWARE, AND RECEIVER AGREES TO LOOK ONLY TO SUCH THIRD PARTY FOR ANY WARRANTY CLAIM RELATING THERETO. RECEIVER EXPRESSLY ACKNOWLEDGES THAT IT IS RECEIVER'S SOLE RESPONSIBILITY TO OBTAIN FROM ANY THIRD PARTY ALL PROPER LICENSES CONTAINED IN MEDIATEK SOFTWARE. MEDIATEK SHALL ALSO NOT BE RESPONSIBLE FOR ANY MEDIATEK SOFTWARE RELEASES MADE TO RECEIVER'S SPECIFICATION OR TO CONFORM TO A PARTICULAR STANDARD OR OPEN FORUM. RECEIVER'S SOLE AND EXCLUSIVE REMEDY AND MEDIATEK'S ENTIRE AND CUMULATIVE LIABILITY WITH RESPECT TO MEDIATEK SOFTWARE RELEASED HEREUNDER WILL BE, AT MEDIATEK'S OPTION, TO REVISE OR REPLACE MEDIATEK SOFTWARE AT ISSUE, OR REFUND ANY SOFTWARE LICENSE FEES OR SERVICE CHARGE PAID BY RECEIVER TO MEDIATEK FOR SUCH MEDIATEK SOFTWARE AT ISSUE.