TI-Android-JB-PortingGuide

This page is currently under construction. The content of this page is due to change quite frequently and thus the quality and accuracy are not guaranteed until this message has been removed. Please feel free to contribute to this page while construction is in progress.

About this manual

The goal of Porting Guide is to provide valuable information and instructions to people who want to run Android OS on their (new) HW. Information covered here will mainly be useful to port TI Android JB DevKit on Sitara-based devices.

Note: Detailed porting information in the different technical areas is dependent on the respective h/w architecture. The information provided here generally refers to the AM335x devices. Information specific to AM37x shall be provided if necessary.

Base Port

The Android Board-specific configuration files are present in device/ti/<boardname>. e.g for am335xevm, the files are at <android sources root>/device/ti/am335xevm.

The Jelly Bean release uses board-specific init file instead of the unified init.rc used in previous releases. The board name is determined by the android property ro.hardware which is the machine name set in the board file in the kernel. So the init file for am335xevm becomes init.am335xevm.rc.

Display

Introduction

This section of the porting guide describes the display system with respect to TI Android JB DevKit. AM335x EVM, AM335x Starter Kit, BeagleBone with LCD cape, AM37x EVM and Flashboard use LCD interface for display while BeagleBoard uses DVI output.

Depending on the display size, android uses either the phone layout (e.g. AM37xevm, AM335xevm) or tablet layout (Beagleboard).

Features Overview

• Supports LCD display interface on AM335x EVM, AM335x Starter Kit, AM37xevm, Flashboard and BeagleBone with LCD cape
• Supports DVI output on Beagleboard, AM37xevm, Flashboard and BeagleBone with DVI-D cape

Android Display Subsystem Overview

TBD

Driver Configuration

• Refer AM335x LCD Controller Driver's Guide for AM335x
• Refer PSP 04.02.00.07 Display Driver Guide for AM37x

Display backlight

Introduction

This section explains how the LCD backlight control is implemented in the DevKit. For variable backlight intensity, PWM-controlled backlight is generally used.

Driver Configuration

TBD

Android Configuration

For integration with the Android Backlight settings configuration, the liblights HAL needs to be implemented for the board. The output HAL library should have the name lights.<TARGET_PRODUCT>.so. E.g. for AM335x EVM, the liblights HAL is called lights.am335xevm.so.

The liblights backlight HAL for AM335x EVM is implemented at device/ti/am335xevm/liblights.

Touchscreen

Introduction

The touchscreen is the primary input device for TI Android DevKit on AM335xevm, EVM-SK, BeagleBone LCD7/LCD3 cape, AM37xevm and Flashboard.

Features Overview

The features supported by Touchscreen in Android are:

• Single touch input
• Single click
• Single long click
• Uni-direction motion touch

Driver Configuration

Add touchscreen driver support

• AM335x evm: Refer AM335x Touchscreen Driver's Guide for details
• AM37x : TBD

Test touch driver using getevent

• Once ADC Touchscreen driver is up through board file (e.g. board-am335xevm.c) configuration.
• Test with AndroidFS as events are coming while touching the LCD display. Run on command prompt:

    # getevent
    add device 1: /dev/input/event1
      name:     "ti-tsc-adcc"

    /dev/input/event1: 0003 0000 00000659
    /dev/input/event1: 0003 0001 00000a31
    /dev/input/event1: 0001 014a 00000001
    /dev/input/event1: 0000 0000 00000000
    /dev/input/event1: 0003 0000 00000654
    /dev/input/event1: 0000 0000 00000000
    

• It confirms that touch inputs and irq based event generation is working fine.

Touch Calibration

The platform data for TSC driver for AM335x contains the following fields to provide calibration data:

static struct tsc_data am335xevm_touchscreen_data = {
...
        .x = {
                .min = 0xCB,
                .max = 0xF9B,
                .inverted = 1,
        },
        .y = {
                .min = 0xC8,
                .max = 0xE93,
                .inverted = 1,
        },
...

X-axis is from left to right and Y-axis from top to bottom.

min and max values are the actual touch data obtained at the extreme corners of the LCD screen. You can obtain the raw value returned by the touchscreen at the corners using the getevent utility in Android. Use the values for ABS_X and ABS_Y

root@android:/ # getevent -tl /dev/input/event3                                
[    2331.426687] EV_ABS       ABS_X                00000ea7            
[    2331.426687] EV_ABS       ABS_Y                00000819            
[    2331.426718] EV_ABS       ABS_PRESSURE         000000b8            
[    2331.426718] EV_KEY       BTN_TOUCH            DOWN                
[    2331.426718] EV_SYN       SYN_REPORT           00000000

Test Touch Calibration in Android

• Run android on the board.
• select "Menu" -> "Dev Tools" -> "Pointer Location" utility
• Touch and draw on the screen and observe that the expected points are getting marked on the LCD screen.
• if drawing on LCD is not proper then driver needs to be fine tune the above mentioned macros.

Android Touchscreen configuration

TBD

See also :http://source.android.com/tech/input/touch-devices.html

In the TI Android DevKit, touchscreen is set as the default input device. commit

Keypad

Introduction

The matrix gpio keypad and Volume gpio keys are in AM335x EVM. Here porting explanation for matrix gpio keypad controller.

Features Overview

• 3x2 matrix key layout supported
• single click input

Driver Configuration

Add keypad driver support

• start the Linux Kernel Configuration tool:

    $ make ARCH=arm menuconfig

• Select Device Drivers from the main menu.

    ...
    Power management options --->
    [*] Networking support --->
    '''Device Drivers --->'''
    File systems --->
    Kernel hacking --->
    ...

• Select Input device support form the next menu:

    ...
    [ ] ISDN support  --->
    < > Telephony support  --->
    '''Input device support  --->'''
    Character devices  --->
    -*- I2C support  --->
    ...

• Select Keyboards from the next menu:

