# Super SIM’s Multi-IMSI Applet

Believe it or not, SIMs (Subscriber Identity Modules) are able to run small applications, called applets. Every Super SIM contains an applet which can switch the IMSI used in order to give you access to the widest selection of networks and redundant paths over which your data can be sent. To have the best experience with Super SIM, it's important to understand how this applet interacts with your device.

## What is an IMSI?

An International Mobile Subscriber Identity (IMSI) identifies a single user of the cellular network. When a device connects to a cellular network, that network uses the IMSI to check with the SIM's home network to query what privileges the network should allow the SIM: whether it can use data, whether it can use SMS — and even whether it's allowed to attach to that network at all.

## Single IMSI SIMs

A SIM generally contains only one IMSI. If that IMSI's home network doesn't have a roaming agreement with the network to which one of your devices is trying to attach, then the device will not be able to connect to that network. Neither will any of your other devices.

There's another problem inherent in having just one IMSIs: the operator of your home network is a single point of failure. All of your data has to be transmitted through its infrastructure. If anything goes wrong there, your devices will not be able to connect to your backend even if the local network that your device is attached to is performing perfectly.

## Super SIM's multi-IMSI approach

To bypass these limitations, each Super SIM holds multiple IMSIs. The SIM uses the multi-IMSI applet to switch between these IMSIs in order to give you access to the best selection of networks at the best rates in whatever country your device is currently located. Super SIM might therefore use one IMSI in the United States and a completely different IMSI when the device is moved to Australia because of either better network availability or better pricing.

### IMSI switching with Super SIM

