getsensor.r2py

"""
getsensor.r2py

Yanyan Zhuang, UBC, Canada

Change log:

v 0.0.1, 20150429 1630 YZ
  Using sensor lib code to get all _original_ data from a phone 
  Note that we need to convert Unicode strings to ASCII because
  namespace in Repy does not allow Unicode.

"""

# a small lib that makes `str`s from Unicode strings
# this is needed because namespace in Repy does not allow Unicode
unicode_scrubber = dy_import_module("unicode_scrubber.r2py")

sensorlib = dy_import_module("sensorlib.r2py")
port = sensorlib.get_connectionport()
sensor_socket = sensorlib.getconnection(port)

class BatteryNotFoundException(RepyException):
  """This exception gets raised when no battery is found on the device.
  """
  pass


class LocationNotFoundException(RepyException):
  """This exception gets raised when location sensor returns no results.
  """
  pass


class SIMNotFoundException(RepyException):
  """This exception gets raised when no SIM card is found on the device.
  In this case, no cellular information can be found.
  """
  pass


##################################################
############## battery interface  ################
##################################################

def get_battery_info():
  """
  <Purpose>
    Get battery data from a devices. Calls sensorlib.request_data(sensor_socket, 
    'readBatteryData', []). The battery information is returned as a dict.

  <Arguments>
    None

  <Exceptions>
    BatteryNotFoundException (descends from RepyException) when no battery 
    is found on the device. 

  <Side Effects>
    When BatteryNotFoundException is raised, the user of this method cannot
    get any battery information.

  <Resource Consumption>
    Battery information lookup. 

  <Returns>
    Battery info as a dict, such as {'status': 3, 'temperature': 257, 'level': 
    99, 'battery_present': True, 'plugged': 2, 'health': 2, 'voltage': 
    4186, 'technology': 'Li-ion'}.
    Return values for status: 1 - unknown; 2 - charging; 3 - discharging; 
      4 - not charging; 5 - full.
    Return values for temperature: in tenths of a degree Centigrade. E.g.,
      257 is 25.7 celcius.
    Return values for level: in percent.
    Return values for plugged: -1 - unknown; 0 - unplugged; 1 - power 
      source is an AC charger; 2 - power source is a USB port.
    Return values for health: 1 - unknown; 2 - good; 3 - overheat; 4 - dead;
      5 - over voltage; 6 - unspecified failure.
    Return values for voltage: in millivolts.
    
  """

  # start battery information lookup 
  sensorlib.request_data(sensor_socket, 'batteryStartMonitoring', [])

  # if no battery is present, then no battery information can be obtained
  if sensorlib.request_data(sensor_socket, 'batteryCheckPresent', []) == False:
    sensorlib.request_data(sensor_socket, 'batteryStopMonitoring', [])
    raise BatteryNotFoundException

  battery_info = sensorlib.request_data(sensor_socket, 'readBatteryData', [])
  sensorlib.request_data(sensor_socket, 'batteryStopMonitoring', [])

  return unicode_scrubber.scrub(battery_info)



##################################################
############## bluetooth interface  ##############
##################################################

def get_bluetooth_info():
  """
  <Purpose>
    Get bluetooth data from a devices. Calls sensorlib.request_data(sensor_socket, 
    'checkBluetoothState'/'bluetoothGetScanMode'/'bluetoothGetLocalName', []). 
    The bluetooth information is returned as a dict.

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    When bluetooth is not enabled, the user of this method cannot get any 
    bluetooth information.

  <Resource Consumption>
    Bluetooth information lookup. 

  <Returns>
    Bluetooth info as a dict, such as {'state': True, 'scan_mode': 3, 
    'local_name': 'GT-P1000'}.
    Return values for scan_mode: -1 - when Bluetooth is disabled; 
    0 - if non discoverable and non connectable; 1 - connectable 
    non discoverable; 3 - connectable and discoverable.
    
  """

  state = sensorlib.request_data(sensor_socket, 'checkBluetoothState', [])
  scan_mode = sensorlib.request_data(sensor_socket, 'bluetoothGetScanMode', [])
  local_name = sensorlib.request_data(sensor_socket, 'bluetoothGetLocalName', [])

  bluetooth_info = {'state': state, 'scan_mode': scan_mode, 'local_name': local_name}
  return unicode_scrubber.scrub(bluetooth_info)



