/
Using SoftSIM on SOM-NRF9151

Using SoftSIM on SOM-NRF9151

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 https://voxelbotics.atlassian.net/wiki/spaces/SOMnRF9151/pages/709328900.

  2. Install the modem and application firmware onto the hardware platform as described in https://voxelbotics.atlassian.net/wiki/spaces/SOMnRF9151/pages/708673628/Installing+SOM-NRF9151+Images?atlOrigin=eyJpIjoiYWUyYTU1MzAzNGMyNGZmOWEwZDFlOTMxNzdkYjk1ZTciLCJwIjoiYyJ9.

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.