blob: 64e0bb8285298a19ef875a546055c8a8b3442b92 [file] [log] [blame]
<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 --&gt; 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>