##################################################
############## cellular interface  ###############
##################################################

def is_roaming():
  """
  <Purpose>
    Return if a phone is roaming (True/False).  Calls sensorlib.request_data(
    sensor_socket, 'checkNetworkRoaming', []). 

  <Arguments>
    None

  <Exceptions>
    SIMNotFoundException. 

  <Side Effects>
    When no SIM card is found, no cellular information can be obtained.

  <Resource Consumption>
    Lookup if phone is roaming. 

  <Returns>
    A boolean vaiable indicating if the phone is roaming. 
  """

  if sensorlib.request_data(sensor_socket, 'getSimState', []) == 'absent':
    # when no SIM card is found on the device, cellular information is
    # not meaningful
    raise SIMNotFoundException

  return sensorlib.request_data(sensor_socket, 'checkNetworkRoaming', [])  



def get_cellular_provider_info():
  """
  <Purpose>
    Get cellular provider info from a devices. Calls sensorlib.request_data(
    sensor_socket, 'getNetworkOperator'/'getNetworkOperatorName', []). The 
    cellular network information, current cellular operator code (MNC+MCC), 
    and operator name, is returned as a dict.

  <Arguments>
    None

  <Exceptions>
    SIMNotFoundException. 

  <Side Effects>
    When no SIM card is found, no cellular provider info can be obtained.

  <Resource Consumption>
    Cellular network provider information lookup. 

  <Returns>
    Cellular provider info as a dict, such as {‘network_operator’: 310260, 
    ‘network_operator_name’: ‘T-Mobile’}.
    
  """

  if sensorlib.request_data(sensor_socket, 'getSimState', []) == 'absent':
    # when no SIM card is found on the device, cellular information is
    # not meaningful
    raise SIMNotFoundException

  network_operator = sensorlib.request_data(sensor_socket, 
                                            'getNetworkOperator', [])
  network_operator_name = sensorlib.request_data(sensor_socket, 
                                            'getNetworkOperatorName', [])

  cellular_network_info = {'network_operator': network_operator, 
                           'network_operator_name': network_operator_name}
  return unicode_scrubber.scrub(cellular_network_info)



def get_cell_info():
  """
  <Purpose>
    Get cellular network info from a devices. Calls sensorlib.request_data(
    sensor_socket, 'getCellLocation'/'getNeighboringCellInfo'/'getNetworkType', 
    []). The cellular network information, current cellular cell ID, 
    neighboring cells, is returned as a dict.

  <Arguments>
    None

  <Exceptions>
    SIMNotFoundException. 

  <Side Effects>
    When no SIM card is found, no cellular information can be obtained.

  <Resource Consumption>
    Cellular network information lookup. 

  <Returns>
    Cellular info as a dict, such as {‘cellID’: {‘lac’: 32115, ‘cid’: 26742}, 
    ‘neighboring_cell’: [{‘rssi’: 11, ‘cid’: 26741}, {‘rssi’: 9, ‘cid’: 40151}, 
    {‘rssi’: 5, ‘cid’: 40153}]}.
    
  """

  if sensorlib.request_data(sensor_socket, 'getSimState', []) == 'absent':
    # when no SIM card is found on the device, cellular information is
    # not meaningful
    raise SIMNotFoundException

  # get details about cell ID, e.g., {‘lac’: 32115, ‘cid’: 26742}
  # cid = Cell ID, lac = location area code
  cellID = sensorlib.request_data(sensor_socket, 
                                            'getCellLocation', [])

  # get information about neighboring cells in a list, e.g.,
  # [{‘rssi’: 11, ‘cid’: 26741}, {‘rssi’: 9, ‘cid’: 40151}, 
  #  {‘rssi’: 5, ‘cid’: 40153}]
  neighboring_cell = sensorlib.request_data(sensor_socket, 
                                            'getNeighboringCellInfo', [])

  cellular_info = {'cellID': cellID, 'neighboring_cell': neighboring_cell}
  return unicode_scrubber.scrub(cellular_info)


