| <html devsite> |
| <head> |
| <title>Implementing Emergency Affordance</title> |
| <meta name="project_path" value="/_project.yaml" /> |
| <meta name="book_path" value="/_book.yaml" /> |
| </head> |
| <body> |
| <!-- |
| Copyright 2017 The Android Open Source Project |
| |
| Licensed under the Apache License, Version 2.0 (the "License"); |
| you may not use this file except in compliance with the License. |
| You may obtain a copy of the License at |
| |
| http://www.apache.org/licenses/LICENSE-2.0 |
| |
| Unless required by applicable law or agreed to in writing, software |
| distributed under the License is distributed on an "AS IS" BASIS, |
| WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied. |
| See the License for the specific language governing permissions and |
| limitations under the License. |
| --> |
| |
| |
| |
| <p>All mobile devices sold in India from January 1st, 2017 must provide a |
| panic button to meet Indian Department of Telecommunications (DoT) requirements. |
| To address these regulatory requirements, Android includes a reference |
| implementation of the Emergency Affordance feature to enable a panic button on |
| Android devices.</p> |
| |
| <p>This feature is enabled by default in Android 8.0 and higher releases, but |
| must be patched into existing builds of earlier releases. Currently, this |
| feature is exclusively targeted at devices sold in the Indian market but can be |
| included on all devices sold throughout the world as the feature has no effect |
| outside India.</p> |
| |
| <h2 id="examples-source">Examples and source</h2> |
| <p>The Emergency Affordance feature is implemented in the Android Open Source |
| Project (AOSP) |
| <a href="https://android.googlesource.com/platform/frameworks/base/">frameworks/base</a> |
| project. It is available in the master branch and is enabled by default in |
| Android 8.0 and higher releases.</p> |
| |
| <p>This feature is currently available in the following branches and commits. |
| This information is provided to enable device manufacturers to easily patch the |
| necessary changes into their existing builds. Device manufacturers wanting to |
| implement the AOSP reference emergency affordance feature can cherry-pick the |
| commits from the applicable branches into their own builds.</p> |
| |
| <p class="table-caption" id="cherry-picks-reference-implementation"> |
| <strong>Table 1.</strong> Cherry-picks for AOSP reference emergency affordance |
| feature</p> |
| <table> |
| <tbody> |
| <tr> |
| <th scope="col">Branch</th> |
| <th scope="col">Commits</th> |
| </tr> |
| <tr> |
| <td>master</td> |
| <td><a href="https://android-review.googlesource.com/#/c/284723/">e0c3c66</a> |
| Added Emergency affordance feature<br> |
| <a href="https://android-review.googlesource.com/#/c/287188/">42a4338</a> |
| Added translations for emergency action string<br> |
| <a href="https://android-review.googlesource.com/#/c/286858/">4df8d64</a> |
| Fixed an issue where the emergency affordance would show on tablets |
| </td> |
| </tr> |
| <tr> |
| <td>nougat-dev</td> |
| <td><a href="https://android-review.googlesource.com/#/c/284761/">e6680d9</a> |
| Added Emergency affordance feature<br> |
| <a href="https://android-review.googlesource.com/#/c/287293/">95e1865</a> |
| Added translations for emergency action string<br> |
| <a href="https://android-review.googlesource.com/#/c/286953/">a70bb89</a> |
| Fixed an issue where the emergency affordance would show on tablets |
| </td> |
| </tr> |
| <tr> |
| <td>marshmallow-dev</td> |
| <td><a href="https://android-review.googlesource.com/#/c/284624/">cd22634</a> |
| Added Emergency affordance feature<br> |
| <a href="https://android-review.googlesource.com/#/c/286937/">13f51c6</a> |
| Added translations for emergency action string<br> |
| <a href="https://android-review.googlesource.com/#/c/287241/">6531666</a> |
| Fixed an issue where the emergency affordance would show on tablets |
| </td> |
| </tr> |
| <tr> |
| <td>lollipop-mr1-dev</td> |
| <td><a href="https://android-review.googlesource.com/#/c/284743/">5fbc86b</a> |
| Added Emergency affordance feature<br> |
| <a href="https://android-review.googlesource.com/#/c/287382/">1b60879</a> |
| Added translations for emergency action string<br> |
| <a href="https://android-review.googlesource.com/#/c/286856/">d74366f</a> |
| Fixed an issue where the emergency affordance would show on tablets |
| </td> |
| |
| </tr> |
| </tbody> |
| </table> |
| |
| <h2 id="implementation">Implementation</h2> |
| <p>The Emergency Affordance feature makes no changes to the APIs exposed through |
| the Android Software Development Kit (SDK). When enabled and activated, the |
| feature provides two triggers that can initiate an emergency call to 112, which |
| is the single emergency number to be used in India and mandated by the Indian |
| DoT regulations.</p> |
| <p>An emergency call is initiated by either:</p> |
| |
| <div style="width:80%"> |
| <table> |
| <tr> |
| <th width="50%">Long pressing the <strong>EMERGENCY</strong> button<br> on the |
| lockscreen</th> |
| <th width="50%">Tapping the <strong>Emergency</strong> option<br> in the |
| Global Action Menu</th> |
| </tr> |
| <tr> |
| <td style="text-align: center"> |
| <img src="/devices/tech/connect/images/emergency-button.png" alt="emergency |
| button"> |
| <figcaption><strong>Figure 1.</strong> <strong>EMERGENCY</strong> button on |
| lockscreen.</figcaption></td> |
| <td style="text-align: center"> |
| <img src="/devices/tech/connect/images/emergency-option.png" alt="emergency |
| option"> |
| <figcaption><strong>Figure 2.</strong> <strong>Emergency</strong> action on |
| Global Action Menu (accessed by long pressing the power key). |
| </figcaption></td> |
| </tr> |
| </table> |
| </div> |
| |
| <p>This feature introduces the following internal components:</p> |
| <ul> |
| <li>EmergencyAffordanceManager |
| <pre class="devsite-click-to-copy"> |
| frameworks/base/core/java/com/android/internal/policy/EmergencyAffordanceManager.java |
| </pre> |
| </li> |
| <li>EmergencyAffordanceService |
| <pre class="devsite-click-to-copy"> |
| frameworks/base/services/core/java/com/android/server/emergency/EmergencyAffordanceService.java |
| </pre> |
| </li> |
| </ul> |
| |
| <h3 id="EmergencyAffordanceManager">EmergencyAffordanceManager</h3> |
| <p>The EmergencyAffordanceManager provides an internal API to use the Emergency |
| Affordance feature. It provides methods for initiating the emergency call and |
| querying at runtime if the feature should be enabled.</p> |
| <ul> |
| <li><code>void performEmergencyCall()</code>. Initiates an emergency call.</li> |
| <li><code>boolean needsEmergencyAffordance()</code>. Determines if the feature |
| should be active.</li> |
| </ul> |
| |
| <p>The feature may be permanently disabled at build time by changing the |
| <code>EmergencyAffordanceManager.ENABLED</code> constant to <code>false</code>. |
| This will cause <code>needsEmergencyAffordance()</code> to always return false |
| and prevent the <code>EmergencyAffordanceService</code> from starting.</p> |
| |
| <h3 id="EmergencyAffordanceService">EmergencyAffordanceService</h3> |
| <p>The <code>EmergencyAffordanceService</code> is a system service that monitors |
| the Mobile Country Code (MCC) of all the detected cellular networks and the MCC |
| of the installed SIM cards. If any of the installed SIM cards or detected |
| cellular networks have a MCC matching one of India's MCCs (404 or 405) then the |
| feature will be enabled. This means the feature can be enabled in India even if |
| no SIM card is present. It is assumed the mobile network will permit |
| registration for emergency calls even without a SIM card installed. The feature |
| will remain enabled until a non-India SIM is installed and none of the detected |
| networks have a matching MCC.</p> |
| |
| <p>The following resources and settings affect the behavior of the Emergency |
| Affordance feature. If the config type is:</p> |
| <ul> |
| <li><strong>Resource</strong>, it is an internal resource defined in |
| <code>frameworks/base/core/res/res/values/config.xml</code>.</li> |
| <li><strong>Setting</strong>, it is a setting stored in the systems settings |
| provider.</li> |
| </ul> |
| |
| <p class="table-caption" id="settings-affecting behavior"> |
| <strong>Table 2.</strong> Settings affecting behavior of emergency affordance |
| feature</p> |
| <table> |
| <tbody> |
| <tr> |
| <th scope="col">Config Type</th> |
| <th scope="col">Name</th> |
| <th scope="col">Description</th> |
| </tr> |
| <tr> |
| <td>Resource</td> |
| <td>config_emergency_call_number</td> |
| <td>The phone number that is automatically dialed when the emergency call is |
| initiated.<br> |
| Type: String<br> |
| Default: 112</td> |
| </tr> |
| <tr> |
| <td>Resource</td> |
| <td>config_emergency_mcc_codes</td> |
| <td>An array of Integers listing the MCCs the feature should be active in.<br> |
| Type: Array of Integers<br> |
| Default: {404,405}</td> |
| </tr> |
| <tr> |
| <td>Setting</td> |
| <td>emergency_affordance_number</td> |
| <td>Global setting override with the number to call with the emergency |
| affordance. This will only have an effect on debuggable build images (ie. build |
| type is userdebug or eng). This is intended only for testing.<br> |
| Type: String<br> |
| Default: unset</td> |
| </tr> |
| <tr> |
| <td>Setting</td> |
| <td>force_emergency_affordance</td> |
| <td>Global setting, whether the emergency affordance should be shown regardless |
| of device state. This is intended only for testing.<br> |
| Type: Boolean (1 or 0)<br> |
| Default: unset --> 0</td> |
| </tr> |
| </tbody> |
| </table> |
| |
| <h3 id="112">Enable emergency calls to 112</h3> |
| <p>The emergency affordance feature connects the call using the emergency |
| dialer so that the call can be connected when the lock screen is active. The |
| emergency dialer connects calls only to the list of numbers provided by the |
| Radio Interface Layer (RIL) through the system property:</p> |
| |
| <ul> |
| <li><code>ril.ecclist</code> when no SIM is installed.</li> |
| <li><code>ril.ecclist<var>SimSlotNumber</var></code> when a SIM is inserted |
| and <code><var>SimSlotNumber</var></code> is the slot ID of the default |
| subscriber.</li> |
| </ul> |
| |
| <p>Device manufacturers using the emergency affordance feature must ensure that |
| devices in India always enable 112 as an emergency number in the RIL.</p> |
| |
| <h2 id="validation">Validation</h2> |
| <p>While testing on a debuggable build, the number that is called can be changed |
| with the following command:</p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| adb shell settings put global emergency_affordance_number <var>NUMBER_TO_CALL</var> |
| </pre> |
| |
| <p>Although this setting can be set on a normal user build, it will be ignored. |
| To actually connect the call the number must be in the list of emergency |
| numbers provided by the RIL. This can be temporarily set using the following |
| command executed from a root shell on a userdebug device:</p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| setprop ril.ecclist "$(getprop ril.ecclist),<var>NUMBER_TO_CALL</var>" |
| </pre> |
| |
| <p>The following command can also be used to force the Emergency Affordance |
| feature to be enabled even in the absence of an Indian mobile network being |
| detected or an Indian SIM card being inserted.</p> |
| <pre class="devsite-terminal devsite-click-to-copy"> |
| adb shell settings put global force_emergency_affordance 1 |
| </pre> |
| |
| <p>At a minimum, it is recommend to test the following cases:</p> |
| |
| <ul> |
| <li>Once activated, long pressing the <strong>EMERGENCY</strong> button on |
| the lockscreen (Figure 1) initiates a call to the specified emergency number. |
| </li> |
| <li>Once activated, the <strong>Emergency</strong> item on the Global Action |
| Menu is present and tapping it initiates a call to the specified emergency |
| number.</li> |
| <li>The feature <strong>is not activated</strong> in the absence of a |
| detected Indian Mobile Network with a non-India SIM card installed.</li> |
| <li>The feature <strong>is activated</strong> on the device when an Indian SIM |
| card is installed, regardless of the detected mobile networks.</li> |
| <li>The feature <strong>is activated</strong> on the device in the presence of |
| an Indian Mobile Network, regardless of the SIM cards installed.</li> |
| </ul> |
| |
| <p>If a device includes supports multiple SIM cards, testing should ensure |
| that the SIM MCC detection works correctly in each SIM slot. The Emergency |
| Affordance feature is not governed by Android compatibility, so there are no |
| Compatibility Test Suite (CTS) tests for it.</p> |
| |
| <h2 id="faq">Frequently Asked Questions</h2> |
| |
| <h5 id="q-112">Q. The emergency number 112 has not been commissioned yet in |
| India. Should it still be used?</h5> |
| <p>112 is the number that will be used in India as the Public Safety Answering |
| Point (PSAP) as defined by the Integrated Emergency Communications and Response |
| Systems (IECRS). Until the PSAP is commissioned, all calls to 112 will be routed |
| to the existing 100 emergency number (though this is the responsibility of the |
| carrier, not Android).</p> |
| |
| <h5 id="q-other-triggers">Q. What about other triggers such as triple-pressing |
| the power button?</h5> |
| <p>Device manufacturers may choose to implement additional triggers. However, |
| while the Indian DoT approves triple-tapping the hardware power button, this |
| trigger is <strong>not supported</strong> in the AOSP reference implementation |
| as some widely used applications (e.g. the Camera app) use power button gestures |
| that include repeated tapping of the power button. Such applications might |
| interfere with the emergency dialer or the user may accidentally trigger the |
| panic button while trying to trigger actions in these applications.</p> |
| |
| </body> |
| </html> |