[GUIDE+LIB] Detecting Kernel Hardware Changes (ex: HDMI/Dock) - Java and No ROOT

INTRODUCTION
I'm the developer of Screen Standby # root app (App allowing turning screen off / on without putting device to sleep). .During the development of my app, I have investigated and successed in implementing "Auto detecting HDMI / Docks / USB accessories", etc and found some interesting things. Now I want to share my methods of doing those task, that is why I created this library.

KernelSwitchObserverLib helps Android Developer creating app that is capable of "sensing" different changes in the device kernels. Those can be:
- HDMI Cable insertion / disconnection
- Headset connection (and what type of headset it is)
- Dock connection (even for various proprietary docks like the Motorola Atrix 4G)
- HTC's Beat audio enabling / disabling
- USB connection to Computer and what type of USB connection is (mass storage, MTP, etc)

Normally, one may capture intents from Android system to handle above tasks
But is it that simple?

For example, Intent has to be "exposed" by the android build so that Java developer can use it (Intent.ACTION_HEADSET_PLUG, for example)
But for some devices (especially proprietary ones from Samsung, HTC or Motorola, they do not expose it). Some of the examples are HDMI / MHL connection, which currently has very limited way of detection
And in order to "sense" those changes, developer must code observers in C/C++ (using NDK) and have a sufficient amount of low-level knowledge

This library solves that.

FEATURES
- It offers developer a way to sense hardware changes on the fly (HDMI connection, etc).
- Everything is Java friendly and compatible with all devices
- Works without Root
- UEvent methods are guaranteed to be triggered with higher priority than intent.

HOW DOES IT WORKS
I found a way to expose the class android.os.UEventObserver that is in charge of observing UEvent (user-events, native messages that Linux kernel broadcast upon a change in kernel hardware). The class is normally hidden from developers, and now I made it accessible through my library

Since UEventObserver "senses" the devices changes via kernel interrupts, there is absolutely no pooling (thread constantly checking for device status after an interval of time), thus, it is battery friendly.

Ok, so what are Hardware Switches?
They are low-level kernel switch (located in /sys/class/switch) that is in charge of reporting hardware state changes. Some of the examples are:

/sys/class/switch/h2w (headset connection status)
/sys/class/switch/hdmi (HDMI/MHL connection status)
/sys/class/switch/dock (Dock connection status)
/sys/class/switch/Beats (HTC's beat connection status (only available in devices having Beat audio))
and much more

SCREENSHOTS
I created an Observer example app to help you have a better look at the library:




LIBRARY STRUCTURE


Every classes are the package: com.nkahoang.observerexample
GenericHardwareObserver: Main class that is in charge of sensing hardware changes. Some main functions and methods are:
+ Constructor GenericHardwareObserver(String hardware_switch)
where hardware_switch is the kernel name of the switch (ex: "h2w" for headset switch, "dock" for Dock switch", "hdmi" for HDMI switch, etc)
+ Static Method List<String> getHardwareSwitches()
enumerate list of available hardware switches in the kernel
+ Method void start()
start observing for changes()
+ Method void stop()
stop observing for changes()
+ Method String getHardwareName()
get the formal name of the hardware (ex: "h2w" is the switch name, this method return "Headset", which is the name of hardware)
+ Method void setOnUEventChangeHandler(UEventChangeHandler handler)
Register a handler for the app to call back once there is a change in hardware state
... and many more

UEventChangeHandler: Abstract interface for implementing callback handler.
+ Method onUEventChange(String state)
The callback method that is called whenever there is a change in the registered hardware

HeadsetObserver: A specialised class inherited from GenericHardwareObserver that is dedicated for Headset status changes.
HDMIObserver: A specialised class inherited from GenericHardwareObserver that is dedicated for HDMI connection status changes.
DockObserver: A specialised class inherited from GenericHardwareObserver that is dedicated for Dock connection status changes.

HOW TO INTEGRATE MY LIBRARY TO YOUR APP?
This guide is for those developing app using Eclipse:
- Create or open your project in Eclipse
- Copy the ./lib/kernelswitchobserverlib.jar from the attachment archive to the libs folder of your project
- Study the code from example app, build your project
- If there are problem building, try adding the library in the second method:

- Right click your project -> Properties
- Navigate to tab Java Build Path -> Libraries -> Add External Jars -> Navigate to the kernelswitchobserverlib.jar file
- Navigate to tab Order and Export -> select kernelswitchobserverlib.jar

ACKNOWLEDGEMENT:
- Beta tester team of Screen Standby # Root as well as everyone used, tested and requested features for Screen Standby # Root
- Especially thanks to jjwatmyself for encouraging me digging more into the kernel (hope this helps solving your problem dude!)


CHANGELOG:

Oct 30 2012: Initial release of library + sample app

DOWNLOAD:

ObserverExampleApp.apk is the sample app ready to be used.
KernelSwitchObserver.zip contains the lib and source code of the sample app

You are free to include and distribute the library in any project however, crediting the original author is obligatory

nitephlight said:

this hack has truly made my day :good:

came across some interesting behavior on galaxy nexus running custom jb kernel (faux123): for switch omapfb-vsync hw state is detected as constantly switching, then observer app fc's.

due to forced vsync in jb kernel I'm assuming? (then again this device is dev playground for me)

Click to expand...

Click to collapse

He he, happy to see someone finally like it. Well, this library has a lot of potential and it is being used in my Screen Standby app to detect HDMI and various type of docks including those not being exposed in the Android SDK.
Love a Galaxy Nexus but then I got a preorder promotion for HTC One X.

That omapfb-vsync switch is probably being switched whenever the device renderer reached 30 fps or 60 fps. Interesting.

Sent from my MZ601 using Tapatalk 2