def get_SIM_info():
  """
  <Purpose>
    Get SIM card info from a devices. Calls sensorlib.request_data(
    sensor_socket, 'getSimState'/'getSimOperator'/'getSimOperatorName'
    /'getSimCountryIso', []). The SIM card information, current SIM 
    card state, SIM card operator, SIM card operator name, SIM card
    country code, is returned as a dict.

  <Arguments>
    None

  <Exceptions>
    SIMNotFoundException. 

  <Side Effects>
    When no SIM card is found, no information can be obtained.

  <Resource Consumption>
    SIM card information lookup. 

  <Returns>
    SIM card info as a dict, such as {‘SIM_operator’: 310260, 
    ‘SIM_operator_name’: ‘’, ‘SIM_country_code’: ‘us’, ‘SIM_state’: 
    ‘ready’}.
    
  """

  SIM_state = sensorlib.request_data(sensor_socket, 'getSimState', [])
  
  if SIM_state == 'absent':
    # when no SIM card is found on the device, cellular information is
    # not meaningful
    raise SIMNotFoundException

  SIM_operator = sensorlib.request_data(sensor_socket, 
                                        'getSimOperator', [])
  SIM_operator_name = sensorlib.request_data(sensor_socket, 
                                             'getSimOperatorName', [])
  SIM_country_code = sensorlib.request_data(sensor_socket, 
                                            'getSimCountryIso', [])

  SIM_info = {'SIM_state': SIM_state, 'SIM_operator': SIM_operator, 
              'SIM_operator_name': SIM_operator_name, 
              'SIM_country_code': SIM_country_code}
  return unicode_scrubber.scrub(SIM_info)


def get_phone_info():
  """
  <Purpose>
    Get phone info from a devices. Calls sensorlib.request_data(
    sensor_socket, 'readPhoneState'/'getPhoneType'/'getNetworkType', 
    []). The phone information, current phone state, phone type, 
    network type, is returned as a dict.

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Phone information lookup. 

  <Returns>
    Phone info as a dict, such as {‘phone_state’: {‘incomingNumber’: 
    ‘’, ‘state’: ‘idle’}, ‘phone_type’: ‘gsm’, ‘network_type’: 'edge'}.
    When no SIM card is available, the phone info dict would be, e.g., 
    {‘phone_state’: {}, ‘phone_type’: ‘gsm’, ‘network_type’: 'unknown'}.
    
  """
  sensorlib.request_data(sensor_socket, 'startTrackingPhoneState', [])

  phone_state = sensorlib.request_data(sensor_socket, 
                                            'readPhoneState', [])
  phone_type = sensorlib.request_data(sensor_socket, 
                                            'getPhoneType', [])
  network_type = sensorlib.request_data(sensor_socket, 
                                            'getNetworkType', [])

  sensorlib.request_data(sensor_socket, 'stopTrackingPhoneState', [])
  
  phone_info = {'phone_state': phone_state, 'phone_type': phone_type, 
                'network_type': network_type}
  return unicode_scrubber.scrub(phone_info)


def get_cellular_signal_strengths():
  """
  <Purpose>
    Get the current signal strengths, in dictionary of gsm_signal_strength.
    Calls sensorlib.request_data(sensor_socket, 'readSignalStrengths', []).

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Current signal strengths lookup. 

  <Returns>
    Signal strengths info as a dict, such as {"gsm_signal_strength": 
    8, "evdo_ecio": -1, "gsm_bit_error_rate": -1, "cdma_ecio": -1, 
    "cdma_dbm": -1, "evdo_dbm": -1}.
  """

  sensorlib.request_data(sensor_socket, 'startTrackingSignalStrengths', [])
  cellular_signal_strengths = sensorlib.request_data(sensor_socket, 
                                                     'readSignalStrengths', [])
  sensorlib.request_data(sensor_socket, 'stopTrackingSignalStrengths', [])

  return unicode_scrubber.scrub(cellular_signal_strengths)


