FMRX Enabler for N900 hardware
=================================================
(c) 2009 Martin Grimme  <martin.grimme@gmail.com>


This is a D-Bus service for enabling the FM receiver on the Nokia N900.
The FM receiver sits on the Bluetooth chip and I2C communication is disabled
by default on the N900 to save battery. The FM receiver can only be powered up
after activating the I2C bus.

This service handles enabling the I2C bus and FM receiver on application
request and automatically disable both when not in use anymore.

This service listens on the D-Bus system bus and there is only one method:

 request()

This method has to be called repeatedly by applications while using the receiver
to ensure that it doesn't get powered down.
The method returns a tuple containing a return code and the path to the device
file.

Return code is one of:

 - OK = 0:
     Everything is OK and the receiver can be used
 - BLUETOOTH_FAILURE = 1:
     There was an error powering up the Bluetooth chip
 - I2C_FAILURE = 2:
     There was an error powering up the I2C bus
 - DRIVER_FAILURE = 3:
     There was an error loading the driver module
 - TUNER_FAILURE = 4:
     There was an error turning on the FM tuner

Example in Python (C and other languages work similar):

  import dbus
  bus = dbus.SystemBus()
  obj = bus.get_object("de.pycage.FMRXEnabler", "/de/pycage/FMRXEnabler")
  enabler = dbus.Interface(obj, "de.pycage.FMRXEnabler")
  retval, device = enabler.request()


VERY IMPORTANT NOTE:
###############################################################################
  The correct way to get sound out of the FM radio is by capturing from the
  PGA Line and playing back. Never ever use the filter bypass mixers to make
  the sound hearable. Unfiltered low frequencies can damage the speakers!

  See the sample script below for the appropriate mixer settings.
###############################################################################



There is also a simple shell script provided for controlling the FM receiver as
root. Non-root applications must use the V4L2 interface of the driver.

Usage:
  fmradio-tool <frequency in KHz> 

Example:
  # fmradio-tool 103300
  Tuning into 103300


---
Many thanks to Nokia for providing the HCI command sequences for powering
up/down the I2C bus!

