Creating an Android FM app

An Android FM application contains at least 2 components, usually packaged in the same APK android package file:

A UI (User Interface) component. This handles direct user interaction for functions including setting frequency,configuration, and status display. The UI component runs only when the FM app is on screen.

A Service component. This runs at least as long as FM is playing, even when the screen is off. It handles “background” tasks, such as enabling volume and media button controls.

Other UI type components may exist, such as Widgets or even a live wallpaper.

UI components generally interact mostly with the Service component, sending commands or calling functions such as setFrequency() or getVolume(). There are no standards for “app internal” APIs. Samsung, HTC, Motorola, LG and most others have their own apps and customs, and they can change from version to version.

The Service component generally communicates with the FM and audio hardware, in some cases through a few abstraction layers of code with their own APIs.

There are no particularly useful standards for most of these APIs, with the exception of the V4l /dev/radio0 API. But even V4L drivers have their own private IOCtls for many functions, such as RDS data retrieval or special configurations.

There had (has ?) been an effort by ST-Ericsson to establish a common Android FM API, going back 2 years now. Unfortunately it seems to have gone nowhere, despite some code checkins to AOSP for ICS. Some 2012 Sony/Sony-Ericsson phones seem to use a variant of this API, but the vast majority of devices with FM capability still use OEM Proprietary APIs.

OEM Proprietary APIs are pretty much undocumented and often secret. Only those working for OEM customer companies can access the documents, and must sign an NDA to do so. Underlying reasons may include the ongoing patent battles as well as good old competitive secrecy.

There are currently 5 major “OEM Proprietary FM APIs” for Android Java, roughly ranked by popularity:

Broadcom: Used on MANY devices with Broadcom FM/WiFi/Bluetooth combo chips from HTC, Samsung, LG and even the Motorola Photon. Most common chip/API but Samsung is likely catching up. Source code is closed.

Samsung: Used on Samsung Silicon Labs si470x devices including Galaxy S/S2/S3/Note/Player. Silicon Labs must enjoy the raging popularity of these high end Samsung devices. Samsung source is closed, but some open source implementations exist.

Motorola: Most Motorola devices used TI chips, but with their own Motorola specific API. Around 2010 Motorola was using the TI API. Motorola may transition to the Broadcom chips and API, if they continue to support FM at all. Motorola source is closed.

Texas Instruments: Used on some HTC devices with TI FM/WiFi/BT chips, with a variant on Sony-Ericsson’s in 2011. As of Sept. 2012, TI seems to be exiting the mobile business; OMAP5 is out, not known about TI FM/combo chips but they’ve never sold too well, except via Motorola. TI and Sony-Ericsson have both released the source code for this API and it’s SE variant.

Qualcomm: Used for Qualcomm FM/combo chips, generally paired with a QCom SOC. Includes HTC OneXL/OneS (iris chip), Huawei Ideos X5/X6 (tavarua). The CyanogenMod 7 FM app was derived from the Qualcomm/Code Aurora FM app and could be considered a variant, using the android.harware.fm Java namespace. Underneath this API, Qualcomm chips use a V4L API. Qualcomm and CM source code is open.

Some of these “OEM Proprietary FM APIs” provide access to audio control, routing and processing functions, and some do not, or at least not all functions. MANY somewhat standard and completely non-standard APIs exist for audio.

In some cases, standard functions such as setDeviceConnectionState() and setForceUse() can be used, but the values passed to them are not standardized for FM. Values such as “routing=8” or “nonstd_fm_on=yes” might be passed to setParameters(). Or Intents can be sent, or fm_flag variables can be set under /sys/. HTC apps do different things depending on the product generation. Motorola is more consistent.

Below the OEM APIs are lower level APIs. Access to these is needed on AOSP based custom ROMs that don’t include the OEM APIs. OEM APIs are usually contained in Jar files under /system/framework and have extensive hooks into OEM skins such as TouchWiz, Sense, Blur, etc. Because the needed source code is usually not available, only stock and “stock derived” ROMs support these APIs.

The most common low level APIs:

Broadcom HCI: The FM portion Broadcom FM/combo chips can be controlled with commands sent to dedicated chip pins, but very few devices use this FM specific connection. Dell Streak 5" is one exception, but it can also use what most devices do: The “HCI UART”, also used for Bluetooth and which shares a single hardware core.

Proprietary HCI commands can be used to get and set many FM registers. Documents are closed. An open source Nokia V4L driver reveals some registers.

Samsung Silicon Labs: Accessed via a Samsung specific /dev/fmradio device using proprietary IOCtls (Unfortunately misnamed /dev/radio0 on CM, implying V4L and requiring annoying detection code). Kernel configuration could provide a V4L compliant driver, but most kernels support the Samsung driver. Kernel driver source is open, and Silicon Labs has open documents.

ZTE Blade has a very different proprietary Silicon Labs driver for which source code is available.

Texas Instruments HCI: Same principles as Broadcom HCI, but uses TI specific proprietary registers. Documents are closed, but open source is available, albeit rather convoluted and difficult to grok.

V4L: At present, used notably for Qualcomm Iris or Tavarua FM chips on devices such as HTC OneXL/S/Evo 4G or Huawei Ideos X5/X6. Documents for these chips are closed, but kernel drivers are open source. Proprietary IOCtls are used beyond the scope of the V4L V2 radio driver standard.

Control of audio functions, such as enabling/disabling speakers and headsets, changing volume/gain levels, may require use of separate APIs, than the FM control APIs, such as tuning.

On stock and stock derived devices, or devices using stock audio libraries, audio functions are often relatively simple. But there are at least dozens of such APIs in common use and OEMs often use several.

Enabling FM on AOSP based custom ROMs with no FM audio functions requires low level access to one or more audio chips. APIs are likely in the hundreds, given all of the /dev devices, ALSA registers, and combinations of different chips.

But accessing low level audio functions “behind the back” of the audio library often has bad results. In many cases a robust solution for FM audio is not possible when using low level methods from an application. The best place for FM audio support is in the audio libraries.

Interference problems between audio libraries and an app using low level methods include:

1.Power shutdown of the audio chip because the library doesn’t know it’s being used.
2.Volume controls going to ringer for same reason.
3.Loss of audio during audio notifications, phone calls, etc., sometimes requiring a reboot or restart of the Android mediaserver to fix.