##################################################
############## location interface  ###############
##################################################

def get_location():
  """
  <Purpose>
    Get original location data from GPS or network or passive. Calls 
    sensorlib.request_data(sensor_socket, 'readLocation', []). The location
    information is returned as a dict, which is converted to ASCII 
    using unicode_scrubber.

  <Arguments>
    None

  <Exceptions>
    LocationNotFoundException (descends from RepyException) when no location 
    information is found. 

  <Side Effects>
    When LocationNotFoundException is raised, the user of this method needs 
    to try several times. If this still fails, then should try 
    get_lastknown_location().

  <Resource Consumption>
    GPS or network location lookup. 

  <Returns>
    location as a dict, such as {'bearing': 0, 'altitude': 0, 
    'time': x, 'longitude': x, 'provider': 'network', 'latitude': x, 
    'speed': 0, 'accuracy': x}.
  
  """

  # start the locating process 
  sensorlib.request_data(sensor_socket, 'startLocating', [])

  # try to read current location
  # note: readLocation call can timeout, or not responsive
  location_data = sensorlib.request_data(sensor_socket, 'readLocation', []) 

  # stop the locating process 
  sensorlib.request_data(sensor_socket, 'stopLocating', []) 

  if not location_data:
    raise LocationNotFoundException    
  assert len(location_data.keys()) == 1   # should return at only one provider

  # take the first key (because only one provider)
  provider = location_data.keys()[0]
  location = location_data[provider]

  # convert unicode format (u'longitude') to ASCII (longitude)
  # because Repy does not allow Unicode
  location = unicode_scrubber.scrub(location)
  return location


def get_lastknown_location():
  """
  <Purpose>
  Get original _last-known_ location data from GPS/network/passive. Calls 
  sensorlib.request_data(sensor_socket, 'getLastKnownLocation', []). The 
  location information is returned as a dict, which is converted to ASCII 
  using unicode_scrubber.

  <Arguments>
  None

  <Exceptions>
  LocationNotFoundException (descends from RepyException) when the returned
  location information is {'passive': None, 'network': None, 'gps': None}. 

  <Side Effects>
  None.

  <Resource Consumption>
  Lookup cached location information on the device. 

  <Returns>
  location as a dict with three keys: passive, network, and gps. Each key 
  value is a dict in the same format as the value returned by get_location().
  For example, {'passive': {'bearing': 0, 'altitude': 0, 'time': x, 
  'longitude': x, 'provider': 'network', 'latitude': s, 'speed': 0, 
  'accuracy': x}, 'network': {'bearing': 0, 'altitude': 0, 'time': x, 
  'longitude': x, 'provider': 'network', 'latitude': x, 'speed': 0, 
  'accuracy': x}, 'gps': None}

  """

  # start the locating process 
  sensorlib.request_data(sensor_socket, 'startLocating', [])

  # try to read the cached location
  location_data = sensorlib.request_data(sensor_socket, 'getLastKnownLocation', []) 

  # stop the locating process 
  sensorlib.request_data(sensor_socket, 'stopLocating', []) 
  assert len(location_data.keys()) >= 1   # should return at least one provider

  # check if location_data is {'passive': None, 'network': None, 'gps': None}
  for i in range(len(location_data.keys())):
    provider = location_data.keys()[i]
    location = location_data[provider]
    if location != None:
      break
  else:
    raise LocationNotFoundException

  # convert unicode format (u'longitude') to ASCII (longitude)
  location = unicode_scrubber.scrub(location_data)
  return location


