WE865-DUAL SW User Guide 1vv0300788 Rev.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Disclaimer The information contained in this document is the proprietary information of Telit Communications S.p.A. and its affiliates (“TELIT”). The contents are confidential and any disclosure to persons other than the officers, employees, agents or subcontractors of the owner or licensee of this document, without the prior written consent of Telit, is strictly prohibited.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Applicable Products Product Part Number WE865-DUAL 3990400528 Reproduction forbidden without Telit Communications S.p.A.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Contents 1 Introduction ...................................................................................................................................... 6 1.1 Scope ........................................................................................................................................................6 1.2 Audience ...............................................................................................................
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 7 8 6.3 ifrename .................................................................................................................................................35 6.4 iwevent ...................................................................................................................................................37 6.5 iwgetid ...........................................................................................................
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 1 Introduction 1.1 Scope This user guide serves the following purpose: Describes WE865-DUAL software architecture Describes how software developers can use the functions of the WiFi software package to configure and manage the WE865-DUAL wireless interface 1.2 Audience This User Guide is intended for software developers who develop applications on the GE863-PRO³ module for configuring and managing WE865-DUAL wireless module. 1.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Wireless Tools project site: http://www.hpl.hp.com/personal/Jean_Tourrilhes/Linux/Tools.html 1.4.2 Wpa Supplicant WPA Supplicant is free software; it can be redistributed and/or modified under the terms of the GNU General Public License version 2 as published by the Free Software Foundation. For further information about GNU License please have a look at http://www.gnu.org/copyleft/gpl.html.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 1.5 Product Overview The WE865-DUAL is a dual-mode Wi-Fi short range wireless companion product to the GE863-PRO³ device family. Based on the processing power of dual 60MHz RISC processor cores, the WE865DUAL is a versatile and powerful addition to any GE863-PRO³-based design instantly adding the power of Wi-Fi communications and the versatility of the SDIO interface. 1.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 1.7 Text Conventions This section lists the paragraph and font styles used for the various types of information presented in this user guide. Format Content Courier Linux shell commands at command prompt. 1.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 2 WE865-DUAL architecture 2.1 Hardware WE865-DUAL WiFi module is connected and communicates with GE863-PRO³ through an SDIO interface. For further hardware information please refer to [1] , [2] , [5] and [6] 2.2 Software Studying Linux Operating System and Linux WiFi Software Framework is important to better understand how WE865-DUAL can be configured and controlled.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Two regions can be identified: 1) User space: where the user applications are executed. 2) Kernel space: where the kernel (with all its components such as device drivers) works.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 2.2.2 Linux WiFi software framework WE865-DUAL Linux WiFi package is made up of different components: WiFi Driver – WE865-DUAL Linux WiFi device driver Wireless Tools – Set of tools for configuring and managing WE865-DUAL Wpa Supplicant – Tool for configuring and managing WPA/WPA2 security WE865-DUAL WiFi module is controlled, under Linux OS, by the means of a WiFi device driver loaded into Kernel Space.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Reproduction forbidden without Telit Communications S.p.A.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 3 Connecting WE865-DUAL to PRO3 Prior to any use WE865-DUAL interface board must be correctly connected to GE863-PRO3 as shown below. Please Note: to disable WE865-DUAL internal voltage regulators PL101 and PL102 jumpers must be closed (see [6] for further information). Reproduction forbidden without Telit Communications S.p.A.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 4 Configuring WE865-DUAL In order to better understand how to configure WE865-DUAL wifi module it is very important to read the introduction in typical wireless networks configurations and devices involved. 4.1 Typical IEEE 802.11 network scenario A typical wireless network is mainly made up of clients and Access Points (AP). Clients (such as PCs, PDAs, laptops, VOIP phones, etc.) connect to an AP.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 When clients connect to each other through an AP, as shown above, they operate in Managed/Infrastructure mode. Another WiFi network topology that allows clients to directly connect to each other without APs forming a peer-to-peer link is called Ad-Hoc. 4.2 WE865-DUAL Setup 4.2.1 WiFi Package Downloading Before setting up WE865-DUAL, the components of the WiFi Package must be downloaded onto GE863-PRO³ filesystem.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Start Colinux and make sure the Ethernet on USB connection via USB port is correctly configured as shown in [4] . Now start Eclipse and download the following files onto GE863-PRO³ filesystem as shown in [4] : WiFi Driver: - loader.xbv - sta.xbv - ufmib.dat - unifi_manager - unifi_sdio.ko - unififw Wireless Tools: - iwconfig - iwlist - ifrename - iwevent - iwgetid - libiw.so.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Now create the /lib/firmware/ and /lib/firmware/unifi-sdio-0/ folders: # mkdir /lib/firmware/ # mkdir /lib/firmware/unifi-sdio-0 Now move the downloaded files from the download folder to the right destination folder. Supposing you are into the download folder, type: For WiFi driver: # mv unifi_sdio.ko /lib/ # mv *.xbv ufmib.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Once the wifi driver has been successfully loaded the eth0 network interface is available. 4.2.3 Configuring the WiFi Network Interface An IP address can now be assigned to the eth0 wifi network interface. For example, to assign the IP address 192.168.1.12 to the device, with a netmask 255.255.255.0, type: # ifconfig eth0 192.168.1.12 netmask 255.255.255.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Once the eth0 network interface has been activated it is possible, for example, to perform a scanning of wifi networks as shown below: # iwlist eth0 scan Reproduction forbidden without Telit Communications S.p.A.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Then it is also possible to associate with a specific SSID: # iwconfig eth0 essid "test" Reproduction forbidden without Telit Communications S.p.A.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 For further information about wifi specific parameters configuration and WE865-DUAL management please refer to paragraphs 5, 6 and 7. 4.2.4 Auto-Setup at system startup It is possible to automatically perform all the steps shown above at system startup. A startup script as the one shown below has to be written: insmod /lib/unifi_sdio.ko sleep 15 ifconfig eth0 192.168.1.12 netmask 255.255.255.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 5 Commands summary All the specific wifi parameters for WE865-DUAL can be configured and controlled through Wireless Tools and Wpa Supplicant. Wireless Tools (iwconfig, iwlist, ifrename, iwevent and iwgetid) and WPA Supplicant, simple linux shell commands, can be used for example to perform scanning and association to a wireless network and/or to set the desired operating mode and to manage WPA security modes and related settings.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 5.1 Wireless Tools examples Some examples on how to use Wireless Tools from system calls: system(“iwconfig eth0 essid \"My Network\””); system(“iwconfig eth0 mode Ad-Hoc”); system(“iwconfig eth0 channel 3”); system(“iwconfig eth0 rate 11M”); 5.2 WiFi Security examples Some examples on how to use wpa_supplicant and wpa_cli from system calls: system(“wpa_supplicant –Dunifi -ieth0 -c/etc/wpa_supplicant.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 6 Wireless Tools Linux Wireless Tools (WT) is a set of tools allowing to configure and manage WE865-DUAL by linux command shell. Wireless Tools package includes the following executables: iwconfig manipulates the basic wireless parameters iwlist allows to initiate scanning and list frequencies, bit-rates, encryption keys...
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Parameters essid Set the ESSID (or Network Name - in some products it may also be called Domain ID). The ESSID is used to identify cells which are part of the same virtual network. As opposed to the AP Address or NWID which define a single cell, the ESSID defines a group of cells connected via repeaters or infrastructure, where the user may roam transparently.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 o o Monitor (the node is not associated with any cell and passively monitor all packets on the frequency) Auto. Examples: iwconfig eth0 mode Managed iwconfig eth0 mode Ad-Hoc freq/channel Set the operating frequency or channel in the device. A value below 1000 indicates a channel number, a value greater than 1000 is a frequency in Hz. You may append the suffix k, M or G to the value (for example, "2.46G" for 2.46 GHz frequency), or add enough '0'.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 You may append the suffix k, M or G to the value (decimal multiplier: 10^3, 10^6 and 10^9 b/s), or add enough '0'. Values below 1000 are card specific, usually an index in the bit-rate list. Use auto to select automatic bit-rate mode (fallback to lower rate on noisy channels), which is the default for most cards, and fixed to revert back to fixed setting.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 iwconfig eth0 sens 2 retry Most cards have MAC retransmissions, and some allow setting the behaviour of the retry mechanism. To set the maximum number of retries, enter limit `value'. This is an absolute value (without unit). To set the maximum length of time the MAC should retry, enter lifetime `value'. By defaults, this value in seconds, append the suffix m or u to specify values in milliseconds or microseconds.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 To set the current encryption key, just enter the key in hex digits as XXXX-XXXX-XXXXXXXX or XXXXXXXX. To set a key other than the current key, prepend or append [index] to the key itself (this won't change which is the active key). You can also enter the key as an ASCII string by using the s: prefix. Passphrase is currently not supported. To change which key is the currently active key just enter [index] (without entering any key value).
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 commit Some cards may not apply changes done through Wireless Extensions immediately (they may wait to aggregate the changes or apply it only when the card is brought up via ifconfig). This command (when available) forces the card to apply all pending changes. This is normally not needed, because the card will eventually apply the changes, but can be useful for debugging.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Noise level Background noise level (when no packet is transmitted). Similar comments as for Signal level. Rx invalid nwid Number of packets received with a different NWID or ESSID. Used to detect configuration, problems or adjacent network existence (on the same frequency). Rx invalid crypt Number of packets that the hardware was not able to decrypt. This can be used to detect invalid encryption settings.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 6.2 iwlist iwlist is used to display some additional information from a wireless network interface that is not displayed by iwconfig. The main argument is used to select a category of information, iwlist displays in detailed form all information related to this category, including information already shown by iwconfig.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 txpower List the various Transmit Powers available on the device. retry List the transmit retry limits and retry lifetime on the device. ap/accesspoint/peers Give the list of Access Points in range, and optionally the quality of link to them. This feature is obsolete and now deprecated in favour of scanning support (above), and most drivers don't support it.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 6.3 ifrename ifrename is a tool allowing you to assign a consistent name to each of your network interface. By default, interface names are dynamic, and each network interface is assigned the first available name (eth0, eth1...). The order network interfaces are created may vary. For built-in interfaces, the kernel boot time enumeration may vary. For removable interface, the user may plug them in any order.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 When used with -i, specify the new name of the interface. The list of mappings from the configuration file is bypassed, the interface specified with -i is renamed directly to newname. The new name may be a wildcard containing a single '*'. When used without -i, rename interfaces by using only mappings that would rename them to newname. The new name may not be a wildcard. This use of ifrename is discouraged, because inefficient (-n without -i).
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 6.4 iwevent iwevent displays Wireless Events received through the RTNetlink socket. Each line displays the specific Wireless Event which describes what has happened on the specified wireless interface. This command doesn't take any arguments. Synopsis iwevent Display There are two classes of Wireless Events.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Event specific to the driver. Please check the driver documentation. Registered node The interface has successfully registered a new wireless client/peer. Will be generated mostly when the interface acts as an Access Point (mode Master). Expired node The registration of the client/peer on this interface has expired. Will be generated mostly when the interface acts as an Access Point (mode Master).
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 6.5 iwgetid iwgetid is used to find out the NWID, ESSID or AP/Cell Address of the wireless network that is currently used. The information reported is the same as the one shown by iwconfig, but iwgetid is easier to integrate in various scripts. By default, iwgetid will print the ESSID of the device, and if the device doesn't have any ESSID it will print its NWID. The default formatting output is pretty-print.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Display the protocol name of the interface. This allows identifying all the cards that are compatible with each other and accept the same type of configuration. This can also be used to check Wireless Extension support on the interface, as this is the only attribute that all drivers supporting Wireless Extension are mandated to support. Reproduction forbidden without Telit Communications S.p.A.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 7 WPA/WPA2 Security wpa_supplicant is a user space program used to set and manage wireless connections secured through WPA/WPA2 both Personal and Enterprise. All the parameters used to secure the wifi connection can be set into /etc/wpa_supplicant.conf configuration file. wpa_supplicant can be simply run through a command shell.
WE865-DUAL Software User Guide 1vv0300788 Rev.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 7.2 Running wpa_supplicant wpa_supplicant can be run simply typing: # wpa_supplicant –Dunifi -ieth0 -c/etc/wpa_supplicant.conf –d 7.3 wpa_cli wpa_cli is a tool that can be used to control the operations of the wpa_supplicant and to get status information and event notifications. Synopsis: wpa_cli [-p] [-i] [-hvB] [-a] [-P] [-g] [command..
WE865-DUAL Software User Guide 1vv0300788 Rev.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 8 Appendix 8.1 WPA/WPA2 (IEEE 802.11i) Wi-Fi Protected Access (WPA and WPA2) is a class of systems to secure Wi-Fi networks. It was created in response to several serious weaknesses researchers had found in the previous system, Wired Equivalent Privacy (WEP). WPA implements the majority of the IEEE 802.11i standard, and was intended as an intermediate measure to take the place of WEP while 802.11i was prepared.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 Following steps are used when associating with an AP using WPA: • • • • • • • • • 8.2.1 wpa_supplicant requests the kernel driver to scan neighbouring BSSes wpa_supplicant selects a BSS based on its configuration wpa_supplicant requests the kernel driver to associate with the chosen BSS if WPA-EAP: integrated IEEE 802.
WE865-DUAL Software User Guide 1vv0300788 Rev. 0 08/08/08 • • • • • • • EAP-AKA EAP-PSK EAP-FAST EAP-PAX EAP-SAKE EAP-IKEv2 EAP-GPSK (experimental) 8.2.
WE865-DUAL Software User Guide 1vv0300788 Rev.