aboutsummaryrefslogtreecommitdiffstats
path: root/docs
diff options
context:
space:
mode:
Diffstat (limited to 'docs')
-rw-r--r--docs/ANDROID-QEMUD-SERVICES.TXT155
-rw-r--r--docs/ANDROID-QEMUD.TXT18
2 files changed, 169 insertions, 4 deletions
diff --git a/docs/ANDROID-QEMUD-SERVICES.TXT b/docs/ANDROID-QEMUD-SERVICES.TXT
new file mode 100644
index 0000000..24636e5
--- /dev/null
+++ b/docs/ANDROID-QEMUD-SERVICES.TXT
@@ -0,0 +1,155 @@
+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)
diff --git a/docs/ANDROID-QEMUD.TXT b/docs/ANDROID-QEMUD.TXT
index 6415a47..1364553 100644
--- a/docs/ANDROID-QEMUD.TXT
+++ b/docs/ANDROID-QEMUD.TXT
@@ -92,7 +92,7 @@ Since the "cupcake" platform, this works as follows:
connect:<service>:<id>
- where <service> is the service name, and <id> is a 4-hexchar string
+ where <service> is the service name, and <id> is a 2-hexchar string
giving the allocated channel index for the client.
@@ -181,9 +181,19 @@ This is documented here since this explains some subtleties in the
implementation code of android/hw-qemud.c
The old scheme also used a serial port to allow the daemon and the emulator
-to communicate. Besides, the same multiplexing protocol was used to pass
-messages through multiple channels. However, several other differences
-exist, best illustrated by the following graphics:
+to communicate. However, the multiplexing protocol swaps the position of
+'channel' and 'length' in the header:
+
+ offset size description
+
+ 0 4 4-char hex string giving the payload size
+
+ 4 2 2-char hex string giving the destination or
+ source channel
+
+ 6 n the message payload
+
+Several other differences, best illustrated by the following graphics:
emulator <==serial==> qemud <-+--> /dev/socket/qemud_gsm <--> GSM client
|