def get_geolocation(latitude, longitude, max_results):
  """
  <Purpose>
    Obtain a list of addresses for the given latitude and longitude. Calls 
    sensorlib.request_data(sensor_socket, 'geocode', [latitude, longitude, 
    max_results]). The addresses information is returned as a dict, which 
    is converted to ASCII using unicode_scrubber.

  <Arguments>
    latitude (float): latitude of a location;
    longitude (float): longitude of a location;
    max_results (Integer): maximum number of results (normally =1).

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Geolocation lookup. 

  <Returns>
    Geolocation (address) as a list, such as [{'thoroughfare': 'Some 
    Street', 'locality': u'Some Town', 'sub_admin_area': 'Some Borough',
    'admin_area': 'Some City', 'feature_name': 'House Numbers', 
    'country_code': 'GB', 'country_name': 'United Kingdom', 
    'postal_code': 'ST1 1'}] .
  
  """

  address = sensorlib.request_data(sensor_socket, 'geocode', 
                                   [latitude, longitude, max_results])
  return unicode_scrubber.scrub(address)

  

##################################################
############### media interface  #################
##################################################


def microphone_record(filename, duration):
  """
  <Purpose>
    Records audio from the microphone and saves it as filename. Calls sensorlib.
    request_data(sensor_socket, 'recorderStartMicrophone', [filename]).

  <Arguments>
    filename (string): the audio file name that will be saved as (e.g., record.mp4);
    duration (Integer): the duration to record the audio.

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Record audio and save as a file on the device. 

  <Returns>
    None.
  """

  filepath = '/mnt/sdcard/Android/data/com.sensibility_testbed/files/sl4a/seattle/seattle_repy/v1/'
  targetpath = filepath + filename
  
  sensorlib.request_data(sensor_socket, 'recorderStartMicrophone', [targetpath])
  sleep(duration)
  
  sensorlib.request_data(sensor_socket, 'recorderStop', [])




def is_media_playing():
  """
  <Purpose>
  Return if media file is playing. (True/False). Calls sensorlib.
  request_data(sensor_socket, 'mediaIsPlaying', [])

  <Arguments>
  None.

  <Exceptions>
  None. 

  <Side Effects>
  None.

  <Resource Consumption>
  Lookup if media file is playing. 

  <Returns>
  A boolean vaiable indicating if a media file is playing on the device. 
  
  """

  # True or False
  return sensorlib.request_data(sensor_socket, 'mediaIsPlaying', [])



def get_media_play_info():
  """
  <Purpose>
  Return information on current media. Calls sensorlib.request_data(
  sensor_socket, 'mediaPlayInfo', [])

  <Arguments>
  None.

  <Exceptions>
  None. 

  <Side Effects>
  None.

  <Resource Consumption>
  Lookup media play information. 

  <Returns>
  media_play_info as a dict. 

  If no media file is loaded, the result is {'loaded': False, 'tag': 'default'}. 

  If there is a media file being played, the result is {'url': filepath, 
  'looping': False, 'tag': 'default', 'loaded': True, 'duration': 17100, 
  'position': 100, 'isplaying': True}. 
  
  If the media file is finished playing, the result is {'url': filepath, 
  'looping': False, 'tag': 'default', 'loaded': True, 'duration': 17100, 
  'position': 17020, 'isplaying': False}
  
  """

  # True or False
  media_play_info = sensorlib.request_data(sensor_socket, 'mediaPlayInfo', [])
  return unicode_scrubber.scrub(media_play_info)



##################################################
############## settings interface  ###############
##################################################