    ...
    < >   Reset key
          *** Input Device Drivers ***
    '''[*]   Keyboards  --->'''
    [ ]   Mice  --->
    [ ]   Joysticks/Gamepads  --->
....

• Select GPIO driven matrix keypad support and GPIO Buttons from the next menu:

    ....
 < >   DECstation/VAXstation LK201/LK401 keyboard
 <*>   GPIO Buttons
 < >   Polled GPIO buttons
 < >   TCA6416/TCA6408A Keypad Support
 <*>   GPIO driven matrix keypad support
 < >   Maxim MAX7359 Key Switch Controller
....

Board-specific Configuration The board-specific configuration includes, specifying the GPIOs, no. of rows and columns, debounce, scan settings etc. The following code snippet shows the configuration for AM335x EVM (arch/arm/mach-omap2/board-am335xevm.c).

static const uint32_t am335x_evm_matrix_keys[] = {
        KEY(0, 0, KEY_MENU),
        KEY(1, 0, KEY_BACK),
        KEY(2, 0, KEY_LEFT),

        KEY(0, 1, KEY_RIGHT),
        KEY(1, 1, KEY_ENTER),
        KEY(2, 1, KEY_DOWN),
};

const struct matrix_keymap_data am335x_evm_keymap_data = {
        .keymap      = am335x_evm_matrix_keys,
        .keymap_size = ARRAY_SIZE(am335x_evm_matrix_keys),
};

static const unsigned int am335x_evm_keypad_row_gpios[] = {
        GPIO_TO_PIN(1, 25), GPIO_TO_PIN(1, 26), GPIO_TO_PIN(1, 27)
};

static const unsigned int am335x_evm_keypad_col_gpios[] = {
        GPIO_TO_PIN(1, 21), GPIO_TO_PIN(1, 22)
};

static struct matrix_keypad_platform_data am335x_evm_keypad_platform_data = {
        .keymap_data       = &am335x_evm_keymap_data,
        .row_gpios         = am335x_evm_keypad_row_gpios,
        .num_row_gpios     = ARRAY_SIZE(am335x_evm_keypad_row_gpios),
        .col_gpios         = am335x_evm_keypad_col_gpios,
        .num_col_gpios     = ARRAY_SIZE(am335x_evm_keypad_col_gpios),
        .active_low        = false,
        .debounce_ms       = 5,
        .col_scan_delay_us = 2,
};

...

static struct gpio_keys_button am335x_evm_volume_gpio_buttons[] = {
        {
                .code                   = KEY_VOLUMEUP,
                .gpio                   = GPIO_TO_PIN(0, 2),
                .active_low             = true,
                .desc                   = "volume-up",
                .type                   = EV_KEY,
                .wakeup                 = 1,
        },
        {
                .code                   = KEY_VOLUMEDOWN,
                .gpio                   = GPIO_TO_PIN(0, 3),
                .active_low             = true,
                .desc                   = "volume-down",
                .type                   = EV_KEY,
                .wakeup                 = 1,
        },
};

static struct gpio_keys_platform_data am335x_evm_volume_gpio_key_info = {
        .buttons        = am335x_evm_volume_gpio_buttons,
        .nbuttons       = ARRAY_SIZE(am335x_evm_volume_gpio_buttons),
};

Test keypad driver using getevent

• Once matrix gpio keypad and volume gpio keys driver is up through board file (e.g. board-am335xevm.c) configuration.
• Test with AndroidFS as events are coming while pressing the keys. Run on command prompt:

    # getevent
    add device 1: /dev/input/event2
            name: "gpio-keys"
    add device 2: /dev/input/event0
            name: "matrix-keypad"

