README.md

7SIM

Control SIM cards based on your schedule.

7SIM is an Android privileged app for custom ROMs, aimed to give users more fine-grained control over their SIM cards.

Technically, this app is an extension of the built-in Settings app. It leverages hidden Android APIs in order to control SIM card states, etc. By adhering to the Android standardized security concerns and restrictions, this app require no root access at all. This guarantees long-term maintainability and compatibility across different Android versions.

If you're a ROM maintainer and wish to ship this app as part of your ROM, see For ROM Maintainers section.

If you're a normal user willing to give it a try, see Installation section.

Benefits

• Manually activate/deactivate individual SIM cards with just two taps
• or automate this process using the integrated scheduler
• Enhance the "Do Not Disturb" mode
• Extend battery life

Screenshots

Features

• Support of Android 10.0 (Q) and above
• Unlocked capability to turn on/off SIM cards on devices (mainly the old ones) that lacked this feature (note that it may not work on some devices due to OEM limitations. Refer to FAQ for troubleshooting)
• Add an arbitrary number of schedules per SIM card
• Automatically supply the PIN code provided by you to unlock the SIM card
• Automatically detect ongoing call and postpone SIM card deactivation
• Tinted SIM card icons
• Real-Time SIM list updates
• Dark mode support
• "Material You" color palette everywhere (including app icon)
• Compatibility with AOSP build system (see For ROM Maintainers section)
• Rootless
• Persistent SIM card disabled state across boots
• Hide app icon option (Why it's grayed out?)
• Tile to launch the app from the Quick Settings panel
• Available in 40 languages upon release

Installation

1. Ensure you're using a custom ROM running on Android 10.0 (Q) or newer

Maybe you want to know Why the app cannot be installed on non-custom ROMs, official LineageOS, etc.?

2. Download the latest release.apk from the release page

Tip

We highly encourage to always verify the checksums of downloaded files. This precautionary measure ensures data integrity, and confirms that the files originated from a trustworthy source since this app is signed with the public Android platform signature.

3. Install the app as you would with any other application

4. You're all set!

For troubleshooting, refer to the FAQ section.

Getting Updates

Currently, the updating process follows the same steps as the Installation process.

Important

You CANNOT update this application using files from the release page if the "Updates" preference is grayed out.

For this see Why the "Updates" option is grayed out?

Help & Feedback

• Getting Updates
• Quirks You Should Know About
• FAQ
• Q&A

FAQ

Tip

If you haven't found an answer to your question, or need further information or clarification, please don't hesitate to ask in Q&A.

1. How do I know if my device has the capability to turn on/off a SIM card out-of-the-box?

1. Open the SIM details page for a SIM within the built-in Settings app
2. If you observe the To disable this SIM, remove the SIM card message in the footer, then your device DOES NOT have the capability to turn on/off SIM cards out-of-the-box
3. Otherwise, the device is capable of disabling pSIMs and/or eSIMs via the Use SIM on/off toggle switch, which is expected to be positioned at the top of the SIM details page.

If your device DOES NOT has the capability to turn on/off SIM cards out-of-the-box, then the 7SIM app will attempt achieve this by controlling the SIM power state. See also Quirks You Should Know About.

2. Does the app need to always run in the background?

No, this app doesn't create any long-lived services and does all the work on-demand. The app is woken up by the Android OS only when the time comes to process weekly repeat schedules.

3. Why is the "Show app icon" option is grayed out?

The "Show app icon" option is available only if the app is considered by the Android OS as a system application, i.e., it's either pre-installed in the device's system partition as part of the ROM, or be deliberately placed in the /system partition by the user.

See Convert the application into a system app section.

4. How many SIM cards are supported?

The Android OS provides "out-of-the-box" support for devices with Tri SIM capabilities, that is up to 3 SIM cards are supported.

5. Would support for eSIM (embedded-SIM) be implemented soon?

It's problematic for now, since the eSIM technology isn't widely adopted, and most Android devices (especially the mid-range ones) and mobile carriers sill don't provide such support.

6. What's the meaning of the error: SIM request failed (code "errCode")?

Depending on the Android version, the following modem-related errors are expected to happen on devices that DO NOT have the capability to turn on/off SIM cards out-of-the-box.

When running on Android 12.0 (S) or newer versions:

• errCode = 2 Failed to connect to the modem to make the SIM power state request. This may happen if the modem has an error. As per Android's manual, the user may want to make the request again later.

• errCode = 3 Failed to connect to the SIM to make the power state request. This may happen if the SIM has been removed. As per Android's manual, the user may want to make the request again later.

• errorCode = 4 Failed to instruct the modem to make the SIM power state. As per Android's manual, this may happen if the modem version does not support synchronous power.

  So far, this error is likely to occur on devices running on non-Qualcomm Snapdragon SoCs.

When running on versions prior to Android 12.0 (S):

• errCode = 8 SIM card I/O error. SIM card is present but faulty.
• errorCode = 9 SIM Card is present but not usable due to carrier restrictions.
• errorCode = -2 This error is equivalent to errorCode = 4 on Android 12.0 (S) or newer versions.

7. Why the app cannot be installed on non-custom ROMs, official LineageOS, etc.?

Because this app is signed with the public Android platform signature. All privileged apps must be signed with the same key used for signing the ROM. Any attempts to install this app on a stock ROM from popular smartphone brands such as Samsung, Huawei, Xiaomi, etc., will fail due to the certificate mismatch.

Custom ROMs like LineageOS, GrapheneOS, /e/OS, etc., also use a private key for signing their official builds.

Although individual custom ROM maintainers may sign the ROM using a private key, this is very rare and uncommon practice. For this reason, the app is distributed as a standalone APK, as it's expected to install on any custom ROM running on Android 10.0 (Q) or newer ever built.

If you're using a custom ROM that's signed with maintainer's private key, then you can ask them to include the app in the next OTA release. Direct them to the For ROM Maintainers section. Alternatively, consider switching to a different ROM, preferably from a different maintainer.

8. Why the "Updates" option is grayed out?

The "Update" option may be grayed out due to the app being signed with the maintainer's private keys. You cannot update this application using files from the release page as they are signed with the public Android platform signature. Therefore, you can get updates of this app only from your ROM maintainer with OTA updates.

9. Where's my SIM PIN code stored?

The SIM PIN codes are stored on disk after being encrypted using the newly generated secret key bound to your screen lock credentials, such as PIN/password/pattern or biometric (Android 10 only). The secret key will be stored in the Hardware-backed Keystore, and the user authentication will take place for every use of the key. This is the highest security level you can have on an Android device.

⚠️ Warning

If "None" or "Swipe" is set as your screen lock method, the default (known to everyone) key will be used to encrypt your SIM PIN codes. Although the decryption will require physical access to the device, this is the lowest possible level of protection, as the data can be easily accessed (especially on a rooted device), if your phone is lost or stolen.

See also Irreversibly Invalidated SIM PIN Codes

For ROM Maintainers

If you're a ROM maintainer and wish to integrate this app into your ROM, follow these steps:

1. Choose one of the following methods to add the app to the Android sources:
   • As a remote project via Local Manifests:

     <remote name="iusmac" fetch="https://github.com/iusmac" revision="14.0-dev" />
     <project path="packages/apps/7SIM" name="7SIM" remote="iusmac" />

   • As an in-tree package within the device tree directory:

     git clone --depth=1 -b 14.0-dev https://github.com/iusmac/7SIM.git

   • Or better — as Git Submodule/Subtree:

     git submodule add --depth=1 -b 14.0-dev https://github.com/iusmac/7SIM.git

     OR

     git subtree add --prefix=7SIM https://github.com/iusmac/7SIM.git 14.0-dev --squash

2. Add app module to a product makefile (e.g., device.mk):

   PRODUCT_PACKAGES += \
       7SIM
   

3. That's all! The next time when you'll build the ROM, the Soong build system will pick up the app sources and compile it alongside other bundled with the Android platform apps (e.g., Dialer, SMS, Settings, etc.). The app will be installed in the /system_ext/priv-app directory.

Warning

Before shipping the app to users, please, test assiduously all provided features on your Android device to ensure they work as expected.

Important

If you sign the ROM with your own private keys, users WILL NOT be able to get app updates from the release page due to certificate mismatch, since this app is signed with the public Android platform signature. The "Updates" option is expected to be grayed out.

Therefore, all future app updates can only be rolled out with OTA updates.

Tip

Instead of rebuilding the entire ROM for critical bug fixes or new features, consider, inviting users to get updates from the release page, or make your own build of the app using the Soong Build System, and distribute the APK to your users. The app will be installed in the /data partition.

Build From Source

Using Gradle Build Tool

Requirements:

• Android 14 SDK or newer with access to hidden APIs and internal resources

Tip

If you don't have one already, you can use our own android.jar that you can find at prebuilts/jars/. Replace it with the stock one in the Android SDK directory.

• Java 17+

Build process:

As mentioned above, the 7SIM app is an extension of the built-in Settings app. In order to have the same UI, and also write less code, it relies on some parts of the SettingsLib package that you can download automatically using this script:

./SettingsLib/fetch.sh

The dependencies will be placed in the same directory where the script is. You can rerun this script in the future to update the dependencies from the SettingsLib package.

Then, use Android Studio or command line tool to build the APK:

./gradlew clean build

Once the build is finished, you should have the .apk files in the build/outputs/apk/debug/ and build/outputs/apk/release/ directories respectively.

If you want to sign the app with your own private key that you've used to sign the ROM, see the keystore.properties file.

To enable debug logging on releases with R8, see Debug Opt-in Logging section.

Using Soong Build System

Requirements:

• Android 14 and later source code base

Note

The app stability is not guaranteed when building against the upstream source code base.

Build process:

Prepare the environment tools, then use the following command to build the APK only:

m 7SIM

You may have to build the ROM from source at least once before running this command. But you're free to experiment.

Once the build is finished, you will be shown the path of the .apk file.

To enable debug logging, edit the BuildConfig.java file.

Development

As mentioned above, the 7SIM is a privileged app that leverages Android hidden APIs and accesses internal resources. During the development, you'll most likely run across the Cannot resolve symbol (or similar) error in Android Studio or standalone LSP servers. For this, you need to replace the android.jar in the Android SDK directory with our own version that you can find at prebuilts/jars/.

There shouldn't be problems when building with Gradle as the library will be picked up via compileOnly.

Debug Opt-in Logging

The debug logging on releases with R8 can be enabled as follows:

./gradlew -PreleaseDebugOpt=1 build

OR

RELEASE_DEBUG_OPT=1 ./gradlew build

You can either use 1 for true or the word true.

Runtime Debugging

The debug logging can be enabled during runtime as follows:

setprop service.7sim.debug true

OR persist the property to start capturing logs on very early boot process:

setprop persist.service.7sim.debug true

Important

You need su privileges to run the above commands, or edit the /system/build.prop file via recovery as an alternative.

The app needs to be restarted to pick up new changes.

---

The device's capability to disable / re-enable a physical (non-eUICC) SIM, even if availability is configured by the platform, and instead opt for slot power control as a fallback method to toggle SIM card states, can be achieved as follows:

setprop service.7sim.debug.uicc_sub_toggle_disabled true

This property can be persistent.

Important

Remember to enable all SIM cards first before switching to a different method.

Support for slot power control isn't guaranteed due to OEM limitations.

You need su privileges to run the above command, or edit the /system/build.prop file via recovery as an alternative.

The app needs to be restarted to pick up new changes.

Testing

Code testing and coverage can be done through the Android Studio interface or command line tool:

• Unit tests

./gradlew :testDebugUnitTest

• Instrumentation tests

./gradlew :connectedDebugAndroidTest

Note

Make sure to start an Emulator or connect a device first so the test has something to connect to.

• Code coverage (via Kover)

./gradlew :koverHtmlReportDebug

Note

Code coverage for instrumentation tests is not supported yet.

Convert the Application Into a System App

A privileged user app is considered by the Android OS as a system application, when it's located in a priv-app directory on the device's system partition.

Note

As of now, this app doesn't require to be installed in the system partition to properly function, but some features such as the "Show app icon" option need it.

In order to convert the application into a system app, follow these steps:

1. Copy the APK

Download the latest release.apk from the release page and place it in the /system partition depending on the Android version:

• when running on Android 11.0 (R) or newer versions: /system/system_ext/priv-app/7SIM/7SIM.apk
• when running on versions prior to Android 11.0 (R): /system/priv-app/7SIM/7SIM.apk

Note: if using recovery, the mount point may vary across different recoveries: /mnt/system, /system_root, /system—for example, /system_root/system/system_ext/priv-app/7SIM/7SIM.apk.

Important

You may also need to set permissions to 644 and the SELinux label to u:object_r:system_file:s0 (e.g., via chcon command) for the file. If using recovery, this should be handled under the hood, but this isn't guaranteed if the recovery is very old.

2. Grant Privileged Permissions

Download and place the privapp_whitelist_com.github.iusmac.sevensim.xml file in the /system partition depending on the Android version:

• when running on Android 11.0 (R) or newer versions: /system/system_ext/etc/permissions/
• when running on versions prior to Android 11.0 (R): /system/etc/permissions/

Note: if using recovery, the mount point may vary across different recoveries: /mnt/system, /system_root, /system—for example, /system_root/system/system_ext/etc/permissions/.

Caution

Starting from Android 9.0 (P), as per Privileged Permission Allowlist article, the presence of the file with permissions is mandatory when converting a privileged user app into a system app, otherwise the device will bootloop indefinitely.

3. Add Survival Addon Script

To ensure the survival of the above files during ROM re-flashes and OTA updates, place the prebuilts/addon.d/50-7SIM.sh file in /system/addon.d/ directory. No need to give it execution permissions.

Note: if using recovery, the mount point may vary across different recoveries: /mnt/system, /system_root, /system—for example, /system_root/system/addon.d/50-7SIM.sh.

Note

This requires ROM with addon.d support, i.e, the presence of the /system/addon.d directory, also of the install directory in the ROM's zip when flashing.

Most custom ROMs support this out-of-the-box.

4. That's It!

This process must be done only once. To get updates, simply install the app as described in Installation section; the application will exist in both the system and data partitions, and the newest one will be used.

In the future, maybe we'll make the APK to be recovery-compatible to do the above steps automatically.

Important

If the ROM's system partition is read-only (e.g., formatted with EROFS), then the only option you have is to ask the ROM maintainer to include the app in the next OTA release. Direct them to the For ROM Maintainers section.

Quirks You Should Know About

Below are some quirks specific to the devices that DO NOT have the capability to turn on/off SIM cards out-of-the-box you that should be aware of.

1. SIM Card Showing in the SIM List After Being Ejected

If the SIM card is turned off and then ejected, it will be still showing in the SIM card list. This is because, as mentioned earlier, the devices lacking the capability to turn on/off SIM cards out-of-the-box, opt for SIM slot power control method to turn off SIM cards, so powering down a SIM card (or, more precisely its corresponding SIM slot that hosts it), is akin to remove it physically (the SIM card is expected to completely vanish from the system). Due to this, the SIM card will be showing in the SIM list until turned on. If the SIM card is ejected then turned on, it should disappear from the SIM list.

2. No Automatic SIM Card State Sync After Airplane Mode Disabled

If a SIM card is turned off and the device is switched into Airplane Mode, any schedule attempting to turn on the SIM card will be ignored, which is the expected behavior. After exiting Airplane Mode, the SIM card WILL NOT automatically turn on if it's supposed to as per schedules. This is because the Android OS doesn't notify apps of Airplane Mode state changes unless the app explicitly subscribes to these changes and remains working in the background. Since this app was developed on purpose to not waste system resources and do all the work on-demand, there is currently no workaround to this.

3. Irreversibly Invalidated SIM PIN Codes

The SIM PIN codes will become unusable under the following conditions:

1. After disabling the secure screen lock method (e.g., re-configuring it to "None" or "Swipe")
2. After clearing the data for the system built-in Settings app via "App Info > Storage & Cache > Clear storage"

These actions will irreversibly invalidate the secret key, making the SIM PIN decryption operation impossible. To restore functionality, you'll need to provide all SIM PIN codes again to regenerate the secret key.

Contributing

Contribute Code

You are welcome to contribute to the project!

Note that, this app was developed to be long-term maintainable and compatible across different Android versions. During development, we prioritize adherence to Android's standardized security concerns and restrictions as much as possible. That's said, before opening any PR with new features or bug fixes, please open an issue to discuss the changes first.

Translate

You can help translate 7SIM here on GitHub. Here are a few tips:

• Only strings without translatable="false" attribute are eligible for translation, for example:

  <string name="app_name">"7SIM"</string>

  whereas this shouldn't be translated:

  <string name="app_name" translatable="false">"7SIM"</string>

• When using ellipsis (dot dot dot), insert … instead.
• When using quotation marks, insert the symbols specific to the target language (if available), as listed in this table.
• When using the regular ASCII single quote mark, double quote everything, for example:

  <string name="my_string">"This is an 'example' string."</string>

• 7SIM uses title case for some English UI text. Title case isn't used in other languages; opt for sentence case instead.