def get_mode_settings():
  """
  <Purpose>
    Get the current settings about mode (airplane mode, ringer silent mode, 
    vibrate mode), in dictionary of mode_settings. Calls sensorlib.
    request_data(sensor_socket, 'checkAirplaneMode'/'checkRingerSilentMode'/
    'getVibrateMode', []).

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Current mode settings lookup. 

  <Returns>
    Signal strengths info as a dict, such as {"airplane_mode": False, 
    "ringer_silent_mode": True, "vibrate_mode": {'ringer_vibrate': True, 
    'notification_vibrate': False}}.
  """

  airplane_mode = sensorlib.request_data(sensor_socket, 'checkAirplaneMode', []) 
  ringer_silent_mode = sensorlib.request_data(sensor_socket, 
                                              'checkRingerSilentMode', []) 

  # call to SL4A getVibrateMode: if the argument is true then query 
  # Ringer setting, else query Notification setting
  ringer_vibrate = sensorlib.request_data(sensor_socket, 
                                          'getVibrateMode', [True])
  notification_vibrate = sensorlib.request_data(sensor_socket, 
                                                'getVibrateMode', [False])
  vibrate_mode = {'ringer_vibrate': ringer_vibrate, 
                  'notification_vibrate': notification_vibrate}

  mode_settings = {'airplane_mode': airplane_mode, 'ringer_silent_mode':
                   ringer_silent_mode, 'vibrate_mode': vibrate_mode}
  return mode_settings



def get_screen_settings():
  """
  <Purpose>
    Get the current settings about screen (screen on/off, screen brightness, 
    screen timeout), in dictionary of screen_settings. Calls sensorlib.
    request_data(sensor_socket, 'checkScreenOn'/'getScreenBrightness'/
    'getScreenTimeout', []).

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Current screen settings lookup. 

  <Returns>
    Signal strengths info as a dict, such as {"screen_on": True, 
    "screen_brightness": 200, "screen_timeout": 60}.
  """

  screen_on = sensorlib.request_data(sensor_socket, 'checkScreenOn', []) 
  screen_brightness = sensorlib.request_data(sensor_socket, 
                                              'getScreenBrightness', []) 
  screen_timeout = sensorlib.request_data(sensor_socket, 
                                          'getScreenTimeout', [])

  screen_settings = {'screen_on': screen_on, 'screen_brightness':
                   screen_brightness, 'screen_timeout': screen_timeout}
  return screen_settings



def get_media_volume():
  """
  <Purpose>
    Get the current settings about media volume (current media volume, 
    maximum media volume), in dictionary of media_volume. Calls sensorlib.
    request_data(sensor_socket, 'getMediaVolume'/'getMaxMediaVolume', []).

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Current media volume settings lookup. 

  <Returns>
    Signal strengths info as a dict, such as {"media_volume": xx, 
    "max_media_volume": xxx}.
  """

  media_volume = sensorlib.request_data(sensor_socket, 'getMediaVolume', []) 
  max_media_volume = sensorlib.request_data(sensor_socket, 
                                              'getMaxMediaVolume', []) 
 
  media_volume = {'media_volume': media_volume, 'max_media_volume':
                     max_media_volume}
  return media_volume



def get_ringer_volume():
  """
  <Purpose>
    Get the current settings about ringer volume (current ringer volume, 
    maximum ringer volume), in dictionary of ringer_volume. Calls sensorlib.
    request_data(sensor_socket, 'getRingerVolume'/'getMaxRingerVolume', []).

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Current ringer volume settings lookup. 

  <Returns>
    Signal strengths info as a dict, such as {"ringer_volume": xx, 
    "max_ringer_volume": xxx}.
  """

  ringer_volume = sensorlib.request_data(sensor_socket, 'getRingerVolume', []) 
  max_ringer_volume = sensorlib.request_data(sensor_socket, 
                                              'getMaxRingerVolume', []) 
 
  ringer_volume = {'ringer_volume': ringer_volume, 'max_ringer_volume':
                     max_ringer_volume}
  return ringer_volume



##################################################
############## sensors interface  ################
##################################################

def start_sensing(sensor_number, delay_time):
  """
  <Purpose>
    Starts recording sensor data to be available for polling. 
    Calls sensorlib.request_data(sensor_socket, 'startSensingTimed', 
    []).

  <Arguments>
    sensor_number (Integer): 1 = All, 2 = Accelerometer, 
                             3 = Magnetometer and 4 = Light 
    delay_time (Integer): Minimum time between readings in ms. 

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Starts recording sensor data. 

  <Returns>
    None.
  """

  sensorlib.request_data(sensor_socket, 'startSensingTimed', 
                         [sensor_number, delay_time])



