/
Using SoftSIM on SOM-NRF9151

Using SoftSIM on SOM-NRF9151

Owned by Dmitry Starchenko
Last updated: Apr 18, 2025
7 min read

1. Overview

This document overviews the SoftSIM technology supported by Zephyr BSP for SOM-NRF9151 and provides instructions how to configure and use the SoftSIM library in the customized Asset Tracker v2 application.

2. Device Preparations

  1. Set up the hardware platform with an LTE antenna as described in Setting Up Emcraft SOM-NRF9151 Hardware Platform.

  2. Install the modem and application firmware onto the hardware platform as described in Installing SOM-NRF9151 Images.

3. SoftSIM Overview

SoftSIM is a form of SIM card that is implemented in software and programmed into a device. The SoftSIM interface in the Modem library is used to transfer SIM data between the modem and the application. When the modem makes a SoftSIM request, the SoftSIM interface handles the request and forwards it to the application. The application then generates a response and responds to the modem through the SoftSIM interface. The modem can be configured at runtime to use a regular SIM or SoftSIM (iSIM), or both. For more information on how to enable this feature in the modem, refer to the nRF91x1 AT Commands Reference Guide.

3.1. nRF Connect SDK SoftSIM C-binding API

nRF Connect SDK implements the following C-binding API, which is declared in the nrf_modem_softsim.h file:

Function

Description

Comments

typedef void (*nrf_modem_softsim_req_handler_t)(enum nrf_modem_softsim_cmd cmd, uint16_t req_id, void *data, uint16_t data_len);

Handle a SoftSIM request.

To handle requests from the SoftSIM interface, the application needs to implement a nrf_modem_softsim_req_handler_t handler and set it with the nrf_modem_softsim_req_handler_set() function. The nrf_modem_softsim_req_handler_t handler is then called by the Modem library whenever there is a new SoftSIM request. The nrf_modem_softsim_req_handler_t handler is called in an interrupt service routine.

cmd - One of the following SoftSIM commands:

  • NRF_MODEM_SOFTSIM_INIT - Initialization command.

  • NRF_MODEM_SOFTSIM_APDU - Transport command, issued by the Modem to request data from the application.

  • NRF_MODEM_SOFTSIM_DEINIT - Deinitialization command.

  • NRF_MODEM_SOFTSIM_RESET - Reset command, issued by the Modem when a request becomes unresponsive.

req_id - Request ID used to match request and response.

data - Pointer to the data of the SoftSIM request.

data_len - Length of the data of the SoftSIM request.

 

int nrf_modem_softsim_req_handler_set(nrf_modem_softsim_req_handler_t handler);

Set a handler function for SoftSIM requests.

handler - The SoftSIM request handler. Use NULL to unset handler.

Returns 0 on success.

int nrf_modem_softsim_res(enum nrf_modem_softsim_cmd cmd, uint16_t req_id, void *data, uint16_t data_len);

Sends a SoftSIM response to a request.

This function is used to respond to the Modem with the data requested by a specific request.

cmd - SoftSIM response command.
req_id - Request ID used to match request and response.
data - Pointer to the data of the SoftSIM response.
data_len - Length of the data of the SoftSIM response.

Returns:

  • 0 on success.

  • -NRF_EINVAL if input data is invalid.

  • -NRF_ENOMEM if memory allocation failed.

int nrf_modem_softsim_err(enum nrf_modem_softsim_cmd cmd, uint16_t req_id);

Sends a SoftSIM error to a request.

This function is used to inform the Modem that an error occurred for a specific request.

cmd - SoftSIM response command.

req_id - Request ID used to match request and response.

Returns:

  • 0 on success.

  • -NRF_ENOMEM if memory allocation failed.

void nrf_modem_softsim_data_free(void *data);

Free the data of a SoftSIM request.

data - Data to free.

3.2. Onomondo SoftSIM Implementation

The customized nRF Connect SDK manifest includes a link to the latest release of Onomondo SoftSIM library. Use the west update command to update the west environment and download the SoftSIM library automatically.

Onomondo SoftSIM library is available at https://github.com/onomondo/nrf-softsim .

Refer to https://github.com/onomondo/nrf-softsim?tab=readme-ov-file#understanding-the-sim---why-softsim-is-possible for more details about Onomondo SoftSIM implementation.

3.2.1. Onomondo SoftSIM C-binding API

The Onomondo SoftSIM library implements the following C-binding API, which is defined in the nrf_softsim.h file:

Function

Description

Comments

int nrf_softsim_init(void);

Initialize the SoftSIM library and install the SoftSIM request handler.

Only use if CONFIG_NRF_SOFTSIM_AUTO_INIT is not set.

Returns 0 on success.

int nrf_softsim_provision(uint8_t *profile, size_t len);

Provision a SoftSIM profile to protected storage.

