Telit Wireless Solutions GS2K User Manual

GS2K Wi-Fi Network Interface Card
(NIC) User Guide
1VV0301491 Rev 2.0 2018-02-13
GS2K Wi-Fi Network Interface Card (NIC) User Guide
TELIT MAY MAKE CHANGES TO SPECIFICATIONS AND PRODUCT DESCRIPTIONS AT ANY TIME, WITHOUT NOTICE.
NOTICES
LIMITATION OF LIABILITY
While reasonable efforts have been made to assure the accuracy of this document, Telit assumes no liability resulting from any inaccuracies or omissions in this document, or from use of the information obtained herein. The information in this document has been carefully checked and is believed to be reliable. However, no responsibility is assumed for inaccuracies or omissions. Telit reserves the right to make changes to any products described herein and reserves the right to revise this document and to make changes from time to time in the content hereof with no obligation to notify any person of revisions or changes. Telit does not assume any liability arising out of the application or use of any product, software, or circuit described herein; neither does it convey license under its patent rights or the rights of others.
It is possible that this publication may contain references to, or information about Telit products (machines and programs), programming, or services that are not announced in your country. Such references or information must not be construed to mean that Telit intends to announce such Telit products, programming, or services in your country.
Telit assumes no liability whatsoever, and disclaims any express or implied warranty, relating to sale and/or use of Telit products including liability or warranties relating to fitness for a particular purpose, merchantability, or infringement of any patent, copyright or other intellectual property right. Telit products are not authorized for use as critical components in medical, lifesaving, or life-sustaining applications.
COPYRIGHT
This Telit manual a nd c ont e nts are owned by Telit and/or its licensors and protected by U.S. and international copyright laws, conventions, and treaties. Your right to use this manual is subject to limitations and restrictions imposed by applicable licenses and copyright laws. Unauthorized reproduction, modification, distribution, display or other use of this manual may result in criminal and civil penalties.
This instruction manual and the Telit products described in this instruction manual may be, include or describe copyrighted Telit material, such as computer programs stored in semiconductor memories or other media. Laws in Italy and other countries preserve for Telit and its licensors certain exclusive rights to copyright material, including the exclusive right to copy, reproduce in any form, distribute and make derivative works of the copyrighted material. Accordingly, any copyrighted material of Telit and its licensors contained herein or in the Telit products described in this instruction manual may not be copied, reproduced, distributed, merged or modified in any manner without the express written permission of Telit. Furthermore, the purchase of Telit products shall not be deemed to grant either directly or by implication, estoppel, or otherwise, any license under the copyrights, patents or patent applications of Telit, as arises by operation of law in the sale of a product.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
USAGE AND DISCLOSURE RESTRICTIONS
I. License Agreements
The software described in this document is the property of Telit and its licensors. It is furnished by express license agreement only and may be used only in accordance with the terms of such an agreement.
II. Copyrighted Materials
Software and documentation are copyrighted materials. Making unauthorized copies is prohibited by law. No part of the software or documentation may be reproduced, transmitted, transcribed, stored in a retrieval system, or translated into any language or computer language, in any form or by any means, without prior written permission of Telit.
III. High Risk Materials
Components, units, or third-party products used in the product described herein are NOT fault-tolerant and are NOT designed, manufactured, or intended for use as on-line control equipment in the following hazardous environments requiring fail-safe controls: the operation of Nuclear Facilities, Aircraft Navigation or Aircraft Communication Systems, Air Traffic Control, Life Support, or Weapons Systems (High Risk Activities). Telit and its supplier(s) specifically disclaim any expressed or implied warranty of fitness for such High-Risk Activities.
IV. Trademarks
Telit, Telit and stylized Logos are registered Trademarks. All other product or service names are the property of their respective owners.
V. Third Party Rights
The software may include Third Party Right software. In this case, you agree to comply with all terms and conditions imposed on you in respect of such separate software. In addition to Third Party Terms, the disclaimer of warranty and limitation of liability provisions in this License shall apply to the Third Party Right software.
TELIT HEREBY DISCLAIMS ANY AND ALL WARRANTIES, EXPRESS OR IMPLIED FROM ANY THIRD PARTIES REGARDING ANY SEPARATE FILES, ANY THIRD PARTY MATERIALS INCLUDED IN THE SOFTWARE, ANY THIRD PARTY
MATERIALS FROM WHICH THE SOFTWARE IS DERIVED (COLLECTIVELY “OTHER CODE”), AND THE USE OF ANY OR ALL THE OTHER CODE IN CONNECTION WITH
THE SOFTWARE, INCLUDING (WITHOUT LIMITATION) ANY WARRANTIES OF SATISFACTORY QUALITY OR FITNESS FOR A PARTICULAR PURPOSE.
NO THIRD PARTY LICENSORS OF OTHER CODE SHALL HAVE ANY LIABILITY FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING WITHOUT LIMITATION LOST PROFITS), HOWEVER CAUSED AND WHETHER MADE UNDER CONTRACT, TORT OR OTHER LEGAL THEORY, ARISING IN ANY WAY OUT OF THE USE OR DISTRIBUTION OF THE OTHER CODE OR THE EXERCISE OF ANY RIGHTS GRANTED UNDER EITHER OR BOTH THIS LICENSE AND THE LEGAL TERMS APPLICABLE TO ANY SEPARATE FILES, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGES.
www.Telit.com
GS2K Wi-Fi Network Interface Card (NIC) User Guide
CONTENTS
NOTICES…………. ........................................................................................... 2
LIMITATION OF LIABILITY ............................................................................. 2
COPYRIGHT ..................................................................................................... 2
USAGE AND DISCLOSURE RESTRICTIONS ................................................ 3
CONTENTS ...................................................................................................... 4
1. INTRODUCTION ............................................................................ 7
1.1. Scope ............................................................................................. 7
1.2. Audience ........................................................................................ 7
1.3. Contact Information and Support ................................................... 7
1.4. Text Convention ............................................................................. 7
1.5. Related Documents ........................................................................ 8
2. HARDWARE AND SOFTWARE COMPONENTS ......................... 9
2.1. Hardware Components .................................................................. 9
2.1.1. Linux Host ...................................................................................... 9
2.1.2. GS2K Modules ............................................................................. 10
2.1.3. SDIO Interconnect ........................................................................ 10
2.2. Software Components .................................................................. 10
2.2.1. Linux Application .......................................................................... 10
2.2.1.1. WPA Supplicant ............................................................................ 10
2.2.1.2. Hostapd ........................................................................................ 11
2.2.1.3. WPA CLI ....................................................................................... 11
2.2.1.4. Hostapd CLI .................................................................................. 11
2.2.1.5. UserApp ........................................................................................ 11
2.2.2. Telit Wi-Fi NIC Applications .......................................................... 11
2.2.2.1. OTHFU Application ...................................................................... 11
2.2.2.2. RF Test Tool ................................................................................. 11
2.2.3. Linux Kernel ................................................................................. 11
2.2.4. GS2K Wi-Fi Driver ........................................................................ 11
2.2.5. GS2K Firmware ............................................................................ 11
2.3. Software Package ........................................................................ 12
3. REFERENCE PLATFORM .......................................................... 13
3.1. X86 PC Host Platform .................................................................. 13
GS2K Wi-Fi Network Interface Card (NIC) User Guide
3.2. Arm Cortex A9 Embedded Platform ............................................. 13
3.3. GS2K SDIO Wi-Fi Adapter Board(WAB) ...................................... 13
4. BUILDING AND LOADING THE SOFTWARE ............................ 15
4.1. GS2K Linux Package ................................................................... 15
4.2. X86 PC Platform ........................................................................... 15
4.2.1. Building the Kernel and Loading the Host .................................... 15
4.2.2. Building the Driver ........................................................................ 15
4.2.3. Preparing the Test Setup ............................................................. 15
4.2.4. Load and Run the Driver .............................................................. 15
4.3. ARM Cortex A9 Embedded Platform ............................................ 15
4.3.1. Building the kernel and Driver, loading the Host .......................... 15
4.3.2. Preparing the Test Setup ............................................................. 16
4.3.3. Loading and Running the Driver ................................................... 16
5. WIRELESS NETWORK OPERATIONS ...................................... 17
5.1. Steps to load the GS2K Wi-Fi module during boot time: .............. 17
5.2. GS2K WLAN interface details ...................................................... 17
5.3. STA Mode .................................................................................... 17
5.4. AP Mode ....................................................................................... 19
5.5. Throughput measurement ............................................................ 22
5.5.1. UDP throughput Test procedure in station mode ......................... 22
5.5.2. TCP throughput Test procedure in station mode .......................... 23
6. OVER THE HOST FIRMWARE UPDATE .................................... 24
6.1. GS2K OTHFU Application ............................................................ 24
6.2. Compiling and building the application ......................................... 25
6.3. Build requirements: ...................................................................... 25
6.4. Typical command sequence for OTHFU ...................................... 25
7. RF TEST COMMANDS ................................................................ 26
7.1. GS2K RF Test Application............................................................ 26
7.2. Compiling and building the application ......................................... 27
7.3. Build requirements ....................................................................... 27
7.4. Typical command sequence for RF TEST.................................... 27
APPENDIX A: DOWNLOADING, BUILDING AND INSTALLING LINUX KERNEL ON
X86 UBUNTU ................................................................................................. 29
A.1 Get the source code ..................................................................... 29
A.2 Building the kernel ........................................................................ 33
A.3 Installing and booting the kernel ................................................... 33
GS2K Wi-Fi Network Interface Card (NIC) User Guide
APPENDIX B: BUILDING AND INSTALLING LINUX KERNEL AND DRIVER ON NXP I
MX6 EMBEDDED HOST ................................................................................ 34
B.1 Bringing up the NXP IMX6 EVK Board: ........................................ 34
B.2 Setting up the SD card ................................................................. 36
APPENDIX C: RF TEST COMMAND AND ARGUMENT DESCRIPTION ..... 38
C.1 Regulatory and Transmit Tests using RF Test Commands .......... 38
C.1.1 Regulatory Testing ....................................................................... 38
C.1.2 Transmit Testing ........................................................................... 38
C.1.3 Gain Control Table ....................................................................... 38
C.1.4. Start RF Test ................................................................................ 38
C.1.5. Stop RF Test ................................................................................ 38
C.1.6. Asynchronous Frame Transmission ............................................. 38
C.1.7 Start Asynchronous Frame Reception .......................................... 41
C.1.8 Stop Asynchronous Frame Reception .......................................... 43
C.1.9 Asynchronous Frame Transmission (TX99 mode) ....................... 44
C.1.10. Asynchronous Frame Transmission (TX100 mode) ..................... 49
APPENDIX D: PROGRAMMING SETUP - GAINSPAN WAB BOARD ......... 52
DOCUMENT HISTORY .................................................................................. 53
GS2K Wi-Fi Network Interface Card (NIC) User Guide
1. INTRODUCTION
1.1.
Scope
This user guide provides information required to install and evaluate Telit Wi-Fi NIC driver for Linux hosts with GS2K modules. It also provides guidelines for using firmware update and RF test commands.
1.2. Audience
This document is intended for Telit customers, who are integrators and about to implement their applications using Telit Wi-Fi NIC module.
1.3. Contact Information and Support
For general contact, technical support services, technical questions and report documentation errors contact Telit Technical Support at:
TS-SRD@telit.com
Alternatively, use:
http://www.telit.com/support
For detailed information about where you can buy the Telit modules or for recommendations on accessories and components visit:
http://www.telit.com
Our aim is to make this guide as helpful as possible. Keep us informed of your comments and suggestions for improvements.
Telit appreciates feedback from the users of our information.
1.4. Text Convention
Danger – This information MUST be followed or catastrophic equipment failure or bodily injury may occur.
Caution or Warning – Alerts the user to important points about integrating the module, if these points are not followed, the module and end user equipment may fail or malfunction.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
Tip or Information – Provides advice and suggestions that may be useful when integrating the module.
All dates are in ISO 8601 format, i.e. YYYY-MM-DD.
1.5. Related Documents
Please refer to http://www.telit.com/gnss/ for current documentation and downloads.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
2. HARDWARE AND SOFTWARE COMPONENTS
This chapter describes the components and procedures for building a wireless application with Linux host and Telit Wi-Fi NIC module.
The GS2K chipset implements 802.11 b/g/n MAC+PHY functionality. It integrates complete MAC, PHY and RF functionality on a single chip providing a low cost and easy­to-use solution for adding wireless connectivity to applications.
GS2K based modules (GS2200M and GS2101M) integrate GS2K chipset and required components like crystals, regulators, RF front end components to provide ready-to-use WLAN radio modules that can be used as NIC cards to provide network connectivity to hosts. These modules are regulatory, certified and calibrated for easy integration and build applications instantly without requiring any work on radio connectivity modules.
GS2K based modules provides host interface over SDIO, SPI and UART for connecting a variety of hosts. The SDIO interface provides high speed interconnection for bigger host systems that are based on processors with 32-bit CPU and MMU which run on Linux operating systems. The Linux host implements the GS2K drivers, the network stack, the supplicant and authenticator 802.11 security and the applications. It also communicates with GS2K modules over SDIO.GS2K modules implements commands and functionality to support Linux network API.
Standard Linux applications like wpa_supplicant and hostapd are used for control path and standard Linux data path is used for data communications requiring no custom software. Custom applications are used only for device firmware update and RF test as they are not part of standard Linux offerings.
NOTE:
SPI, UART interface currently not supported.
2.1. Hardware Components
The following diagram illustrates the hardware components:
The description to the hardware components are as follows:
2.1.1. Linux Host
The Linux host can be any processor system that can run standard Linux software. It can be a high end X86 PC or an embedded platform like i.MX6SLL. The host processor is selected by customer.
Linux Host
(e.g., X86 PC, i.MX6SLL)
GS2K Module
(GS2200MIZ, GS2101MIP, etc)
SDIO interconnect
GS2K Wi-Fi Network Interface Card (NIC) User Guide
2.1.2. GS2K Modules
GS2K modules acts as NIC card, it is based on GS2K chipset and supports all GS2K modules.
2.1.3. SDIO Interconnect
The SDIO interconnect provides connectivity between the host and GS2K processor.
2.2. Software Components
The following diagram illustrates the software components being used. Telit Wi-Fi NIC host software is provided along with the package – which is required to be installed in a directory and built (discussed in the coming chapters).
2.2.1. Linux Application
Standard Linux applications are used for network connection setup and management. Following are the standard Linux application:
2.2.1.1. WPA Supplicant
wpa_supplicant” is a WPA supplicant for Linux, BSD, Mac OS X, and Windows with WPA and WPA2 (IEEE 802.11i / RSN) support. It is suitable for both desktop/laptop computers and embedded systems. Supplicant is IEEE 802.1X/WPA component that is used in the client stations. It implements key negotiation with a WPA Authenticator, controls the roaming and IEEE 802.11 authentication/association of WLAN driver.
Sockets Data i/f
NL80211 Ctl i/f
Wpa_cli
hostapd_cli
OTHFU App
RF Test App
User App
Wpa_supplicant
Hostapd
User Space
Kernel Space
CFG80211
NW Stack
GS2K Wi-Fi SDIO Driver
Linux Host
GS2K Module
GS2K
SDIO i/f
= Telit Wi-Fi NIC Software
= User Software
= Standard Linux Sw
GS2K Wi-Fi Network Interface Card (NIC) User Guide
2.2.1.2. Hostapd
hostapd is a user space daemon for access point and authentication servers. It implements IEEE 802.11 access point management, IEEE 802.1X/WPA/WPA2/EAP Authenticators, RADIUS client, EAP server, and RADIUS authentication server.
2.2.1.3. WPA CLI
wpa_cli is a text-based frontend program interacting with wpa_supplicant. It is used to get the current status, change configuration, trigger events, and request interactive user input.
2.2.1.4. Hostapd CLI
hostapd_cli utility is a text-based frontend program for interacting with hostapd.
2.2.1.5. UserApp
“UserApp” makes use of networking services to setup socket connections and perform data transfer.
2.2.2. Telit Wi-Fi NIC Applications
2.2.2.1. OTHFU Application
OTHFU application provides over-the-host firmware update facility for GS2K firmware. Applications. GS2K firmware is updated using this application. (Refer Chapter - 6 Over
the Host Firmware Update).
2.2.2.2. RF Test Tool
RF test tool application provides commands for testing and evaluating GS2K radio. It provides commands for frame transmission and reception (Refer Chapter – 7 RF Test
commands”).
2.2.3. Linux Kernel
Standard Linux kernel is used without any customizations.
2.2.4. GS2K Wi-Fi Driver
GS2K Wi-Fi driver is a kernel module provided by Telit. This module implements driver for interfacing Linux kernel network control and data path to GS2K Wi-Fi device. It interprets commands and messages between Linux kernel and GS2K. It also performs queuing and flow control.
It contains SDIO driver adaptation layer for communication between Linux kernel and GS2K SDIO device over SDIO interconnect. It implements probe, interrupt handling and buffer management.
2.2.5. GS2K Firmware
GS2K firmware is loaded on GS2K module. It is programmed and run on GS2K providing IEEE 802.11 Full MAC functionality. It handles scan, association and data transfer functionality and implements MAC features like rate adaptation, client power­save, AP mode inactivity tracking, AP mode power save buffering, etc. It also provides firmware update and RF test functionality, and is considered as a single binary image that is loaded into GS2K module flash.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
2.3. Software Package
Telit Wi-Fi NIC software package gs2k_wifi_nic.tar.gz consists of Telit Wi-Fi NIC software components and few tools.
Following are the software package contents:
1. fw – gs2k fw single image binary
2. drv - contains driver files and make file
3. apps a. othfu – contains othfu app source files and makefile b. rftest – contains rftest app source files and makefile
4. wpa_supplicant – contains sample configuration files
5. hostapd – contains sample configuration files
6. tools – contains gs_flashprogrammer and any other tools if required.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
3. REFERENCE PLATFORM
This chapter describes the reference platform used to demonstrate the solution, the setup and applications used.
The Linux solution is demonstrated using a reference platform setup. Two Linux host platforms are used, one PC host and the other is embedded host. The GS2K target board is same in both cases and is described as follows:
3.1. X86 PC Host Platform
Lenovo Thinkpad T440p laptop is used for X86 PC host running Ubuntu 16.4 and Linux Kernel version 4.9.11. This machine has a SD card slot to plug the GS2K target board for testing.
3.2. Arm Cortex A9 Embedded Platform
i.MX6SLL application processor is a single Arm® Cortex®-A9, which operates at speed upto 800 MHz. Products based on the i.MX6SLL application processors enables cost effective, rapid development of multimedia applications for Android® and Linux® operating systems. This board has a SD card slot to plug GS2K target board for testing.
3.3. GS2K SDIO Wi-Fi Adapter Board(WAB)
GS2K SDIO Wi-Fi Adapter Board (WAB) is a GS2101MIP module based hardware adapter board that is interfaced using the SDIO interface of a Linux host processor.
The following diagram shows the i.MX6SLL board and GS2K SDIO WAB.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
GS2K SDIO WAB is plugged into SD card slot on laptop for testing.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
4. BUILDING AND LOADING THE SOFTWARE
This chapter provides the steps for building GS2K Linux drivers, loading and running them on a reference platform.
4.1. GS2K Linux Package
This step is common for all Linux host platforms.
1. Create a folder called “telit”.
mkdir ~/telit
2. Copy gs2k_wifi_nic.tar.gz package into this directory.
3. Unzip the package using following command.
tar xvf gs2k_wifi_nic.tar.gz
4.2. X86 PC Platform
Following are the steps for building, loading and running GS2K Linux drivers on X86 host reference platform.
4.2.1. Building the Kernel and Loading the Host
On X86 platform, the host and development system are the same and hence it is not required to setup a cross-compilation environment. Ubuntu 16.4 with Linux kernel version 4.9.11 is required on X86 PC.
Check the Linux Kernel version by issuing the command “uname -r”. If Linux kernel version is already installed - then just build the driver, install and test it with instructions in following sections. If the Linux kernel version is not installed – then download, build and install the kernel on Ubuntu (Refer - Appendix A: Downloading, Building and
Installing Linux Kernel on x86 Ubuntu).
4.2.2. Building the Driver
1. Go to ~/telit/gs2k_wifi_nic/drv
2. Build the driver
4.2.3. Preparing the Test Setup
Program GS2K WAB with GS2K firmware provided in ‘fw’ folder of the package using the flash programmer tool.
Refer Appendix D: Programming Setup - GainSpan WAB Board for preparing the test setup and for programming steps using flash programmer refer GS2K Module
Programming User Guide”.
4.2.4. Load and Run the Driver
Follow the procedures mentioned in Chapter: 5 Wireless Network Operations” to load and setup wireless connection and perform data transfer.
4.3. ARM Cortex A9 Embedded Platform
Following are the steps for building, loading and running GS2K Linux drivers for ARM Cortex A9 host reference platform:
4.3.1. Building the kernel and Driver, loading the Host
The GS2K driver is tested with Linux kernel version 4.9.11. If the complete setup for i.MX6SLL board including cross-compile environment, building the bootloader, kernel and root filesystem and loading them on host board already exists then - simply include the driver in the build procedure and follow the procedures mentioned in Chapter - 5
GS2K Wi-Fi Network Interface Card (NIC) User Guide
Wireless Network Operations” to install and test. If the complete setup is not present
then – follow the procedures mentioned in “Appendix B: Building and Installing Linux Kernel and Driver on NXP i MX6 Embedded Hostto download, build and install the kernel, root filesystem and GS2K driver.
4.3.2. Preparing the Test Setup
Program GS2K WAB with GS2K firmware provided in ‘fw’ folder of the package using the flash programmer tool.
Refer “Appendix D: Programming Setup - GainSpan WAB Boardfor preparing the test
setup and for programming steps using flash programmer refer “GS2K Module Programming User Guide”.
4.3.3. Loading and Running the Driver
Follow the procedures mentioned in Chapter - 5 Wireless Network Operations to load and setup wireless connection and perform data transfer.
GS2K Wi-Fi Network Interface Card (NIC) User Guide
5. WIRELESS NETWORK OPERATIONS
This chapter provides step by step procedure to setup wireless network connectivity and perform data transfer.
Prepare the system (refer Chapter – 4 Building and loading the software”) before configuring the WLAN interface.
Following are the steps to connect to the wireless network and test data transfer, once the WLAN interface is configured:
NOTE:
Configuration instructions are only for reference and contain typical example. For more details refer – Linux documentation.
5.1. Steps to load the GS2K Wi-Fi module during boot time:
Compile GS2K module (refer: - 4.2.2Building the Driver) and place the module file
gs2k_sdio.ko in /lib/modules/$(uname -r)/kernel/drivers/net
Open the file /etc/modules and write gs2k_sdio in it.
Run the command depmod -a
And run the command sudo update-initramfs -u
Once the above commands are successfully executed the at every restart the
GS2K Wi-Fi module will be automatically loaded.
Run command lsmod | grep” for gs2k to check whether gs2k_sdio” is currently
loaded.
5.2. GS2K WLAN interface details
The following command is used to find the physical device corresponding to GS2K WLAN interface:
iw dev
The following command is used to check the features and commands supported by all devices:
iw phy
5.3. STA Mode
Following are the steps to configure and test wireless interface in station mode:
1. Configure DHCP
a) Open configuration file and make sure DHCP is enabled.
>vi /etc/network/interfaces
File should contain below two lines:
auto wlan0
iface wlan0 inet dhcp
b) Restart networking
Loading...
+ 37 hidden pages