def stop_sensing():
  """
  <Purpose>
    Stops recording sensor data to be available for polling. Calls 
    sensorlib.request_data(sensor_socket, 'stopSensing', []).

  <Arguments>
    None. 

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Stops recording sensor data. 

  <Returns>
    None.
  """

  sensorlib.request_data(sensor_socket, 'stopSensing', [])

  

def get_sensors():
  """
  <Purpose>
    Get the most recently recorded sensor data (accelerometer, 
    magnetic and orientation), in dictionary of sensors. Calls 
    sensorlib.request_data(sensor_socket, 'readSensors', []).

  <Arguments>
    None

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Current sensors (accelerometer, magnetic and orientation) lookup. 

  <Returns>
    Sensors as a dict, such as {"time": 1.386305361412E9, "roll": 
    -0.034543427079916, "zforce": 9.959879, "yforce": -0.842759, 
    "yMag": 164.9375, "xMag": -3.1875, "azimuth": 0.005331491399556398, 
    "xforce": 0.3439138, "zMag": -67.75, "pitch": 0.08443046659231186, 
    "accuracy":3}.
  """

  sensors = sensorlib.request_data(sensor_socket, 'readSensors', [])
  return unicode_scrubber.scrub(sensors)


def get_sensors_accuracy():
  """
  <Purpose>
    Get the most recently received accuracy value. Calls 
    sensorlib.request_data(sensor_socket, 'sensorsGetAccuracy', []).

  <Arguments>
    None. 

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Look up sensor accuracy. 

  <Returns>
    Returns the most recently received accuracy value, e.g., 3 (highest accuracy).
  """

  return sensorlib.request_data(sensor_socket, 'sensorsGetAccuracy', [])



def get_light():
  """
  <Purpose>
    Get the most recently received light value. Calls 
    sensorlib.request_data(sensor_socket, 'sensorsGetLight', []).

  <Arguments>
    None. 

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Look up light value. 

  <Returns>
    TODO: what's the return value looks like?
  """

  return sensorlib.request_data(sensor_socket, 'sensorsGetLight', [])



def get_acceleration():
  """
  <Purpose>
    Get the most recently received accelerometer value. Calls 
    sensorlib.request_data(sensor_socket, 'sensorsReadAccelerometer', 
    []).

  <Arguments>
    None. 

  <Exceptions>
    ValueError. 

  <Side Effects>
    None.

  <Resource Consumption>
    Look up accelerometer value. 

  <Returns>
    A list of floats [(acceleration on the) X axis, Y axis, Z axis], 
    e.g., [0.3830723, -0.8036005, 10.036493].
  """

  try:
    data = sensorlib.request_data(sensor_socket, 
                                'sensorsReadAccelerometer', [])
  except ValueError, e:
    raise ValueError(str( e ) + " Data was '" + str(data) + "'")

  return data


def get_magnetic_field():
  """
  <Purpose>
    Get the most recently received magnetic field value. Calls 
    sensorlib.request_data(sensor_socket, 'sensorsReadMagnetometer', 
    []).

  <Arguments>
    None. 

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Look up magnetic field value. 

  <Returns>
    A list of floats [(magnetic field value for) X axis, Y axis, Z 
    axis], e.g., [29.5, 206.875, -119.625].
  """

  return sensorlib.request_data(sensor_socket, 
                                'sensorsReadMagnetometer', [])



def get_orientation():
  """
  <Purpose>
    Get the most recently received orientation value. Calls 
    sensorlib.request_data(sensor_socket, 'sensorsReadOrientation', 
    []).

  <Arguments>
    None. 

  <Exceptions>
    None. 

  <Side Effects>
    None.

  <Resource Consumption>
    Look up orientation value. 

  <Returns>
    A list of doubles [azimuth, pitch, roll], e.g., 
    [-0.17154279351234436, 0.080450139939785, -0.03844258934259415].
  """

  return sensorlib.request_data(sensor_socket,
    'sensorsReadOrientation', [])


