1 <html devsite> 2 <head> 3 <title>Implementing Emergency Affordance</title> 4 <meta name="project_path" value="/_project.yaml" /> 5 <meta name="book_path" value="/_book.yaml" /> 6 </head> 7 <body> 8 <!-- 9 Copyright 2017 The Android Open Source Project 10 11 Licensed under the Apache License, Version 2.0 (the "License"); 12 you may not use this file except in compliance with the License. 13 You may obtain a copy of the License at 14 15 http://www.apache.org/licenses/LICENSE-2.0 16 17 Unless required by applicable law or agreed to in writing, software 18 distributed under the License is distributed on an "AS IS" BASIS, 19 WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. 20 See the License for the specific language governing permissions and 21 limitations under the License. 22 --> 23 24 25 26 <p>All mobile devices sold in India from the 1st January 2017 will need to 27 provide a panic button to meet Indian Department of Telecommunications (DoT) 28 requirements.</p> 29 30 <p>An Emergency Affordance feature has been developed to provide a reference 31 implementation of the panic button for Android devices to address these 32 regulatory requirements. This will be enabled by default in future Android 33 releases but must be patched into existing builds. Currently, this feature is 34 exclusively targeted at devices that are sold in the Indian market but can be 35 included on all devices sold throughout the world as the feature has no effect 36 outside India.</p> 37 38 <h2 id="examples-source">Examples and source</h2> <p>The Emergency Affordance 39 feature is implemented in the Android Open Source Project (AOSP) <a 40 href="https://android.googlesource.com/platform/frameworks/base/">frameworks/base</a> 41 project. It is available in the master branch and will be enabled by default in 42 future Android releases.</p> 43 44 <p>This feature is currently available in the following branches and commits. 45 This information is provided to enable device manufacturers to easily patch the 46 necessary changes into their existing builds. Device manufacturers wanting to 47 implement the AOSP reference emergency affordance feature can cherry-pick the 48 commits from the applicable branches into their own builds.</p> 49 50 <p class="table-caption" id="cherry-picks-reference-implementation"> 51 <strong>Table 1.</strong> Cherry-picks for AOSP reference emergency affordance feature</p> 52 <table> 53 <tbody> 54 <tr> 55 <th scope="col">Branch</th> 56 <th scope="col">Commits</th> 57 </tr> 58 <tr> 59 <td>master</td> 60 <td><a href="https://android-review.googlesource.com/#/c/284723/">e0c3c66</a> 61 Added Emergency affordance feature<br> 62 <a href="https://android-review.googlesource.com/#/c/287188/">42a4338</a> 63 Added translations for emergency action string<br> 64 <a href="https://android-review.googlesource.com/#/c/286858/">4df8d64</a> 65 Fixed an issue where the emergency affordance would show on tablets 66 </td> 67 </tr> 68 <tr> 69 <td>nougat-dev</td> 70 <td><a href="https://android-review.googlesource.com/#/c/284761/">e6680d9</a> 71 Added Emergency affordance feature<br> 72 <a href="https://android-review.googlesource.com/#/c/287293/">95e1865</a> 73 Added translations for emergency action string<br> 74 <a href="https://android-review.googlesource.com/#/c/286953/">a70bb89</a> 75 Fixed an issue where the emergency affordance would show on tablets 76 </td> 77 </tr> 78 <tr> 79 <td>marshmallow-dev</td> 80 <td><a href="https://android-review.googlesource.com/#/c/284624/">cd22634</a> 81 Added Emergency affordance feature<br> 82 <a href="https://android-review.googlesource.com/#/c/286937/">13f51c6</a> 83 Added translations for emergency action string<br> 84 <a href="https://android-review.googlesource.com/#/c/287241/">6531666</a> 85 Fixed an issue where the emergency affordance would show on tablets 86 </td> 87 </tr> 88 <tr> 89 <td class="style1">lollipop-mr1-dev</td> 90 <td><a href="https://android-review.googlesource.com/#/c/284743/">5fbc86b</a> 91 Added Emergency affordance feature<br> 92 <a href="https://android-review.googlesource.com/#/c/287382/">1b60879</a> 93 Added translations for emergency action string<br> 94 <a href="https://android-review.googlesource.com/#/c/286856/">d74366f</a> 95 Fixed an issue where the emergency affordance would show on tablets 96 </td> 97 98 </tr> 99 </tbody> 100 </table> 101 102 <h2 id="implementation">Implementation</h2> <p>The Emergency Affordance feature 103 makes no changes to the APIs exposed through the Android SDK. When enabled and 104 activated, it provides two triggers that can initiate an emergency call to 105 112, which is the single emergency number to be used in India and mandated by 106 the DoT regulations.<br> An emergency call is initiated by either:</p> <ul> 107 <li>Long pressing the <strong>EMERGENCY</strong> button on the lockscreen 108 (Figure 1)</li> <li>Tapping the <strong>Emergency</strong> option from the 109 <em>Global Action Menu</em> (Figure 2), accessed by long pressing the power 110 key.</li> </ul> 111 112 <table> 113 <tr> 114 <td width="50%"><img src="/devices/tech/connect/images/emergency-button.png" alt="emergency 115 button" width="246" id="emergency-button" /> 116 <p class="img-caption"> 117 <strong>Figure 1.</strong> Long press the <strong>EMERGENCY</strong> button, 118 highlighted with a red box, on the lock screen.</p></td> 119 <td width="50%"><img src="/devices/tech/connect/images/emergency-option.png" alt="emergency 120 option" width="247" id="emergency-option" /> 121 <p class="img-caption"> 122 <strong>Figure 2.</strong> Tap the <strong>Emergency</strong> action item on 123 the <em>Global Action Menu</em>.</p></td> 124 </tr> 125 </table> 126 127 <p>This feature introduces the following internal components:</p> <ul> 128 <li>EmergencyAffordanceManager 129 <pre class="devsite-click-to-copy"> 130 frameworks/base/core/java/com/android/internal/policy/EmergencyAffordanceManager.java 131 </pre> 132 </li> 133 <li>EmergencyAffordanceService 134 <pre class="devsite-click-to-copy"> 135 frameworks/base/services/core/java/com/android/server/emergency/EmergencyAffordanceService.java 136 </pre> 137 </li> 138 </ul> 139 140 <h3 id="EmergencyAffordanceManager">EmergencyAffordanceManager</h3> <p>The 141 EmergencyAffordanceManager provides an internal API to use the Emergency 142 Affordance feature. It provides methods for initiating the emergency call and 143 querying at runtime if the feature should be enabled.</p> <ul> <li><code>void 144 performEmergencyCall()</code> - Initiates an emergency call</li> 145 <li><code>boolean needsEmergencyAffordance()</code> - Determines if the feature 146 should be active</li> </ul> <p>The feature may be permanently disabled at build 147 time by changing the <code>EmergencyAffordanceManager.ENABLED</code> constant 148 to <code>false</code>. This will cause <code>needsEmergencyAffordance()</code> 149 to always return false and prevent the <code>EmergencyAffordanceService</code> 150 from starting.</p> 151 152 <h3 id="EmergencyAffordanceService">EmergencyAffordanceService</h3> <p>The 153 <code>EmergencyAffordanceService</code> is a system service that monitors the 154 Mobile Country Code (MCC) of all the detected cellular networks and the MCC of 155 the installed SIM cards. If any of the installed SIM cards or detected cellular 156 networks have a MCC matching one of India's MCCs (404,405) then the feature 157 will be enabled. This means the feature can be enabled in India even if no SIM 158 card is present. It is assumed the mobile network will permit registration for 159 emergency calls even without a SIM card installed. The feature will remain 160 enabled until a non-India SIM is installed and none of the detected networks 161 have a matching MCC.</p> 162 163 <p>The following resources and settings affect the behavior of the Emergency 164 Affordance feature. If the config type is "Resource" it is an internal resource 165 defined in <code>frameworks/base/core/res/res/values/config.xml</code>. If 166 config type is "Setting" it is a setting stored in the systems settings 167 provider.</p> 168 169 <p class="table-caption" id="settings-affecting behavior"> 170 <strong>Table 2.</strong> Settings affecting behavior of emergency affordance 171 feature</p> 172 <table> 173 <tbody> 174 <tr> 175 <th scope="col">Config Type</th> 176 <th scope="col">Name</th> 177 <th scope="col">Description</th> 178 </tr> 179 <tr> 180 <td>Resource</td> 181 <td>config_emergency_call_number</td> 182 <td>The phone number that is automatically dialed when the emergency call is 183 initiated.<br> 184 Type: String<br> 185 Default: 112</td> 186 </tr> 187 <tr> 188 <td>Resource</td> 189 <td>config_emergency_mcc_codes</td> 190 <td>An array of Integers listing the MCCs the feature should be active in.<br> 191 Type: Array of Integers<br> 192 Default: {404,405}</td> 193 </tr> 194 <tr> 195 <td>Setting</td> 196 <td>emergency_affordance_number</td> 197 <td>Global setting override with the number to call with the emergency 198 affordance. This will only have an effect on debuggable build images (ie. build 199 type is userdebug or eng). This is intended only for testing.<br> 200 Type: String<br> 201 Default: unset</td> 202 </tr> 203 <tr> 204 <td>Setting </td> 205 <td>force_emergency_affordance</td> 206 <td>Global setting, whether the emergency affordance should be shown regardless 207 of device state. This is intended only for testing.<br> 208 Type: Boolean (1 or 0)<br> 209 Default: unset --> 0</td> 210 </tr> 211 </tbody> 212 </table> 213 214 <h3 id="112">Enable emergency calls to '112'</h3> <p>The emergency affordance 215 feature connects the call using the emergency dialer so that the call can be 216 connected when the lock screen is active. The emergency dialer only connects 217 calls to the list of numbers provided by the Radio Interface Layer (RIL), 218 through the system property 'ril.ecclist', when no SIM is installed and 219 '<code>ril.ecclist<<i>SimSlotNumber</i>></code>' when a SIM is inserted 220 and <code><i><SimSlotNumber></i></code> is the slot ID of the default 221 subscriber.<br> Device manufacturers using the emergency affordance feature 222 must ensure that devices in India always enable 112 as an emergency number in 223 the RIL.</p> 224 225 <h2 id="validation">Validation</h2> <p>While testing, on a debuggable build, 226 the number that is called can be changed with the following command:</p> 227 <pre class="devsite-terminal devsite-click-to-copy"> 228 adb shell settings put global emergency_affordance_number <var>NUMBER_TO_CALL</var> 229 </pre> 230 231 <p>Although this setting can be set on a normal user build, it will be ignored. 232 To actually connect the call the number must be in the list of emergency 233 numbers provided by the RIL. This can be temporarily set using the following 234 command executed from a root shell on a userdebug device:</p> 235 <pre class="devsite-terminal devsite-click-to-copy"> 236 setprop ril.ecclist "$(getprop ril.ecclist),<var>NUMBER_TO_CALL</var>" 237 </pre> 238 239 <p>The following command can also be used to force the Emergency Affordance 240 feature to be enabled even in the absence of an Indian mobile network being 241 detected or an Indian SIM card being inserted.</p> 242 <pre class="devsite-terminal devsite-click-to-copy"> 243 adb shell settings put global force_emergency_affordance 1 244 </pre> 245 246 <p>During testing it is recommend that at least the following cases are 247 tested.</p> 248 249 <ul> <li>Once activated, long pressing the <strong>EMERGENCY</strong> button on 250 the lockscreen (Figure 1) initiates a call the specified emergency number.</li> 251 <li>Once activated, the <strong>Emergency</strong> item on the Global Action 252 Menu is present and that tapping it initiates a call to the specified emergency 253 number.</li> <li>The feature <b>is not</b> <b>activated</b> in the absence of a 254 detected Indian Mobile Network with a non-India SIM card installed.</li> 255 <li>The feature <b>is activated</b> on the device whilst an Indian SIM card is 256 installed, regardless of the detected mobile networks.</li> <li>The feature 257 <b>is</b> <b>activated</b> on the device whilst an in the presence of a Indian 258 Mobile Network regardless of the SIM cards installed.</li> </ul> 259 260 <p>If a device includes supports multiple SIM cards then testing should ensure 261 that the SIM MCC detection works correctly in each SIM slot. The feature is not 262 governed by Android compatibility, so there are no CTS tests for it.</p> 263 264 <h2 id="faq">Frequently Asked Questions</h2> 265 266 <h5 id="q-112">Q. The emergency number '112' has not been commissioned yet in 267 India, should it still be used?</h5> 268 269 <p>'112' is the number that will be used in India as the Public Safety 270 Answering Point (PSAP) as defined by the Integrated Emergency Communications 271 and Response Systems (IECRS). Until the PSAP is commissioned all calls to '112' 272 will be routed to the existing '100' emergency number.</p> 273 274 <h5 id="q-other-triggers">Q. What about other triggers like "triple" pressing 275 the power button?</h5> <p>Device manufacturer may choose to implement 276 additional triggers. Triple tapping the hardware power button is also an 277 approved trigger action by the India DoT. However, this trigger is not 278 supported in the AOSP reference implementation as a number of other widely used 279 applications use the power button gestures, including repeated tapping of the 280 power button. These applications might interfere with the emergency dialer, or 281 the user may accidentally trigger the panic button while trying to trigger 282 actions in these applications.</p> 283 284 </body> 285 </html> 286
