David Turner | 791d861 | 2009-04-13 18:01:32 -0700 | [diff] [blame] | 1 | ANDROID QEMUD SERVICES |
| 2 | |
| 3 | The docs/ANDROID-QEMUD.TXT document describes how clients running in the |
| 4 | emulated system can communicate with the emulator through the 'qemud' |
| 5 | multiplexing daemon. |
| 6 | |
| 7 | This document lists all services officially provided by the emulator to |
| 8 | clients. Each service is identified by a unique name. There is no provision |
| 9 | for versioning. Instead, if you need new features, create a new service |
| 10 | with a slightly different name and modify clients to use it in the system |
| 11 | image. |
| 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) |
David 'Digit' Turner | 318e4f2 | 2009-05-25 18:01:03 +0200 | [diff] [blame] | 156 | |
| 157 | |
| 158 | "boot-properties" service: |
| 159 | -------------------------- |
| 160 | |
| 161 | This service is used to set system properties in the emulated system at |
| 162 | boot time. It is invoked by the 'qemu-props' helper program that is invoked |
| 163 | by /system/etc/init.goldfish.rc. All messages are framed and the protocol |
| 164 | is the following: |
| 165 | |
| 166 | 1/ Clients sends the 'list' command |
| 167 | |
| 168 | 2/ Service answers by listing all system properties to set. One per |
| 169 | message with the following format: |
| 170 | |
| 171 | <property-name>=<property-value> |
| 172 | |
| 173 | Note that <property-value> is not zero-terminated. |
| 174 | |
| 175 | |
| 176 | 3/ After sending all the properties, the service force-closes the |
| 177 | connection. |
| 178 | |
| 179 | Implementation: android/boot-properties.c |
| 180 | Since: SDK 1.XXX (donut) |