Illumination bar API

The Illumination bar API allows developers to control the LED light illumination bar at the bottom of a number of Xperia™ smartphones (see the list of support phones below). Some of the options that can be set are the LED colour, whether or not the LED pulses and time between pulses, and various pre-defined fading patterns.  On Xperia™ SP, the LED can also be set to illuminate in rhythm with music from the audio player.

Please note that the Illumination API is provided for free as an “experimental API”. This means you can experiment with illumination effects in your app in any way you like, but we will only provide limited documentation and no support.

Supported phones

The following phones are fully supported by the Illumination bar API:

  • Xperia™ SP
  • Xperia™ ZL
  • Xperia™ ZR
  • Xperia™ UL
  • Xperia™ A

The following phones are also supported by the Illumination bar API, but the support for the pre-defined fading patterns is less extensive on these devices:

  • Xperia™ U
  • Xperia™ L
  • Xperia™ S
  • Xperia™ SL
  • Xperia™ P
  • Xperia™ sola
  • Xperia™ ion
  • Xperia™ acro HD
  • Xperia™ go
  • Xperia™ M
  • Xperia™ M dual

Also, for some devices (for example Xperia™ S and Xperia™ P) the hardware only supports white colour.

How to use the Illumination bar API
To add illumination effects to your app, you need to take the following steps:

1. Download  the IlluminationIntent.java file to the \src\com\sonyericsson\illumination directory in your Android project. Create the needed directories if they don’t exist already.

2. Set the illumination permission in the AndroidManifest:

<uses-permission android:name="com.sonyericsson.illumination.permission.ILLUMINATION"/>

3. Use the illumination intent in your Activity to create the effect you want (change com.yourapplication.packagename to the actual package name of your app):
Intent intent = new Intent(IlluminationIntent.ACTION_START_LED);
intent.putExtra(IlluminationIntent.EXTRA_LED_ID, IlluminationIntent.VALUE_BUTTON_2);
intent.putExtra(IlluminationIntent.EXTRA_PACKAGE_NAME, "com.yourapplication.packagename");
startService(intent);

If you want your app to check if a device supports the Illumination API, you can add the following code to your Activity:
Intent checkIntent = new Intent(IlluminationIntent.ACTION_STOP_LED);

        // Evaluate if we have the Illumination Service installed that can receive the intent
        if (null == getPackageManager().resolveService(checkIntent,
                PackageManager.GET_RESOLVED_FILTER)) {
               //  Not supported
       }

Details about the pre-defined fading patterns

For Xperia™ SP, Xperia™ ZL, Xperia™ ZR, Xperia™ UL and Xperia™ A the following pre-defined patterns are available:


LED ID                       PRIO               FADE UP   FADE DOWN

--------------------------------------------------------------------

VALUE_BUTTON_2               PRIO_0              500        1000

LIGHT_ID_ATTENTION*          PRIO_1                0           0

VALUE_PATTERN_1              PRIO_2             1500        3000

VALUE_PATTERN_3              PRIO_3              800        1300

VALUE_PATTERN_2              PRIO_4              500        1000

VALUE_AUDIO**                PRIO_5                0           0

VALUE_BUTTON_RGB             PRIO_6              500        1000

LIGHT_ID_NOTIFICATIONS*      PRIO_7                0           0

LIGHT_ID_BATTERY*            PRIO_8                0           0

For all other supported phones (Xperia™ U,                            Xperia™ L, Xperia™ S, Xperia™ SL, Xperia™ P, Xperia™ sola, Xperia™ ion, Xperia™ acro HD, Xperia™ go, Xperia™ M and Xperia™ M dual), the following patterns are available:


LED ID                       PRIO                FADE UP   FADE DOWN

--------------------------------------------------------------------

VALUE_BUTTON_2               PRIO_0              500        1000

VALUE_BUTTON_RGB***          PRIO_2              500        1000

* Android specific, not possible to set with illumination.

** Xperia™ SP only.

*** Xperia™ U only.