1ANDROID QEMUD SERVICES
2
3The docs/ANDROID-QEMUD.TXT document describes how clients running in the
4emulated system can communicate with the emulator through the 'qemud'
5multiplexing daemon.
6
7This document lists all services officially provided by the emulator to
8clients. Each service is identified by a unique name. There is no provision
9for versioning. Instead, if you need new features, create a new service
10with a slightly different name and modify clients to use it in the system
11image.
12
13
14"gsm" service:
15--------------
16
17   The GSM service provides a communication channel where GSM/GPRS AT commands
18   can be exchanged between the emulated system and an emulated modem.
19
20   The messages consist in un-framed character messages as they appear in a
21   regular AT command channel (i.e. terminated by \r\n most of the time).
22
23   There can be only 1 client talking to the modem, since the AT command
24   protocol does not allow for anything more complex.
25
26   Implementation: telephony/modem_driver.c
27   Since:          SDK 1.0
28
29"gps" service:
30--------------
31
32  The GPS service is used to broadcast NMEA 0183 sentences containing fix
33  information to all clients. The service doesn't listen to clients at all.
34
35  All sentences are un-framed and end with a \n character.
36
37  Implementation: android/gps.c
38  Since:          SDK 1.0
39
40
41"hw-control" / "control" service:
42---------------------
43
44  This service is named "control" in 1.0 and 1.1, and "hw-control"
45  in 1.5 and later releases of the SDK.
46
47  This service is used to allow the emulated system to control various aspects
48  of hardware emulation. The corresponding clients are in
49  hardware/libhardware_legacy in the Android source tree.
50
51  All messages use the optional framing described in ANDROID-QEMUD.TXT.
52  Only one client can talk with the service at any one time, but clients
53  quickly connect/disconnect to the service anyway.
54
55  Supported messages are:
56
57    1/ Client sends "power:light:brightness:<lightname>:<val>", where
58       <lightname> is the name of a light and <val> is an decimal value
59       between 0 (off) and 255 (brightest). Valid values for 'light' are:
60
61            lcd_backlight
62            keyboard_backlight
63            button_backlight
64
65       Currently, only 'lcd_backlight' is supported by the emulator.
66       Note that the brightness value doesn't scale linearly on physical
67       devices.
68
69    2/ Client sends "set_led_state:<color-rgb>:<on-ms>:<off-ms>" where
70       <color-rgb> is an 8-hexchar value describing an xRGB color, and
71       <on-ms> and <off-ms> are decimal values expressing timeout in
72       milliseconds.
73
74       This is used to modify the color of the notification LED on the
75       emulated phone as well as provide on/off timeouts for flashing.
76
77       cCrrently unsupported by the emulator.
78
79    3/ Client sends "vibrator:<timeout>", where <timeout> is a decimal value.
80       used to enable vibrator emulation for <timeout> milli-seconds.
81
82       Currently unsupported by the emulator.
83
84
85  Implementation: android/hw-control.c
86  Since:          SDK 1.0
87
88
89"sensors" service:
90------------------
91
92  This service is used for sensor emulation. All messages are framed and the
93  protocol is the following:
94
95    1/ Clients initially sends "list-sensors" and receives a single string
96       containing a decimal mask value. The value is a set of bit-flags
97       indicating which sensors are provided by the hardware emulation. The
98       bit flags are defined as:
99
100         bit 0:   accelerometer
101         bit 1:   compass
102         bit 2:   orientation
103         bit 3:   temperature
104
105    2/ Client sends "set-delay:<delay-ms>", where <delay-ms> is a decimal
106       string, to set the minimum delay in milliseconds between sensor event
107       reports it wants to receive.
108
109    3/ Client sends "wake", the service must immediately send back "wake" as
110       an answer. This is used to simplify parts of the client emulation.
111
112    4/ Client sends "set:<sensor-name>:<flag>", where <sensor-name> is the
113       name of one of the emulated sensors, and <flag> is either "0" or "1".
114       This is used to enable or disable the report of data from a given
115       emulated sensor hardware.
116
117       the list of valid <sensor-name> values is the following:
118
119           acceleration      : for the accelerometer
120           magnetic-field    : for the compass
121           orientation       : for the orientation sensor
122           temperature       : for the temperature sensor
123
124
125    5/ If at least one of the emulated sensors has been enabled with
126       "set:<name>:1", then the service should broadcast periodically the
127       state of sensors.
128
129       this is done by broadcasting a series of framed messages that look
130       like:
131
132           acceleration:<x>:<y>:<z>
133           magnetic-field:<x>:<y>:<z>
134           orientation:<azimuth>:<pitch>:<roll>
135           temperature:<celsius>
136           sync:<time_us>
137
138       Note that each line, corresponds to an independent framed message.
139       Each line, except the last one, is optional and should only be
140       produced if the corresponding sensor reporting has been enabled
141       through "set:<name>:1".
142
143       <x>, <y>, <z>, <azimuth>, <pitch>, <roll> and <celsius> are floating
144       point values written as strings with the "%g" printf formatting option.
145
146       The last 'sync' message is required to end the broadcast and contains
147       the current VM clock time in micro-seconds. The client will adjust it
148       internally to only care about differences between sensor broadcasts.
149
150       If reporting is disabled for all sensors, no broadcast message needs
151       to be sent back to clients.
152
153
154  Implementation: android/hw-sensors.c
155  Since:          SDK 1.5 (cupcake)
156
157
158"boot-properties" service:
159--------------------------
160
161  WARNING: These properties don't get set until init starts a service in
162  class "core" called "qemu-props". Other init services in class "core"
163  include servicemanager and vold.  If those processes read the property
164  (they probably don't right now), there is a small chance it has not been set yet.
165  Also, init services are started asynchronously, so there is no guarantee that
166  services started just after qemu-props will not run before qemu-props, and may
167  not see the new properties. This hasn't been an issue, but should probably
168  be cleaned up.
169
170  This service is used to set system properties in the emulated system at
171  boot time. It is invoked by the 'qemu-props' helper program that is invoked
172  by /system/etc/init.goldfish.rc. All messages are framed and the protocol
173  is the following:
174
175  1/ Clients sends the 'list' command
176
177  2/ Service answers by listing all system properties to set. One per
178     message with the following format:
179
180        <property-name>=<property-value>
181
182     Note that <property-value> is not zero-terminated.
183
184
185  3/ After sending all the properties, the service force-closes the
186     connection.
187
188  Implementation: android/boot-properties.c
189  Since:          SDK 1.XXX (donut)
190