docs/ANDROID-QEMUD-SERVICES.TXT - emulator-unstable-refactoring - Git at Google

 ANDROID QEMUD SERVICES

 The docs/ANDROID-QEMUD.TXT document describes how clients running in the
 emulated system can communicate with the emulator through the 'qemud'
 multiplexing daemon.

 This document lists all services officially provided by the emulator to
 clients. Each service is identified by a unique name. There is no provision
 for versioning. Instead, if you need new features, create a new service
 with a slightly different name and modify clients to use it in the system
 image.


 "gsm" service:
 --------------

    The GSM service provides a communication channel where GSM/GPRS AT commands
    can be exchanged between the emulated system and an emulated modem.

    The messages consist in un-framed character messages as they appear in a
    regular AT command channel (i.e. terminated by \r\n most of the time).

    There can be only 1 client talking to the modem, since the AT command
    protocol does not allow for anything more complex.

    Implementation: telephony/modem_driver.c
    Since:          SDK 1.0

 "gps" service:
 --------------

   The GPS service is used to broadcast NMEA 0183 sentences containing fix
   information to all clients. The service doesn't listen to clients at all.

   All sentences are un-framed and end with a \n character.

   Implementation: android/gps.c
   Since:          SDK 1.0


 "hw-control" / "control" service:
 ---------------------

   This service is named "control" in 1.0 and 1.1, and "hw-control"
   in 1.5 and later releases of the SDK.

   This service is used to allow the emulated system to control various aspects
   of hardware emulation. The corresponding clients are in
   hardware/libhardware_legacy in the Android source tree.

   All messages use the optional framing described in ANDROID-QEMUD.TXT.
   Only one client can talk with the service at any one time, but clients
   quickly connect/disconnect to the service anyway.

   Supported messages are:

     1/ Client sends "power:light:brightness:<lightname>:<val>", where
        <lightname> is the name of a light and <val> is an decimal value
        between 0 (off) and 255 (brightest). Valid values for 'light' are:

             lcd_backlight
             keyboard_backlight
             button_backlight

        Currently, only 'lcd_backlight' is supported by the emulator.
        Note that the brightness value doesn't scale linearly on physical
        devices.

     2/ Client sends "set_led_state:<color-rgb>:<on-ms>:<off-ms>" where
        <color-rgb> is an 8-hexchar value describing an xRGB color, and
        <on-ms> and <off-ms> are decimal values expressing timeout in
        milliseconds.

        This is used to modify the color of the notification LED on the
        emulated phone as well as provide on/off timeouts for flashing.

        cCrrently unsupported by the emulator.

     3/ Client sends "vibrator:<timeout>", where <timeout> is a decimal value.
        used to enable vibrator emulation for <timeout> milli-seconds.

        Currently unsupported by the emulator.


   Implementation: android/hw-control.c
   Since:          SDK 1.0


 "sensors" service:
 ------------------

   This service is used for sensor emulation. All messages are framed and the
   protocol is the following:

     1/ Clients initially sends "list-sensors" and receives a single string
        containing a decimal mask value. The value is a set of bit-flags
        indicating which sensors are provided by the hardware emulation. The
        bit flags are defined as:

          bit 0:   accelerometer
          bit 1:   compass
          bit 2:   orientation
          bit 3:   temperature

     2/ Client sends "set-delay:<delay-ms>", where <delay-ms> is a decimal
        string, to set the minimum delay in milliseconds between sensor event
        reports it wants to receive.

     3/ Client sends "wake", the service must immediately send back "wake" as
        an answer. This is used to simplify parts of the client emulation.

     4/ Client sends "set:<sensor-name>:<flag>", where <sensor-name> is the
        name of one of the emulated sensors, and <flag> is either "0" or "1".
        This is used to enable or disable the report of data from a given
        emulated sensor hardware.

        the list of valid <sensor-name> values is the following:

            acceleration      : for the accelerometer
            magnetic-field    : for the compass
            orientation       : for the orientation sensor
            temperature       : for the temperature sensor


     5/ If at least one of the emulated sensors has been enabled with
        "set:<name>:1", then the service should broadcast periodically the
        state of sensors.

        this is done by broadcasting a series of framed messages that look
        like:

            acceleration:<x>:<y>:<z>
            magnetic-field:<x>:<y>:<z>
            orientation:<azimuth>:<pitch>:<roll>
            temperature:<celsius>
            sync:<time_us>

        Note that each line, corresponds to an independent framed message.
        Each line, except the last one, is optional and should only be
        produced if the corresponding sensor reporting has been enabled
        through "set:<name>:1".

        <x>, <y>, <z>, <azimuth>, <pitch>, <roll> and <celsius> are floating
        point values written as strings with the "%g" printf formatting option.

        The last 'sync' message is required to end the broadcast and contains
        the current VM clock time in micro-seconds. The client will adjust it
        internally to only care about differences between sensor broadcasts.

        If reporting is disabled for all sensors, no broadcast message needs
        to be sent back to clients.


   Implementation: android/hw-sensors.c
   Since:          SDK 1.5 (cupcake)


 "boot-properties" service:
 --------------------------

   WARNING: These properties don't get set until init starts a service in
   class "core" called "qemu-props". Other init services in class "core"
   include servicemanager and vold.  If those processes read the property
   (they probably don't right now), there is a small chance it has not been set yet.
   Also, init services are started asynchronously, so there is no guarantee that
   services started just after qemu-props will not run before qemu-props, and may
   not see the new properties. This hasn't been an issue, but should probably
   be cleaned up.

   This service is used to set system properties in the emulated system at
   boot time. It is invoked by the 'qemu-props' helper program that is invoked
   by /system/etc/init.goldfish.rc. All messages are framed and the protocol
   is the following:

   1/ Clients sends the 'list' command

   2/ Service answers by listing all system properties to set. One per
      message with the following format:

         <property-name>=<property-value>

      Note that <property-value> is not zero-terminated.


   3/ After sending all the properties, the service force-closes the
      connection.

   Implementation: android/boot-properties.c
   Since:          SDK 1.XXX (donut)
	ANDROID QEMUD SERVICES

	The docs/ANDROID-QEMUD.TXT document describes how clients running in the
	emulated system can communicate with the emulator through the 'qemud'
	multiplexing daemon.

	This document lists all services officially provided by the emulator to
	clients. Each service is identified by a unique name. There is no provision
	for versioning. Instead, if you need new features, create a new service
	with a slightly different name and modify clients to use it in the system
	image.


	"gsm" service:
	--------------

	The GSM service provides a communication channel where GSM/GPRS AT commands
	can be exchanged between the emulated system and an emulated modem.

	The messages consist in un-framed character messages as they appear in a
	regular AT command channel (i.e. terminated by \r\n most of the time).

	There can be only 1 client talking to the modem, since the AT command
	protocol does not allow for anything more complex.

	Implementation: telephony/modem_driver.c
	Since: SDK 1.0

	"gps" service:
	--------------

	The GPS service is used to broadcast NMEA 0183 sentences containing fix
	information to all clients. The service doesn't listen to clients at all.

	All sentences are un-framed and end with a \n character.

	Implementation: android/gps.c
	Since: SDK 1.0


	"hw-control" / "control" service:
	---------------------

	This service is named "control" in 1.0 and 1.1, and "hw-control"
	in 1.5 and later releases of the SDK.

	This service is used to allow the emulated system to control various aspects
	of hardware emulation. The corresponding clients are in
	hardware/libhardware_legacy in the Android source tree.

	All messages use the optional framing described in ANDROID-QEMUD.TXT.
	Only one client can talk with the service at any one time, but clients
	quickly connect/disconnect to the service anyway.

	Supported messages are:

	1/ Client sends "power:light:brightness:<lightname>:<val>", where
	<lightname> is the name of a light and <val> is an decimal value
	between 0 (off) and 255 (brightest). Valid values for 'light' are:

	lcd_backlight
	keyboard_backlight
	button_backlight

	Currently, only 'lcd_backlight' is supported by the emulator.
	Note that the brightness value doesn't scale linearly on physical
	devices.

	2/ Client sends "set_led_state:<color-rgb>:<on-ms>:<off-ms>" where
	<color-rgb> is an 8-hexchar value describing an xRGB color, and
	<on-ms> and <off-ms> are decimal values expressing timeout in
	milliseconds.

	This is used to modify the color of the notification LED on the
	emulated phone as well as provide on/off timeouts for flashing.

	cCrrently unsupported by the emulator.

	3/ Client sends "vibrator:<timeout>", where <timeout> is a decimal value.
	used to enable vibrator emulation for <timeout> milli-seconds.

	Currently unsupported by the emulator.


	Implementation: android/hw-control.c
	Since: SDK 1.0


	"sensors" service:
	------------------

	This service is used for sensor emulation. All messages are framed and the
	protocol is the following:

	1/ Clients initially sends "list-sensors" and receives a single string
	containing a decimal mask value. The value is a set of bit-flags
	indicating which sensors are provided by the hardware emulation. The
	bit flags are defined as:

	bit 0: accelerometer
	bit 1: compass
	bit 2: orientation
	bit 3: temperature

	2/ Client sends "set-delay:<delay-ms>", where <delay-ms> is a decimal
	string, to set the minimum delay in milliseconds between sensor event
	reports it wants to receive.

	3/ Client sends "wake", the service must immediately send back "wake" as
	an answer. This is used to simplify parts of the client emulation.

	4/ Client sends "set:<sensor-name>:<flag>", where <sensor-name> is the
	name of one of the emulated sensors, and <flag> is either "0" or "1".
	This is used to enable or disable the report of data from a given
	emulated sensor hardware.

	the list of valid <sensor-name> values is the following:

	acceleration : for the accelerometer
	magnetic-field : for the compass
	orientation : for the orientation sensor
	temperature : for the temperature sensor


	5/ If at least one of the emulated sensors has been enabled with
	"set:<name>:1", then the service should broadcast periodically the
	state of sensors.

	this is done by broadcasting a series of framed messages that look
	like:

	acceleration:<x>:<y>:<z>
	magnetic-field:<x>:<y>:<z>
	orientation:<azimuth>:<pitch>:<roll>
	temperature:<celsius>
	sync:<time_us>

	Note that each line, corresponds to an independent framed message.
	Each line, except the last one, is optional and should only be
	produced if the corresponding sensor reporting has been enabled
	through "set:<name>:1".

	<x>, <y>, <z>, <azimuth>, <pitch>, <roll> and <celsius> are floating
	point values written as strings with the "%g" printf formatting option.

	The last 'sync' message is required to end the broadcast and contains
	the current VM clock time in micro-seconds. The client will adjust it
	internally to only care about differences between sensor broadcasts.

	If reporting is disabled for all sensors, no broadcast message needs
	to be sent back to clients.


	Implementation: android/hw-sensors.c
	Since: SDK 1.5 (cupcake)


	"boot-properties" service:
	--------------------------

	WARNING: These properties don't get set until init starts a service in
	class "core" called "qemu-props". Other init services in class "core"
	include servicemanager and vold. If those processes read the property
	(they probably don't right now), there is a small chance it has not been set yet.
	Also, init services are started asynchronously, so there is no guarantee that
	services started just after qemu-props will not run before qemu-props, and may
	not see the new properties. This hasn't been an issue, but should probably
	be cleaned up.

	This service is used to set system properties in the emulated system at
	boot time. It is invoked by the 'qemu-props' helper program that is invoked
	by /system/etc/init.goldfish.rc. All messages are framed and the protocol
	is the following:

	1/ Clients sends the 'list' command

	2/ Service answers by listing all system properties to set. One per
	message with the following format:

	<property-name>=<property-value>

	Note that <property-value> is not zero-terminated.


	3/ After sending all the properties, the service force-closes the
	connection.

	Implementation: android/boot-properties.c
	Since: SDK 1.XXX (donut)