profile - String representing a SoftSIM profile. This encodes IMSI, ICCID and necessary keys.

len - Length of profile passed.

Returns 0 on success.

int nrf_softsim_check_provisioned(void);

Check if a SoftSIM profile is provisioned in protected storage.

Returns 1 if provisioned, 0 if not.

It’s not recommended to call this function after switching from SoftSIM to the physical SIM, as it may cause kernel panic.

3.2.2. Onomondo SoftSIM Threads and Tasks

The nrf_softsim_init() implements a separate workqueue thread for SoftSIM operations, which prevents other threads from interfering with handling of SoftSIM requests from the nRF9151 LTE modem.

4. Configuring SoftSIM in the Customized Asset Tracker v2 Application

4.1. Asset Tracker v2 C-binding API for SoftSIM

The Customized Asset Tracker v2 application implements the following C-binding helper API for SoftSIM, defined in softsim_app.* files:

Function

Description

Comments

void softsim_app_init(void);

Initialize the SoftSIM library.

The Onomondo allows to initialize the library on boot, but it also switches the SIM type to virtual SIM. It's not suitable if the physical and software SIMs are supposed to be interchangable.

bool softsim_app_is_initialized(void);

Check if the SoftSIM library is initialized

Returns true if SoftSIM library is initialized, false otherwise

int softsim_app_select_softsim(bool enable);

Switch between physical and soft SIMs

enable - Select the soft SIM if true and physical SIM if false.

The function will switch the modem between the minimum functionality mode (+CFUN=0) and normal mode (+CFUN=1) to force it to write SIM type selection to the internal non-volatile memory.

Returns 0 on success, negative error code otherwise.

bool softsim_app_is_selected(void);

Check if soft SIM is selected

Returns true if soft SIM is selected, false otherwise

bool softsim_app_is_inserted(void);

Check if soft SIM is "inserted"

The function implies that if the soft SIM is provisioned, it can be used by the modem ("inserted"). It's applicable to the Onomondo implementation, but other implementations may differ.

Returns true if soft SIM is "inserted", false otherwise.

4.2. Partition Manager and Application Configuration for SoftSIM Library

The SoftSIM library requires the partition manager configuration to include the following partitions in order to store the SoftSIM profile in the nRF9151 internal Flash:

tfm_its: region: flash_primary address: 0xf8000 size: 0x2000 tfm_otp_nv_counters: region: flash_primary address: 0xfa000 size: 0x2000 EMPTY_tfm_ps: region: flash_primary address: 0xfc000 size: 0x4000 tfm_storage: region: flash_primary address: 0xf8000 span: - EMPTY_tfm_ps - tfm_its - tfm_otp_nv_counters size: 0x8000

The application configuration file (prj.conf) should include the following parameters in order to include the SoftSIM library into the resulting image:

# FPU config CONFIG_FPU=y CONFIG_FPU_SHARING=y CONFIG_FP_SOFTABI=y # Onomondo SoftSIM library is not compatible with the hardware floating point, so we need to use the software implementation # Heap and stacks CONFIG_MAIN_STACK_SIZE=5000 CONFIG_HEAP_MEM_POOL_SIZE=30000 # Min. heap size supported by the SoftSIM library CONFIG_SHELL_CMD_BUFF_SIZE=256 # Should big enough to store the SoftSIM profile # Onomondo SoftSIM Configurations CONFIG_SOFTSIM_APP=y # Enable SoftSIM support CONFIG_SOFTSIM_AUTO_INIT=n # NVS Configurations CONFIG_NVS=y # Enable support of Non-volatile Storage CONFIG_NVS_LOG_LEVEL_ERR=y CONFIG_PM_PARTITION_SIZE_NVS_STORAGE=0x8000 # Set the Non-volatile Storage size to 32KB # TF-M Configurations CONFIG_BUILD_WITH_TFM=y # Build the application with TF-M as the Secure Execution Environment CONFIG_PM_PARTITION_SIZE_TFM_SRAM=0xC000 # Increase the TF-M SRAM region from 32KB to 48KB CONFIG_TFM_PROFILE_TYPE_NOT_SET=y CONFIG_TFM_LOG_LEVEL_SILENCE=y # The bootloader adds a small mcuboot_pad partition, # whose size must be subtracted from the TF-M partition #CONFIG_BOOTLOADER_MCUBOOT=y CONFIG_PM_PARTITION_SIZE_TFM=0xfe00 # Reduce the TF-M Flash partition to 63,5KB (64KB - mcuboot_pad size) # PSA Crypto Configurations CONFIG_PSA_WANT_ALG_CBC_NO_PADDING=y CONFIG_PSA_WANT_ALG_ECB_NO_PADDING=y CONFIG_PSA_WANT_ALG_CMAC=y CONFIG_PSA_WANT_KEY_TYPE_AES=y # Libraries CONFIG_NEWLIB_LIBC=y # Enable Newlib, as it's required by SoftSIM CONFIG_NEWLIB_LIBC_FLOAT_PRINTF=y # Reduce the size of TF-M by disabling the PS CONFIG_TFM_PARTITION_PROTECTED_STORAGE=n CONFIG_PSA_CRYPTO_DRIVER_CC3XX=n # Reduce the size of TF-M by disabling the PS CONFIG_TFM_PARTITION_PROTECTED_STORAGE=n CONFIG_PSA_CRYPTO_DRIVER_CC3XX=n