There are a number of different situations that will cause a Super SIM to switch its IMSI. When an IMSI switch occurs, the applet will communicate with your device using "proactive commands" — instructions sent by the SIM to the device — offered by the [Card Application Toolkit](https://en.wikipedia.org/wiki/SIM_Application_Toolkit), a component of the standard [GSM](https://en.wikipedia.org/wiki/GSM) system.

{% hint style="info" %}
When a Super SIM changes its IMSI, the applet sends a `REFRESH` proactive command to the host device. This instructs the device to re-read the data on the SIM, including the new IMSI. Take a look at [**The REFRESH Proactive Command**](#the-refresh-proactive-command), below, for more details on how this works.
{% endhint %}

**Scenario 1: the device is in a new location**

Each Super SIM has a table that indicates which IMSI it should use in a given country. If the applet detects a Location Status event, a Status command, or an update to the LOCI (LOCation Information) files on your device, it will use the location data and the table to determine if it is using the preferred IMSI for that country. If it is not, the applet will switch to the preferred IMSI.

**Scenario 2: the device is unable to connect to all visible networks**

Many devices record the networks they have attempted to attach to but were not able to do so. This ensures they don't waste time attempting to connect to those networks in future. The record is called a forbidden networks (FPLMN) list. When all of the networks currently visible to the device are listed as forbidden networks, the applet on the SIM will switch IMSI to try to attach again with a different IMSI.

{% hint style="info" %}
On each IMSI switch, the FPLMN list will be cleared just before the `REFRESH` proactive command is sent.
{% endhint %}

**Scenario 3: The SIM's onboard timer expires**

Super SIMs are able to handle host devices that don't support either of the IMSI switching mechanisms outlined above. If the Super SIM enters Limited Service mode — because the device has not been unable to attach to any networks — it starts a timer. If the timer expires and the SIM is still in Limited Service, the applet now switches the IMSI and sends a `REFRESH` proactive command to the device.

The duration of the timer is approximately 180 seconds (three minutes).

{% hint style="warning" %}
If your device automatically restarts after a specified period of time during which it wasn't able to establish a data connection, make sure that the period is greater than the Super SIM's IMSI switching timer duration, or the applet's timer will not fire and the IMSI will not change accordingly. This is because your device may reset the onboard timer when it restarts.
{% endhint %}

### The REFRESH proactive command

When a Super SIM's multi-IMSI applet switches the IMSI, a `REFRESH` proactive command is sent to the host device. This instruction informs the device that the contents or structure of the Elementary Files (EFs) on the SIM have been changed. This command instructs the device to refresh the information it holds about the SIM and is therefore expected to reload the EFs and other data, including the IMSI, from the SIM.

The Super SIM multi-IMSI applet follows the [ETSI Technical Specification 102 223 Release 6](https://www.etsi.org/deliver/etsi_ts/102200_102299/102223/06.14.00_60/ts_102223v061400p.pdf). The `REFRESH` proactive command sent by the applet uses command qualifier `00 - NAA Initialization and Full File Change Notification`.

{% hint style="warning" %}
Later releases of ETSI TS 102 223 discourage the use of command qualifier `00`. However, using the suggested alternative command qualifier, `04 - UICC Reset`, can result in the device resetting and prompting the user for the SIM PIN, leaving the device disconnected from the network. To avoid this, the multi-IMSI applet continues to use command qualifier `00`.
{% endhint %}

## Example

Here is an example of Super SIM's multi-IMSI applet in action.

1. The SIM is initially provisioned with IMSI 1 as the active IMSI.
2. The SIM attaches to a German network (MCC 262).
3. Later, the SIM travels to Argentina (MCC 722).
4. The SIM tries to attach to a network in Argentina using the active IMSI, IMSI 1. However, no roaming agreement is in place, so IMSI 1 is rejected by the visited network.
5. The SIM applet finds Argentina (MCC 722) as the new location.
6. The SIM applet overwrites the active IMSI: IMSI 1 is replaced with IMSI 3 according to IMSI Selection Table.
7. The SIM sends the `REFRESH` proactive command to the device and a new network attach is performed using IMSI 3 .
8. The SIM is connected with IMSI 3 on an Argentine network partner.

## Advanced: Using local AT commands to control applet

You can use local AT commands issued to the SIM via your modem to control the multi-IMSI applet. Each `AT+CSIM` command can be used to trigger some action within the SIM. It instructs the module to relay to the SIM an embedded Application Protocol Data Unit (APDU) `ENVELOPE` command. This, in turn, contains proprietary instructions for the SIM.

{% hint style="warning" %}
As of April 2025, we are in the process of updating our SIM applets. Later in 2025, we will begin producing SIM hardware and SIM profiles with new applets. Additionally, we intend to over-the-air (OTA) update existing SIMs with the new applets. The new applets will have different AT commands. Be sure to take this into consideration before implementing any regular use of these AT commands in your device's firmware.

To learn about other planned changes to the SIM hardware and applets as part of this initiative, see our [migration guide](https://app.gitbook.com/s/cNyZufRYRGfUcwkaTlLQ/migration-guides/migrating-to-the-new-super-sim-hardware).

The table below documents both the current SIM applet command and new command that will be needed to trigger the action in the new applet to be released later in 2025.
{% endhint %}

<table><thead><tr><th width="187">Command Name</th><th>Description</th><th width="186.51171875">Current SIM Applets</th><th>New SIM Applets</th></tr></thead><tbody><tr><td><strong>Query SIM Status</strong></td><td>Request details about the multi-IMSI applet such as whether or not the applet is in automatic switching mode.</td><td><p>Request:</p><p><code>AT+CSIM=26,"80C2000008CF06020282814C00"</code></p><p></p><p>Response: </p><p>See <a href="#query-sim-status-responses">Query SIM Status Responses </a>below</p></td><td><p>Request: <code>AT+CSIM=28,"80C2000009CF0702028281B30100"</code></p><p></p><p>Response: </p><p>See <a href="#query-sim-status-responses">Query SIM Status Responses</a> below</p></td></tr><tr><td><strong>Force IMSI Switch</strong></td><td>Switch to the next IMSI. If the IMSI you switch to is not the Preferred IMSI for the current location, this will be a temporary change. Will return to automatic mode at Return to Priority Timer or the device is rebooted.</td><td><p>Request: <code>AT+CSIM=28,"80C2000009CF07020282814E0101"</code> </p><p></p><p>Response:</p><p><code>+CSIM: 4, "910B"</code></p></td><td><p>Request:</p><p><code>AT+CSIM=28,"80C2000009CF0702028281A001AA"</code></p><p></p><p>Responses:</p><p> <code>+CSIM: 4,"9000"</code> </p><p>or</p><p><code>+CSIM: 4,"6109"</code> if there is a response with 9 byte</p></td></tr><tr><td><strong>Return to Automatic Switching</strong></td><td>Set the SIM to automatic switching mode.</td><td><p>Request: <code>AT+CSIM=36,"80C200000DCF0B020282814F050190000000"</code></p><p></p><p>Response:</p><p><code>+CSIM: 4, "9000</code></p></td><td><p>Request: <code>AT+CSIM=28,"80C2000009CF0702028281A001EE"</code></p><p></p><p>Responses:</p><p><code>+CSIM: 4,"9000"</code> </p><p>or</p><p><code>+CSIM: 4,"6109"</code> if there is a response with 9 bytes</p></td></tr><tr><td><strong>Lock IMSI</strong></td><td><p>Disables automatic switching so the SIM will only use the current IMSI. </p><p></p><p><strong>Warning: this</strong> <strong>persists</strong> <strong>through device/modem reboots.</strong> </p><p></p><p>To restore Super SIM’s normal behavior, you must use the Return to Automatic Switching command.</p></td><td>Not available</td><td><p>Request: <code>AT+CSIM=28,"80C2000009CF0702028281A001BB"</code></p><p></p><p>Responses:</p><p><code>+CSIM: 4,"9000"</code> </p><p>or</p><p><code>+CSIM: 4,"6109"</code> if there is a response with 9 byte</p></td></tr><tr><td><strong>Switch to Last Working IMSI</strong></td><td>Will return to automatic mode at Return to Priority Timer or the device is rebooted.</td><td>Not available</td><td><p>Request: <code>AT+CSIM=28,"80C2000009CF0702028281A001CC"</code></p><p></p><p>Responses: </p><p><code>+CSIM: 4,"9000"</code> </p><p>or</p><p><code>+CSIM: 4,"6109"</code> if there is a response with 9 bytes</p></td></tr><tr><td><strong>Switch to Preferred IMSI</strong></td><td><p>Switches to the Preferred IMSI for the current location.</p><p></p><p>Will return to automatic mode at Return to Priority Timer or the device is rebooted.</p></td><td>Not available</td><td><p>Request: <code>AT+CSIM=28,"80C2000009CF0702028281A001DD"</code> </p><p></p><p>Responses:</p><p><code>+CSIM: 4,"9000"</code></p><p>or</p><p><code>+CSIM: 4,"6109"</code> if there is a response with 9 bytes</p></td></tr></tbody></table>

### **Query SIM status responses**

#### **Current Applet**

The crucial point is that you can use the returned data to check applet status. Look at the first hexadecimal byte of the response. This should be `80`, which indicates that the SIM is set to switch IMSIs automatically. The value is a bitfield. Bit 7 should always be set; bit 0 indicates the applet's current operation mode: if it is clear, the applet will switch IMSIs automatically.

```bash
AT+CSIM=26,"80C2000008CF06020282814C00"

+CSIM: 24,"80FF200000000F00009000"
```

Some modems may require a second command to read the response you're after. If your modem returns `+CSIM: 4, "6109"` you will need to issue a second command to read the response.

```bash
AT+CSIM=26,"80C2000008CF06020282814C00"
+CSIM: 4, "6109"

AT+CSIM=10,"00C0000009"
+CSIM: 24,"80FF200000000F00009000"
```

If you get the SIM status after forcing the SIM to switch to the next IMSI, the first byte of the response should no longer be 80. Common values are A1 and 82 depending on the point in the process at which you complete the query, but other values may be seen.

A1 means that the applet's timer is in operation (bit 6 is set) and the applet is in Default IMSI mode (bit 0 is set). When the timer fires, the applet will switch to Automatic mode.

82 indicates that the applet has switched from Default IMSI mode to Automatic mode. Bit 1 is set when the applet mode changes.

If you query the SIM's status again after running the command to put it back into automatic IMSI switching mode, the first byte of the response will once more be `80` — IMSI switching will take place automatically.

#### **New Applet**

If you run the query SIM status command, you will get a response from which you can decode various settings on the SIM. Note that the response below is an example.

```bash
AT+CSIM=28,"80C2000009CF0702028281B30100"
+CSIM: 4,"6109" #Command Executed and there is a response data of 9 bytes

AT+CSIM=10,"00C0000009"
+CSIM: 22,"010403029500FF95759000" #Example repsonse. Yours will be different.
```

Use the table below to understand what different bytes of the response convey:

<table><thead><tr><th width="96.744140625">Byte</th><th>Description</th><th>Values</th></tr></thead><tbody><tr><td>1</td><td>Automatic switch mode status</td><td><code>00</code>= Disabled<br><code>01</code>= Enabled</td></tr><tr><td>2</td><td>Current active IMSI. Indicates the position of the IMSI in the IMSI list starting from <code>01</code>.</td><td><code>01</code>, <code>02</code>, <code>03</code>, ...</td></tr><tr><td>3</td><td>Last working IMSI. Indicates the position of the IMSI in the IMSI list starting from <code>01</code>.</td><td><code>01</code>, <code>02</code>, <code>03</code>, ...</td></tr><tr><td>4-6</td><td>Timer left for switch back to preferred IMSI. 3 bytes in swap format.</td><td>Example: <code>029500</code></td></tr><tr><td>7-9</td><td>First network latch time from TP.</td><td>Example: <code>FF9575</code></td></tr></tbody></table>

### Advanced example: Using manual AT commands

The example below shows how to use the AT Commands to combine multiple local commands to understand the status of the multi-IMSI applet and force the SIM to switch to the next IMSI.

{% hint style="warning" %}
This example uses the AT Commands of the current multi-IMSI applet as of April 2025. Later in 2025, we will begin producing SIM hardware and SIM profiles with new applets. Additionally, we intend to over-the-air (OTA) update existing SIMs with the new applets. The new applets will have different AT commands. Be sure to take this into consideration before implementing any regular use of these AT commands in your device's firmware.

To learn about other planned changes to the SIM hardware and applets as part of this initiative, see our [migration guide](https://docs.korewireless.com/en-us/twilio-iot-acquisition/migration-guides/migrating-to-the-new-super-sim-hardware).
{% endhint %}

**Query SIM status**

The following `AT+CSIM` command can be used to read the status of the multi-IMSI applet. It instructs the module to relay to the SIM an embedded Application Protocol Data Unit (APDU) `ENVELOPE` command. This, in turn, contains proprietary instructions for the SIM.

The crucial point is that you can use the returned data to check applet status. Look at the first hexadecimal byte of the response. This should be `80`, which indicates that the SIM is set to switch IMSIs automatically. The value is a bitfield. Bit 7 should always be set; bit 0 indicates the applet's current operation mode: if it is clear, the applet will switch IMSIs automatically.

{% code lineNumbers="true" %}

```bash
AT+CSIM=26,"80C2000008CF06020282814C00"

+CSIM: 24,"80FF200000000F00009000"
```

{% endcode %}

Some modems may require a second command to read the response you're after. If your modem returns `+CSIM: 4, "6109"` you will need to issue a second command to read the response.

{% code lineNumbers="true" %}

```bash
AT+CSIM=26,"80C2000008CF06020282814C00"
+CSIM: 4, "6109"

AT+CSIM=10,"00C0000009"
+CSIM: 24,"80FF200000000F00009000"
```

{% endcode %}

**Force a switch to the next IMSI**

The following command causes the SIM to provide a new IMSI to the module. It will be the next IMSI in its list. This may not be usable in the device's current location, in which case the module will fail to connect, ultimately triggering a further IMSI switch.

{% code lineNumbers="true" %}

```bash
AT+CSIM=28,"80C2000009CF07020282814E0101"

+CSIM: 4,"910B"
```

{% endcode %}

If you query the SIM's status again, the first byte of the response should no longer be `80`. Common values are `A1` and `82` depending on the point in the process at which you complete the query, but other values may be seen.

`A1` means that the applet's timer is in operation (bit 6 is set) and the applet is in Default IMSI mode (bit 0 is set). When the timer fires, the applet will switch to Automatic mode.

`82` indicates that the applet has switched from Default IMSI mode to Automatic mode. Bit 1 is set when the applet mode changes.

**Return to automatic IMSI switching**

As long as the SIM is not already using the preferred IMSI for its location, the following command will cause the SIM to provide a new IMSI to the module. Either way, the multi-IMSI applet will once again be in automatic mode.

{% code lineNumbers="true" %}

```bash
AT+CSIM=36,"80C200000DCF0B020282814F050190000000"

+CSIM: 4,"9000"
```

{% endcode %}

If you query the SIM's status again, the first byte of the response will once more be `80` — IMSI switching will take place automatically.

{% hint style="info" %}
You can find full information on the structure of APDU commands and the responses they may yield by consulting [ETSI Technical Specification 102 221](https://www.etsi.org/deliver/etsi_ts/102200_102299/102221/16.03.00_60/ts_102221v160300p.pdf).
{% endhint %}