    /dev/input/event0: 0004 0004 00000002
    /dev/input/event0: 0001 009e 00000001
    /dev/input/event0: 0000 0000 00000000
    /dev/input/event0: 0004 0004 00000002
    /dev/input/event0: 0001 009e 00000000
    /dev/input/event0: 0000 0000 00000000
    

• It confirms that keypad inputs and irq based event generation is working fine.

Android Keypad Configuration

• Android requires Key layout files (.kl files) for mapping Linux key codes and axis codes to Android key codes and axis codes and specifying associated policy flags.
• The <matrix keypad driver name>.kl (e.g. QWERTY_Keypad.kl) or <gpio keypad driver name>.kl (e.g. gpio-keys.kl) should be present in root directory of AndroidFS.
• Syntax of a Key layout File (Refer to the link: http://source.android.com/tech/input/key-layout-files.html):

• Key declarations each consist of the keyword "key" followed by a Linux key code number(In Decimal), an Android key code name, and optional set of whitespace delimited policy flags.
• For example:

  The gpio-keys.kl for Beaglebone looks like:
  # Beaglebone LCD Cape  GPIO KEYPAD keylayout
  key 105   BACK               WAKE
  key 106   HOME               WAKE
  key 103   MENU               WAKE
  key 108   SEARCH             WAKE
  key 28    POWER              WAKE

• For finding a suitable Android key code name for your requirement, follow the link: http://source.android.com/tech/input/keyboard-devices.html
• The Policy Flags specify extra information such as: whether this key should wake the device, also while waking the device should this key press be considered etc. Complete information is available under the "Key Declarations" in the link: http://source.android.com/tech/input/key-layout-files.html

MMC

Introduction

The MMC/SD card is used as the primary boot device and storage device on TI Android DevKit. This section gives details on configuring the MMC interface and supporting MMC/SD storage card.

Features Overview

The MMC/SD/SDIO driver supports following features

• The driver is built in-kernel (part of vmlinux).
• MMC cards including High Speed cards.
• SD cards including SD High Speed and SDHC cards
• Uses block bounce buffer to aggregate scattered blocks

Driver Configuration

• Refer PSP 04.02.00.07 MMC Driver Guide for AM37x
• Refer AM335x MMC/SD Driver's Guide for AM335x

Android MMC HAL or Vold Configuration

Android system uses vold as the mount daemon, which detects, mounts and monitors the status of sdcard. The mount daemon needs a configuration file to tell it what the sdcard device is. Since Android 2.2 (froyo), it ships with a new implementation of vold (aka vold2). The configuration is changed to /etc/vold.fstab and its format is also changed. See system/core/rootdir/etc/vold.fstab in the Android source tree for the detailed explanations of the format.

However, a fixed vold.fstab can only support block device with fixed name.

# cat /etc/vold.fstab
dev_mount sdcard /mnt/sdcard 3 /devices/platform/omap/omap_hsmmc.0/mmc_host/mmc0
dev_mount usb /mnt/usb2 auto /devices/platform/omap/ti81xx-usbss/musb-hdrc.1/usb1

Depending on the interface used these values can change. Best way is to probe sysfs directories to find the fixed name. For MMC the entry will be of the form:

 /sys/devices/platform/omap/omap_hsmmc.X/mmc_host/mmcY

Update the android storage list overlay at overlay/frameworks/base/core/res/res/xml/storage_list.xml

<StorageList xmlns:android="http://schemas.android.com/apk/res/android">
    <storage android:mountPoint="/storage/sdcard0"
             android:storageDescription="@string/storage_internal"
             android:primary="true"
             android:emulated="true"
             android:mtpReserve="100" />
</StorageList>

Audio

This release supports audio playback and capture at 44.1kHz. For application-specific usage, the audio HAL supports the software resampler. The audio HAL is implemented at hardware/ti/omap3/audio. The audio HAL uses the file mixer_paths.xml to configure the audio driver. This file contains the ALSA mixer settings for the various audio paths supported by the driver. The mixer_paths.xml is present at device/ti/<boardname> and is copied to the filesystem by the entry in device.mk. The following is the contents of mixer_paths.xml for AM335x EVM

<mixer>
  <!-- These are the initial mixer settings -->
  <ctl name="DAC IF1 SWITCH" value="Normal" />

  <path name="speaker">
    <ctl name="PCM Playback Volume" value="120" />
  </path>

  <path name="headphone">
    <ctl name="PCM Playback Volume" value="120" />
  </path>

  <path name="headset-mic">
    <ctl name="Mic Jack Switch" value="1" />
    <ctl name="Analog Left AUXL Capture Switch" value="1" />
    <ctl name="Analog Right AUXR Capture Switch" value="1" />
    <ctl name="Analog Capture Volume" value="3"/>
   </path>
</mixer>

The mixers setting commands at the beginning of the file are executed when the audio HAL is initialized. The mixer settings within the various <paths> are executed when that mode of operation is selected.

Testing audio from command line

You can use tinyalsa utilities to test audio input/output from shell.

• To play simple audio

   # tinyplay testfile.wav -n 16

• To record simple audio

   # tinycap testfile.wav -n 16

NOTE: The above commands are specific to AM335x-based devices. For AM37x devices -n 16 option is not required.

NOTE: Android handles volume control in software. We recommend to keep the default volume levels close to maximum in the audio HAL.

WLAN

Introduction

This section of guide provides a step by step explanation of what's involved in adding a new WiFi driver and making WiFi work in a custom Android build like Rowboat.

Features Overview

• WLAN (802.11 b/g/n)
• Core IP pre-tested against WiFi specifications.
• Station mode is fully supported.
• Initial support for SoftAP/WiFi hotspot and WiFi Direct is available

Android WLAN Sub-System Overview

Diagram explains WLAN event flow from application to h/w with respect to rowboat android source tree.

Application

• Settings/Connection Manager:<android-src>/packages/apps/Settings/src/com/android/settings/WirelessSettings.java

Application Framework

• WiFi manager:<android-src>/frameworks/base/wifi/java/android/net/wifi
• JNI Implementation:<android-src>/frameworks/base/core/jni/android_net_wifi_Wifi.cpp

Libraries

• libhardware_legacy:<android-src>/hardware/libhardware_legacy/wifi/wifi.c
• wpa_supplicant (Daemon):<android-src>/external/hostap/wpa_supplicant
• Higher level network management is done in <android-src>/frameworks/base/core/java/android/net.

Driver Configuration

In this Devkit release we are using WL12XX Compat wireless SDK. The drivers and firmwares of WL12XX Compat release are at hardware/ti/wlan

To enable WLAN support in kernel the following settings need to be enabled:

• First enable Wireless LAN device driver as shown below:

   Device Drivers  --->
       [*] Network device support  --->
           [*]   Wireless LAN --->

• Enable WLAN Networking support as shown below:

   [*] Networking support  --->
       -*-   Wireless  --->
           [*]   Wireless extensions sysfs files

This enables the following CONFIG options in kernel and allows WL12xx compat wlan drivers to be built:

   CONFIG_WLAN=y
   CONFIG_WIRELESS_EXT=y
   CONFIG_WEXT_CORE=y
   CONFIG_WEXT_PROC=y
   CONFIG_WEXT_PRIV=y

• The following additional options need to be enabled in kernel for WLAN to operate

  CONFIG_KEYS=y
  CONFIG_SECURITY=y
  CONFIG_CRYPTO=y
  CONFIG_CRYPTO_ARC4=y
  CONFIG_CRYPTO_ECB=y
  CONFIG_CRYPTO_AES=y
  CONFIG_CRYPTO_MICHAEL_MIC=y
  CONFIG_CRC7=y

• The relevant initialization and pin-muxing for MMC bus is done in the relevant board file e.g for AM335xevm arch/arm/mach-omap2/board-am335xevm.c. Do take care of this initialization and pin-muxing if using any other MMC bus e.g. MMC3.

The following code snippet shows the board-specific WLAN configuration done on AM335xevm. The code below is provided for information only and is not complete. Please refer to the source for more details.

File: arch/arm/mach-omap2/board-am335xevm.c arch/arm/mach-omap2/board-am335xevm.c

struct wl12xx_platform_data am335xevm_wlan_data = { .irq = OMAP_GPIO_IRQ(AM335XEVM_WLAN_IRQ_GPIO), .board_ref_clock = WL12XX_REFCLOCK_38_XTAL, /* 38.4Mhz */ .bt_enable_gpio = GPIO_TO_PIN(3, 21), .wlan_enable_gpio = GPIO_TO_PIN(1, 16), }; /* Module pin mux for wlan and bluetooth */ static struct pinmux_config mmc2_wl12xx_pin_mux[] = { {"gpmc_a1.mmc2_dat0", OMAP_MUX_MODE3 | AM33XX_PIN_INPUT_PULLUP}, {"gpmc_a2.mmc2_dat1", OMAP_MUX_MODE3 | AM33XX_PIN_INPUT_PULLUP}, {"gpmc_a3.mmc2_dat2", OMAP_MUX_MODE3 | AM33XX_PIN_INPUT_PULLUP}, {"gpmc_ben1.mmc2_dat3", OMAP_MUX_MODE3 | AM33XX_PIN_INPUT_PULLUP}, {"gpmc_csn3.mmc2_cmd", OMAP_MUX_MODE3 | AM33XX_PIN_INPUT_PULLUP}, {"gpmc_clk.mmc2_clk", OMAP_MUX_MODE3 | AM33XX_PIN_INPUT_PULLUP}, {NULL, 0}, }; ... static int wl12xx_set_power(struct device *dev, int slot, int on, int vdd) { if (on) { gpio_direction_output(am335xevm_wlan_data.wlan_enable_gpio, 1); mdelay(70); } else { gpio_direction_output(am335xevm_wlan_data.wlan_enable_gpio, 0); } return 0; } static void wl12xx_init(int evm_id, int profile) { ... if (wl12xx_set_platform_data(&am335xevm_wlan_data)) pr_err("error setting wl12xx data\n"); dev = am335x_mmc[1].dev; if (!dev) { pr_err("wl12xx mmc device initialization failed\n"); goto out; } ... ret = gpio_request_one(am335xevm_wlan_data.wlan_enable_gpio, GPIOF_OUT_INIT_LOW, "wlan_en"); ... setup_pin_mux(wl12xx_pin_mux); pdata->slots[0].set_power = wl12xx_set_power; out: return; }

See also: WL127x WiLink6 Portal

Android WiFi HAL Configuration

• Enable building of TI version of wpa_supplicant 0.8.x in your BoardConfig.mk (e.g. device/ti/am335xevm/BoardConfig.mk for AM335xevm and device/ti/omap3evm/BoardConfig.mk for AM37xevm)

This is by simply adding following options in BoardConfig.mk:

   BOARD_WPA_SUPPLICANT_DRIVER      := NL80211
   WPA_SUPPLICANT_VERSION           := VER_0_8_X_TI
   BOARD_WLAN_DEVICE                := wl12xx_mac80211
   BOARD_SOFTAP_DEVICE              := wl12xx_mac80211
   WIFI_DRIVER_MODULE_PATH          := "/system/lib/modules/wl12xx_sdio.ko"
   WIFI_DRIVER_MODULE_NAME          := "wl12xx_sdio"

This will set WPA_BUILD_SUPPLICANT to true in external/wpa_supplicant_8_ti/Android.mk enabling building of wpa_supplicant 0.8.x with NL80211. At run time wl12xx_sdio will get loaded from WIFI_DRIVER_MODULE_PATH.

BOARD_SOFTAP_DEVICE := wl12xx_mac80211 needs to be set only if SoftAP/hotspot feature is required.

• Next we need to provide a proper wpa_supplicant.conf for our device. That we will keep in /data/misc/wifi.

• Set the correct permissions and paths created and load the core wi-fi drivers from init.am335xevm.rc

# wi-fi
   mkdir /data/misc/wifi/sockets 0770 wifi wifi
   mkdir /data/misc/dhcp 0770 dhcp dhcp
   insmod /system/lib/modules/compat.ko
   insmod /system/lib/modules/cfg80211.ko
   insmod /system/lib/modules/mac80211.ko
   insmod /system/lib/modules/wlcore.ko
   insmod /system/lib/modules/wl12xx.ko
   insmod /system/lib/modules/wl18xx.ko

• Set the wifi interface name in device.mk

  PRODUCT_PROPERTY_OVERRIDES := \
       wifi.interface=wlan0

• Start wpa_supplicant and dhcpcd from init.am335xevm.rc.

service wpa_supplicant /system/bin/wpa_supplicant \
       -iwlan0 -Dnl80211 -c/data/misc/wifi/wpa_supplicant.conf \
       -e/data/misc/wifi/entropy.bin
       class main
       socket wpa_wlan0 dgram 660 wifi wifi
       disabled
       oneshot

service dhcpcd_wlan0 /system/bin/dhcpcd -ABKL
       class main
       disabled
       oneshot

service iprenew_wlan0 /system/bin/dhcpcd -n
       class main
       disabled
       oneshot

The following entries are required to configure SoftAP/hotspot and WiFi Direct functions:

• Register hostap service for SoftAP/hotspot:

service hostapd_bin /system/bin/hostapd -d /data/misc/wifi/hostapd.conf
   socket wpa_wlan0 dgram 660 wifi wifi
   disabled
   oneshot

• Register the supplicant and dhcp hooks for WiFi Direct:

service p2p_supplicant /system/bin/wpa_supplicant \
       -iwlan0 -Dnl80211 -c/data/misc/wifi/wpa_supplicant.conf -N \
       -ip2p0 -Dnl80211 -c/data/misc/wifi/p2p_supplicant.conf \
       -puse_p2p_group_interface=1
       class main
       socket wpa_wlan0 dgram 660 wifi wifi
       disabled
       oneshot

service dhcpcd_p2p /system/bin/dhcpcd -aABKL
   disabled
   oneshot

service iprenew_p2p /system/bin/dhcpcd -n
   disabled
   oneshot

Overlay changes

The following entries enable Wi-Fi for use by android network manager.

Add the following entries in device/ti/<boardname>/overlay/frameworks/base/core/res/res/values/config.xml

<string-array translatable="false" name="networkAttributes">
...
        <item>"wifi,1,1,1,-1,true"</item>
        <item>"wifi_p2p,13,1,0,-1,true"</item>
...
    </string-array>

<string-array translatable="false" name="radioAttributes">
        <item>"1,1"</item>
...
    </string-array>

Add the required permissions file into the android filesystem by updating device.mk. This also enables the Wi-Fi and Wi-Fi Direct options in the Settings App.

PRODUCT_COPY_FILES := \
...
    frameworks/native/data/etc/android.hardware.wifi.xml:system/etc/permissions/android.hardware.wifi.xml \
    frameworks/native/data/etc/android.hardware.wifi.direct.xml:system/etc/permissions/android.hardware.wifi.direct.xml

Verify WLAN from console

The following steps perform basic checks to see if WiFi driver is operational:

# lsmod
wl12xx 142062 0 - Live 0xbf08d000 (O)
mac80211 248275 1 wl12xx, Live 0xbf03c000 (O)
cfg80211 161123 2 wl12xx,mac80211, Live 0xbf004000 (O)
compat 1706 0 - Live 0xbf000000 (O)


# insmod /system/lib/modules/wl12xx_sdio.ko
[  154.549804] wl1271: loaded

If you do not see the message wl1271: loaded after inserting wl12xx_sdio.ko kernel module, the wifi driver initialization may not be correct. Please ensure that all the relevant pinmuxing and gpio configuration is correct and not over-written.

Next, check that the driver is not unloaded after initialization:

# netcfg
lo       UP                                   127.0.0.1/8   0x00000049 00:00:00:00:00:00
sit0     DOWN                                   0.0.0.0/0   0x00000080 00:00:00:00:00:00
eth0     UP                               172.24.190.76/22  0x00001043 40:5f:c2:76:4c:99
wlan0    DOWN                                   0.0.0.0/0   0x00001002 00:12:34:56:78:90

If wlan0 is not available in netcfg output, the driver might have been unloaded due to some error.

Now, we try to up the wlan0 interface:

# netcfg wlan0 up
[ 8255.485626] wl1271: firmware booted (Rev 6.3.6.0.79_2)
[ 8255.491027] wl1271: Driver version: R4_SP2_03_00
[ 8255.515350] ADDRCONF(NETDEV_UP): wlan0: link is not ready

The above messages show that the interface is up and the firmware is downloaded to wlan module and booted.

Ensure that wlan drivers are unloaded before trying the Android UI for wireless settings

# netcfg wlan0 down
# rmmod wl12xx_sdio

If wlan0 is not available in netcfg output, the driver might have been unloaded due to some error.

TBD

WLAN calibration

• Copy the ini files used for calibration to the sdcard

  sudo cp -rv rowboat/hardware/ti/wlan/mac80211/ti-utils/ini_files /media/rootfs/system/etc/wifi

• Boot the board. Make sure WLAN is disabled. wl12xx_sdio.ko should NOT be loaded

root@android:/ # lsmod
omaplfb 10662 0 - Live 0xbf0ed000 (O)
pvrsrvkm 159205 49 omaplfb, Live 0xbf0bc000 (O)
wl12xx 142062 0 - Live 0xbf08e000 (O)
mac80211 251034 1 wl12xx, Live 0xbf03c000 (O)
cfg80211 161115 2 wl12xx,mac80211, Live 0xbf004000 (O)
compat 1706 0 - Live 0xbf000000 (O)

• Remove existing calibration file

  rm /system/etc/firmware/ti-connectivity/wl1271-nvs.bin

• Run the calibrator tool

  calibrator plt autocalibrate wlan0 /system/lib/modules/wl12xx_sdio.ko /system/etc/wifi/ini_files/127x/TQS_S_2.6.ini /system/etc/firmware/ti-connectivity/wl1271-nvs.bin

NOTE: Running the calibration results in a random MAC address being set. To set the desired MAC address, run the following step:

  calibrator set nvs_mac /system/etc/firmware/ti-connectivity/wl1271-nvs.bin <MAC Address>

You can verify the MAC address using the following command:

  calibrator get nvs_mac /system/etc/firmware/ti-connectivity/wl1271-nvs.bin

Bluetooth

Introduction

This section describes how to enable Bluetooth support on Android for wl1271 chipset.

Features Overview

• Bluetooth 2.1
• OPP, A2DP, AVRCP, HID profiles are supported.
• HSP, HFP profiles are NOT supported

Android BT Sub-System Overview

Enable Bluetooth with the following setting in BoardConfig.mk (e.g. device/ti/am335xevm/BoardConfig.mk)

   # Bluetooth
   BOARD_HAVE_BLUETOOTH := true

This enables bluez external/bluez HAL layer, which is used to connect with Android Frameworks (frameworks/base/core/jni/android_bluetooth_*.cpp, frameworks/base/core/java/android/bluetooth/*.java and SystemServer via DBUS .

Driver Configuration

TI Android DevKit uses the TI Wilink7 Bluetooth driver along with the TI Shared-Transport driver (TI-ST) for managing the BT-UART.

• WL12xx BT is interfaced to UART1 on AM37xevm and AM335xevm. UART1 initialization and BT module registration with TI-ST is implemented at arch/arm/mach-omap2/board-am335xevm.c for AM37xevm and arch/arm/mach-omap2/board-am335xevm.c for AM335xevm.

• Bluetooth support is enabled in the kernel as shown below:

   [*] Networking support  ---> 
       <*>   Bluetooth subsystem support  --->
           [*]   L2CAP protocol support
           <*>   RFCOMM protocol support
           <*>   RFCOMM protocol support
           <*>   BNEP protocol support
           [*]     Multicast filter support
           [*]     Protocol filter support 
           <*>   HIDP protocol support 
                 Bluetooth device drivers  --->
                   <*> HCI UART driver
                   [*]   UART (H4) protocol support 
                   [*]   HCILL protocol support
       <*>   RF switch subsystem support

This enables the following CONFIG options:

CONFIG_BT=y
CONFIG_BT_L2CAP=y
CONFIG_BT_RFCOMM=y
CONFIG_BT_RFCOMM_TTY=y
CONFIG_BT_BNEP=y
CONFIG_BT_BNEP_MC_FILTER=y
CONFIG_BT_BNEP_PROTO_FILTER=y
CONFIG_BT_HIDP=y
CONFIG_BT_HCIUART=y
CONFIG_BT_HCIUART_H4=y
CONFIG_BT_HCIUART_LL=y
CONFIG_RFKILL=y

• The following CONFIG options enable TI-ST and WiLink Bluetooth driver support:

CONFIG_BT_WILINK=y
CONFIG_TI_ST=y

• The following kernel configs are required for Bluetooth AVRCP support:

CONFIG_INPUT_MISC=y
CONFIG_INPUT_UINPUT=y

You can check this as follows:

   Device Drivers  --->
       Input device support  --->
           [*]   Miscellaneous devices  --->
                   <*>   User level driver support

The following code-snippet shows board-level configuration for TI-ST on AM335xevm:

File: arch/arm/mach-omap2/board-am335xevm.c

struct ti_st_plat_data wilink_pdata = { .nshutdown_gpio = GPIO_TO_PIN(3, 21), .dev_name = "/dev/ttyO1", .flow_cntrl = 1, .baud_rate = 3000000, .suspend = plat_kim_suspend, .resume = plat_kim_resume, .chip_enable = plat_kim_chip_enable, .chip_disable = plat_kim_chip_disable, }; static struct platform_device wl12xx_device = { .name = "kim", .id = -1, .dev.platform_data = &wilink_pdata, }; static struct platform_device btwilink_device = { .name = "btwilink", .id = -1, }; static inline void __init am335xevm_init_btwilink(void) { pr_info("am335xevm: bt init\n"); platform_device_register(&wl12xx_device); platform_device_register(&btwilink_device); }

Android BT HAL Configuration

• Set the correct permissions and paths created from init.rc

   #Owners, Modes for Bluetooth
   chmod 0660 /dev/ttyO1
   chown bluetooth bluetooth /dev/ttyO1
   chmod 0660 /sys/class/rfkill/rfkill0/state
   chown bluetooth bluetooth /sys/class/rfkill/rfkill0/state

• The following services are registered in init.rc for Bluetooth operation:

• dbus-daemon: (deal connections between hcid and system server)

   service dbus /system/bin/dbus-daemon --system --nofork
   class main
   socket dbus stream 660 bluetooth bluetooth
   user bluetooth
   group bluetooth net_bt_admin

• bluetoothd: create hcid (Bluetooth Host Controller Interface Daemon) service, but disabled at first

   service bluetoothd /system/bin/bluetoothd -n
   class main
   socket bluetooth stream 660 bluetooth bluetooth
   socket dbus_bluetooth stream 660 bluetooth bluetooth
   # init.rc does not yet support applying capabilities, so run as root and
   # let bluetoothd drop uid to bluetooth with the right linux capabilities
   group bluetooth net_bt_admin misc
   disabled

• uim-sysfs: userspace module for TI-ST kernel driver. This service attaches the BT UART HCI interface to the bluetooth stack at 3000000 baud rate. It is also responsible for loading the BT firmware on WL1271. The sources for uim-sysfs is found in hadware/ti/wpan

   #shared transport user space mgr service for Bluetooth, FM and GPS
   service uim /system/bin/uim-sysfs
   class core
   user bluetooth
   group bluetooth net_bt_admin

Overlay changes

Add bluetooth entry in the overlay to indicate bluetooth availability to network manager

<string-array translatable="false" name="networkAttributes">
...
    <item>"bluetooth,7,7,0,-1,true"</item>
...
</string-array>

<string-array translatable="false" name="radioAttributes">
...
    <item>"7,1"</item>
...

Copy the Bluetooth permissions file and the relevant bluez conf file. The permissions file also enables Bluetooth menu in Settings

PRODUCT_COPY_FILES += \
    frameworks/native/data/etc/android.hardware.bluetooth.xml:system/etc/permissions/android.hardware.bluetooth.xml \
    system/bluetooth/data/main.nonsmartphone.conf:system/etc/bluetooth/main.conf

USB Host and Gadget

Introduction

Android JB supports both USB host and USB device ports. USB host can be used to connect Keyboard/Mouse, Mass storage device, modem dongles etc, while the USB device port is mainly used for adb and USB accessory gadgets.

Driver Configuration

• See AM335x USB Driver's Guide for AM335xevm
  • The USB Android Gadget driver on AM335x is enabled as shown below:

-> Device Drivers
   -> USB support
      -> USB Gadget Support
         -> USB Gadget Drivers
            (X) Android Gadget

Android USB Configuration

Android USB Gadget Configuration

USB Gadget configuration for AM335x

The Android gadget driver is configured via the sysfs entries. These are done from init.<ro.hardware>.usb.rc. For am335xevm, this is init.am335xevm.usb.rc

on boot
    write /sys/class/android_usb/android0/iManufacturer ${ro.product.manufacturer}
    write /sys/class/android_usb/android0/iProduct ${ro.product.model}
    write /sys/class/android_usb/android0/iSerial ${ro.serialno}

on property:sys.usb.config=none
    stop adbd
    write /sys/class/android_usb/android0/enable 0
    write /sys/class/android_usb/android0/bDeviceClass 0
    setprop sys.usb.state ${sys.usb.config}

on property:sys.usb.config=adb
    write /sys/class/android_usb/android0/enable 0
    write /sys/class/android_usb/android0/idVendor 18d1
    write /sys/class/android_usb/android0/idProduct D002
    write /sys/class/android_usb/android0/functions ${sys.usb.config}
    write /sys/class/android_usb/android0/enable 1
    setprop sys.usb.state ${sys.usb.config}

on property:sys.usb.config=mtp
    write /sys/class/android_usb/android0/enable 0
    write /sys/class/android_usb/android0/idVendor 18d1
    write /sys/class/android_usb/android0/idProduct D108
    write /sys/class/android_usb/android0/functions ${sys.usb.config}
    write /sys/class/android_usb/android0/enable 1
    setprop sys.usb.state ${sys.usb.config}

on property:sys.usb.config=mtp,adb
    write /sys/class/android_usb/android0/enable 0
    write /sys/class/android_usb/android0/idVendor 18d1
    write /sys/class/android_usb/android0/idProduct D109
    write /sys/class/android_usb/android0/functions ${sys.usb.config}
    write /sys/class/android_usb/android0/enable 1
    start adbd
    setprop sys.usb.state ${sys.usb.config}

The sysfs settings need to be done depending on the features required to be enabled. By default only the adb and mtp mode is configured.

USB Accessory Gadget configuration for AM335x

To indicate that the platform supports USB Host port add the following to device.mk:

PRODUCT_COPY_FILES += \
    frameworks/native/data/etc/android.hardware.usb.accessory.xml:system/etc/permissions/android.hardware.usb.accessory.xml

PRODUCT_PACKAGES += \
    com.android.future.usb.accessory

NOTE: The USB accessory does not work over USB Hub.

Android USB Host Configuration

To indicate that the platform supports USB Host port add the following to device.mk:

PRODUCT_COPY_FILES += \
    frameworks/native/data/etc/android.hardware.usb.host.xml:system/etc/permissions/android.hardware.usb.host.xml

NAND

TBD

Sensors

Accelerometer

The STMicro LIS33 Accelerometer is supported on Am37x Flashboard and AM335x evm.

Kernel driver for accelerometer on AM335x : http://gitorious.org/rowboat/kernel/trees/rowboat-am335x-kernel-3.2/drivers/misc/lis3lv02d

Android HAL on AM335xevm: http://gitorious.org/rowboat/vendor-ti-am335xevm/trees/rowboat-jb/libsensors

To indicate accelerometer support to android add the following line in device.mk

PRODUCT_COPY_FILES += \
    frameworks/native/data/etc/android.hardware.sensor.accelerometer.xml:system/etc/permissions/android.hardware.sensor.accelerometer.xml

Light sensor

AM335x evm supports light sensor TSL2550.

Light sensor kernel driver : http://gitorious.org/rowboat/kernel/blobs/rowboat-am335x-kernel-3.2/drivers/misc/tsl2550.c

Please note that the standard linux driver is modified to report light sensor values to the input sub-system. See commit.

Android HAL on AM335xevm: http://gitorious.org/rowboat/vendor-ti-am335xevm/trees/rowboat-jb/libsensors

To indicate light sensor support to android add the following line in device.mk

PRODUCT_COPY_FILES += \
    frameworks/native/data/etc/android.hardware.sensor.light.xml:system/etc/permissions/android.hardware.sensor.light.xml

You can use the light sensor input to modify the LCD backlight intensity. You need to add the following entry in the overlay:

  <bool name="config_automatic_brightness_available">true</bool>

Also you need to implement a lookup table to map the light intensity to the LCD backlight values. Please refer to the overlay patch file for more details.

Temperature Sensor

AM335xevm supports temperature sensor LM75.

Kernel driver path : https://gitorious.org/rowboat/kernel/blobs/rowboat-am335x-kernel-3.2/drivers/hwmon/lm75.c The driver is modified to be compatible with the android sensor input subsystem. See commits here and here

Android HAL for AM335xevm is at :http://gitorious.org/rowboat/vendor-ti-am335xevm/trees/rowboat-jb/libsensors

Camera

TBD

USB camera

This section discusses interfacing USB camera with android

Kernel configuration

Enable the following CONFIGs to add support for USB camera in kernel:

  CONFIG_USB_VIDEO_CLASS=y
  CONFIG_USB_VIDEO_CLASS_INPUT_EVDEV=y

Android Configuration

Enable USB Camera support in BoardConfig.mk. Also disable stub camera

   BOARD_USB_CAMERA := true
   #USE_CAMERA_STUB := true

Add the following entries in device.mk

#Camera
PRODUCT_PACKAGES += \
        camera.omap3 \

NOTE: The Camera icon will automatically appear in apps due to presence of camera.omap3.so in the filesystem.

Add permission for camera in init.am335xevm.rc. This is used for temporary storage before capture.

   mkdir /data/misc/camera 0770 media media

Add camera permissions in ueventd.am335xevm.rc

  /dev/video0         0666  root       root

The Camera HAL is at hardware/ti/omap3/camera.

NOTE: By default it is assumed that the USB camera is registered as /dev/video0 ( source ). You may need to change this for your device.

USB 3G Modem

The USB 3G Modem section describes how to connect USB Modem to the android.

Introduction

PPP is the protocol used for establishing internet links over dial-up modems, DSL connections, and many other types of point-to-point links. The pppd daemon works together with the kernel PPP driver to establish and maintain a PPP link with another system (called the peer) and to negotiate Internet Protocol (IP) addresses for each end of the link.

Kernel Configuration for USB Modem

Device Drivers  --->
 [*] Network device support  --->
   <*>   PPP (point-to-point protocol) support
     <*>     PPP BSD-Compress compression
     <*>     PPP Deflate compression
     <*>     PPP support for async serial ports
     <*>     PPP support for sync tty ports
 [*] USB support  --->
   <*>   USB Modem (CDC ACM) support
   <*>   USB Serial Converter support  --->
     [*]   USB Generic Serial Driver
     <*>   USB driver for GSM and CDMA modems

File System Changes

To get the Modem Working, we need usb_modeswitch, usb_modeswicth.conf(configuration file) for the specific modem or Hardware vendor and the airtel.chat(dialer script) for the specific network.

• Copy the usb_modeswitch (ARM Compiled binary) and usb_modeswitch.conf to the /system/xbin folder. The ARM compiled binary and the sources can be obtained from HERE
• Copy the airtel.chat(dialer script) to the /system/etc/ppp folder

Below is the description of an example usb_modeswitch.conf file for the Huawei E1731 Modem (Airtel in India)

  Huawei E1731

  EnableLogging=1

  DefaultVendor= 0x12d1
  DefaultProduct=0x1446

  TargetVendor=  0x12d1
  TargetProductList="1001,1406,140b,140c,1412,141b,1436,14ac,1506"

  CheckSuccess=20

  MessageEndpoint= 0x01
  MessageContent="55534243123456780000000000000011062000000100000000000000000000"

The DefaultVendor and DefaultProduct is the ID displayed for CDROM or mass storage, the TargetVendor and TargetProduct is for Modem. Plug the device into linux system and do "dmesg" or "lsusb" to know the IDs.

Example: HUAWEI E1731 Modem Below is the log when plugged to PC

   [6663132.917033] usb 1-4: new high speed USB device number 10 using ehci_hcd
   [6663133.033394] usb 1-4: New USB device found, idVendor=12d1, idProduct=1446
[6663133.033400] usb 1-4: New USB device strings: Mfr=3, Product=2, SerialNumber=0
[6663133.033404] usb 1-4: Product: HUAWEI Mobile
[6663133.033407] usb 1-4: Manufacturer: HUAWEI Technology
[6663133.036040] scsi16 : usb-storage 1-4:1.0
[6663133.036652] scsi17 : usb-storage 1-4:1.1
[6663133.685546] usb 1-4: USB disconnect, device number 10
[6663137.665047] usb 1-4: new high speed USB device number 11 using ehci_hcd
[6663137.781645] usb 1-4: New USB device found, idVendor=12d1, idProduct=1436
[6663137.781651] usb 1-4: New USB device strings: Mfr=4, Product=3, SerialNumber=0
[6663137.781654] usb 1-4: Product: HUAWEI Mobile
[6663137.781657] usb 1-4: Manufacturer: HUAWEI Technology
[6663137.784476] option 1-4:1.0: GSM modem (1-port) converter detected
[6663137.784663] usb 1-4: GSM modem (1-port) converter now attached to ttyUSB0
[6663137.786425] cdc_ether 1-4:1.1: wwan0: register 'cdc_ether' at usb-0000:00:1d.7-4, Mobile Broadband Network Device, 02:50:f3:00:00:00
[6663137.788066] option 1-4:1.3: GSM modem (1-port) converter detected
[6663137.788268] usb 1-4: GSM modem (1-port) converter now attached to ttyUSB1
[6663137.788509] option 1-4:1.4: GSM modem (1-port) converter detected
[6663137.788646] usb 1-4: GSM modem (1-port) converter now attached to ttyUSB2
[6663137.789203] scsi22 : usb-storage 1-4:1.5
[6663137.789812] scsi23 : usb-storage 1-4:1.6
[6663138.790809] scsi 22:0:0:0: CD-ROM            HUAWEI   Mass Storage     2.31 PQ: 0 ANSI: 2
[6663138.791303] scsi 23:0:0:0: Direct-Access     HUAWEI   SD Storage       2.31 PQ: 0 ANSI: 2
[6663138.807169] sr1: scsi-1 drive
[6663138.808426] sr 22:0:0:0: Attached scsi CD-ROM sr1
[6663138.808593] sr 22:0:0:0: Attached scsi generic sg5 type 5
[6663138.809394] sd 23:0:0:0: Attached scsi generic sg6 type 0
[6663138.812181] sd 23:0:0:0: [sde] Attached SCSI removable disk

Below is the description of an example airtel.chat(dialer script) file for AirTel (INDIA)

TIMEOUT 10
ABORT 'BUSY'
ABORT 'NO ANSWER'
ABORT 'ERROR'
SAY 'Starting GPRS connect script\n'
""'ATZ'
SAY 'Setting APN\n'
OK 'AT+CGDCONT=1,"IP","airtelgprs.com"'
ABORT 'NO CARRIER'
SAY 'Dialing...\n'
OK 'ATD*99***1#'
CONNECT

NOTE: the single quotes in the above chat file must be together. ie no space allowed.

This file is network service provider dependent, so modify the airtelgprs.com according to your service provider.

Usage

Below are the steps to perform once android boots up with the above necessary modifications

• Disable wireless and ethernet settings
• Plug the USB Modem
• Run the following commands

   mount -t usbfs usbfs /proc/bus/usb

   /system/xbin/usb_modeswitch -I -W -c /system/xbin/usb_modeswitch.conf

Mount the usbfs file system to /proc/bus/usb. This is necessary to avoid the “Couldn’t opendir()” error you get otherwise on running usb_modeswitch.
Once Mode Switch Succeeds, modem will be enumerated as /dev/ttyUSB* (* can be 0,1,2).
If you place the usb_modeswitch and usb_modeswitch.conf at other place, change the above command accordingly.

• Once Modem succeeds in enumeration, run the follwoing command

   /system/bin/pppd /dev/ttyUSB0 115200 persist defaultroute usepeerdns updetach crtscts noauth debug connect "/system/xbin/chat -v -s -f /system/etc/ppp/airtel.chat"

• From the logcat check what primary and secondary dns server IPs you got, you can kill the logcat after getting the IPs. Set those primary and secondary DNS server IPs for your device with the following commands replacing IP1 and IP2 with whatever IPs you got.

   setprop net.dns1 <IP1>
   setprop net.dns2 <IP2>

You are ready to browse that net after this if everything went well in the previous steps.
Enjoy the 3G fast speed surfing on your device.

Disclaimer

• All components explained in this porting guide are validated against TI Android DevKit release 4.0.0 and 4.0.1 only.
• This guide can be taken as reference to port mentioned components on similar architecture.

Technical Support and Product Updates

For further information or to report any problems, contact http://e2e.ti.com/android or http://support.ti.com.
For community support join http://groups.google.com/group/rowboat
For IRC #rowboat on irc.freenode.net