4.3. SoftSIM Shell Commands

The Customized Asset Tracker v2 application provides a set of Zephyr shell commands for SoftSIM, which are defined in the softsim_app.c file:

Command

Parameters

Comments

softsim provisioning <profile> [-f]

<profile> - SoftSIM profile to provision

[<-f>] - overwrite the existing profile

Write SoftSIM profile to the device memory

softsim enable

 

Switch from physical SIM to SoftSIM

softsim disable

 

Switch from SoftSIM to physical SIM

softsim status

 

Show the SoftSIM status in the following format:

SoftSIM library <initialized|not initialized> SoftSIM <provisioned|not provisioned> SoftSIM <selected|not selected>

5. Using SoftSIM in the Customized Asset Tracker v2 Application

5.1. Obtaining SoftSIM Profiles

Refer to the following instructions to obtain the SoftSIM profiles:

https://github.com/onomondo/nrf-softsim?tab=readme-ov-file#quick-setup-guide

https://github.com/onomondo/onomondo-softsim-cli?tab=readme-ov-file#softsim-cli

5.2. Provisioning SoftSIM

  1. Reset the board and observe the SoftSIM status in the nRF9151 serial console:

    [00:00:00.781,738] <inf> softsim: SoftSIM initialized ... [00:00:00.930,480] <inf> softsim_app: Switched to physical SIM ... [00:00:01.899,749] <inf> softsim_app: SoftSIM library initialized [00:00:01.899,780] <inf> softsim_app: SoftSIM not provisioned [00:00:01.899,810] <inf> softsim_app: SoftSIM not selected

  2. Verify that the SoftSIM library is initialized, but the SoftSIM is not provisioned and not selected.

  3. Provision the SoftSIM profile using the softsim provisioning command:

    uart:~$ softsim provisioning <SoftSIM profile> Provisioning SoftSIM, len = 186 [00:00:07.143,188] <inf> softsim: SoftSIM keys written to KMU [00:00:07.143,249] <inf> softsim: Provisioning SoftSIM 1/4 [00:00:07.235,595] <inf> softsim: Provisioning SoftSIM 2/4 [00:00:07.237,091] <inf> softsim: Provisioning SoftSIM 3/4 [00:00:07.238,861] <inf> softsim: Provisioning SoftSIM 4/4 [00:00:07.241,516] <inf> softsim: SoftSIM provisioned [00:00:07.241,546] <inf> softsim: SoftSIM fully provisioned

  4. Use the softsim status command to verify that the SoftSIM profile has been provisioned:

    uart:~$ softsim status SoftSIM library initialized SoftSIM provisioned SoftSIM not selected

SoftSIM provisioning does not require resetting the device, and the profile can be used immediately after provisioning.

The SoftSIM profile is stored in the nRF9151 internal Flash and can be erased or overwritten in the following situations:

  • Ovewriting the application firmware will also erase the SoftSIM profile.

  • Using the softsim provisioning with the -f flag will overwrite the existing SoftSIM profile without erasing the application firmware.

5.3. Connecting to LTE Network Using SoftSIM

  1. Switch to SoftSIM using the softsim enable command:

    uart:~$ softsim enable Switching to SoftSIM [00:07:30.759,857] <inf> softsim_app: Switched to SoftSIM

  2. Read the SoftSIM status and verify that the SoftSIM has been selected:

    uart:~$ softsim status SoftSIM library initialized SoftSIM provisioned SoftSIM selected

  3. Wait for the device to connect to the LTE Network as if it was using the physical SIM. For details refer to Connecting to LTE Network with nRF9151 LTE Modem | 4. Connecting to LTE Network with nRF9151 LTE Modem.

Selected SIM type is stored in the LTE modem non-volatile memory. In case of reset, the device will continue to use the previously selected SIM.

The physical SIM is selected by default. SIM type can be changed in the following situations:

  • The application automatically reverts to the physical SIM if the SoftSIM library is not initialized or the SoftSIM profile is not provisioned.

  • The softsim enable command is used to select the SoftSIM. The command will succeed only if the SoftSIM library is initialized and the SoftSIM profile is provisioned. Otherwise, the application will continue to use the physical SIM (if inserted).

  • The softsim enable command is used to select the physical SIM.

Related content