##################################################
########### text to speech interface  ############
##################################################


def is_tts_speaking():
  """
  <Purpose>
  Return if text to speech (tts) is currently in progress (True/False). Calls 
  sensorlib.request_data(sensor_socket, 'ttsIsSpeaking', []).

  <Arguments>
  None

  <Exceptions>
  None. 

  <Side Effects>
  None.

  <Resource Consumption>
  Lookup if tts is currently in progress. 

  <Returns>
  A boolean vaiable indicating if tts is currently in progress on the device. 
  
  """

  # True or False
  return sensorlib.request_data(sensor_socket, 'ttsIsSpeaking', [])



def tts_speak(message):
  """
  <Purpose>
  Speaks the provided message via text to speech (tts). Calls 
  sensorlib.request_data(sensor_socket, 'ttsSpeak', [message]).

  <Arguments>
  message (string): the message to speak.

  <Exceptions>
  None. 

  <Side Effects>
  None.

  <Resource Consumption>
  Text to speech speaks the provided message. 

  <Returns>
  None. 
  
  """

  sensorlib.request_data(sensor_socket, 'ttsSpeak', [message])


##################################################
############## WiFi interface  ###################
##################################################

def is_wifi_enabled():
  """
  <Purpose>
  Return if WiFi is enabled on this device (True/False). Calls 
  sensorlib.request_data(sensor_socket, 'checkWifiState', []).

  <Arguments>
  None

  <Exceptions>
  None. 

  <Side Effects>
  None.

  <Resource Consumption>
  Lookup if WiFi is enabled on the device. 

  <Returns>
  A boolean vaiable indicating if WiFi is enabled on the device. 
  
  """

  # True or False
  return sensorlib.request_data(sensor_socket, 'checkWifiState', [])


def get_wifi_connection_info():
  """
  <Purpose>
  Return information about the WiFi network currently connected to. Calls 
  sensorlib.request_data(sensor_socket, 'wifiGetConnectionInfo', []). 

  <Arguments>
  None

  <Exceptions>
  None. 

  <Side Effects>
  None.

  <Resource Consumption>
  Lookup WiFi connection information on the device. 

  <Returns>
  wifi_conn as a dict, and is returned as a dict of this format:
  {
    "ssid": network SSID (string),
    "bssid": network BSSID, i.e. MAC address (string),
    "rssi": received signal strength in dBm (negative int),
    "supplicant_state": current WPA association state (string),
    "link_speed": link speed in MBps (int),
    "mac_address": this device's WiFi interface MAC (string),
    XXX "ip_address": this device's IP address (XXX int, byte quadruples reversed!),
    XXX "network_id": XXX (int),
    "hidden_ssid": True if the SSID is not broadcast (bool)
  }
  """

  wifi_conn = sensorlib.request_data(sensor_socket, 'wifiGetConnectionInfo', [])

  # convert unicode format to ASCII
  return unicode_scrubber.scrub(wifi_conn)


def do_wifi_scan():
  """
  <Purpose>
  Return WiFi connection info on this device. Calls 
  sensorlib.request_data(sensor_socket, 'wifiGetScanResults', []).

  <Arguments>
  None

  <Exceptions>
  None. 

  <Side Effects>
  None.

  <Resource Consumption>
  Scan the WiFi network from the device. 

  <Returns>
  WiFi scan results wifi_data as a HUGE dict of this format, 
  with one dict for each network found:
  {
    "ssid": network SSID (string),
    "bssid": network BSSID, i.e. MAC address (string),
    "frequency": frequency in MHz (int),
    "level": received signal strength in dBm (negative int),
    "capabilities": security features supported by the network (string)
  }

  """

  sensorlib.request_data(sensor_socket, 'wifiStartScan', []) 
  wifi_data = sensorlib.request_data(sensor_socket, 'wifiGetScanResults', [])
  
  # we do not need to stop scan (it stops itself after scan is done)
  # convert unicode format to ASCII
  return unicode_scrubber.scrub(wifi_data)