Monday, September 14, 2009

Tutorial : how to use the LED with Android phone

Some android phones have a nice LED ( but not all of them: I don't think the Galaxy has one ).

This LED can show lots of different colors, and adding this feature in your application is a nice little "plus" !
And it's really easy...


So how to do it ?

You just have to get the notification manager, and use it to send a flash Light notification.
The notification contains the color light, the duration with the LED On, and the duration with the LED off.

Here's the code :

private void RedFlashLight()
{
NotificationManager nm = ( NotificationManager ) getSystemService( NOTIFICATION_SERVICE );
Notification notif = new Notification();
notif.ledARGB = 0xFFff0000;
notif.flags = Notification.FLAG_SHOW_LIGHTS;
notif.ledOnMS = 100;
notif.ledOffMS = 100;
nm.notify(LED_NOTIFICATION_ID, notif);
}

LED_NOTIFICATION_ID is just a value to register this allocation. In my case, it is just 0.
Here, the LED will flash with the color given by the parameter ledARGB, in this case 0xFFff0000 (red ). It will be ON for 100 milliseconds, then OFF for 100 milliseconds, and then loop back ON, etc...

This is nice, but wait... How do I STOP it ?
This code will let the LED flash for ever !

To stop it, we have two solutions :
1) decide to only have the LED flash once, so in this case, you have to add the FLAG_ONLY_ALERT_ONCE flag :
notif.flags = Notification.FLAG_SHOW_LIGHTS | Notification.FLAG_ONLY_ALERT_ONCE;
2) Let the LED flash for as long as you want, then cancel the notification. In my case, I stop it after a certain amount of time by posting a message with a delay.
Here is the full code for this :

private void ClearLED()
{
NotificationManager nm = ( NotificationManager ) getSystemService( NOTIFICATION_SERVICE );
nm.cancel( LED_NOTIFICATION_ID );
}
private Runnable mClearLED_Task = new Runnable()
{
public void run()
{
synchronized( LetterGame.this)
{
ClearLED();
}
}
};

private void RedFlashLight()
{
NotificationManager nm = ( NotificationManager ) getSystemService( NOTIFICATION_SERVICE );
Notification notif = new Notification();
notif.ledARGB = 0xFFff0000;
notif.flags = Notification.FLAG_SHOW_LIGHTS;
notif.ledOnMS = 100;
notif.ledOffMS = 100;
nm.notify(LED_NOTIFICATION_ID, notif);
// Program the end of the light :
mCleanLedHandler.postDelayed(mClearLED_Task, LED_TIME_ON );
}


With mCleanLedHandler being just a handler, and LED_TIME_ON the flash duration.

Some notes :
1) Don't let a handler alive when changing activity ! On the OnPause of your activity, clear the handler :
mCleanLedHandler.removeCallbacks( mClearLED_Task );
2) programming the LED suffers one issue : the emulator does not emulate the LED at all... So you have to use a real device to see what it looks like ( but anyway, you always use real device at some point, don't you ? :) )
3) programming the LED then suffers a Second issue : when the real device is connected to your PC in order for you to develop / test / debug, the device is also charging the battery. And in this case, the LED is orange. Whatever notification you send ! So you have to test without your device plugged !


That's all !
With all that, you can code some nice LED flashes !!!