Cellular

The cellular interface provides connection to mobile broadband networks using standards defined by 3GPP (3rd Generation Partnership Project).

3GPP has defined a wide range of standards (such as GSM, GPRS, UMTS, HSDPA, LTE, 5G) with different properties: range of coverage, minimum achievable latency, downlink/uplink max throughput, etc.

The cellular interface is implemented using cellular modules from different vendors. Depending on the cellular module installed in each device, the cellular interface will have different capabilities.

Operational command controllers cellular show capabilities can be used to list the cellular modules that are configurable on the system, as well as any relevant information about them.

Example:

admin@osdx$ controllers cellular show capabilities
wwan0
   Module Manufacturer: Quectel
   Module Model: EC25E
   Module Firmware: EC25EFAR06A01M4G_TEL
   Hardware Revision: 10000
   Modem/App Firmware: EC25EFAR06A01M4G_TEL_01.300.01.300
   IMEI: 866308062070222
   Radio Interfaces: gsm, umts, lte
   Data Service Capability: non-simultaneous-cs-ps
   Maximum TX/RX rate supported: 50000/100000 Kbps
   Bands: gsm-dcs-1800, gsm-900-extended, gsm-900-primary, wcdma-2100, wcdma-850-us, wcdma-900
   LTE bands: 1, 3, 5, 7, 8, 20, 38, 40, 41

Profile 

Once the cellular modules available in the system are known, they can be configured. To do this, the first thing to do is define a cellular profile that will be later assigned to the cellular module being configured.

To create a cellular profile, use the cellular profile <id> command to give it a name and adjust the different parameters:

apn: configures the APN (Access Point Name) used to establish the connection to the mobile broadband network (mandatory).
username: configures the username to be used in network authentication.
password: configures the password to be used in network authentication.
auth: configures the protocol to be used in network authentication. One of the following values (default, both) can be selected.
- chap: use the Challenge Handshake Authentication Protocol.
- pap: use the Password Authentication Protocol.
- both: use CHAP and PAP.

Once the cellular profile has been created, the cellular module can be configured using the controllers cellular <txt> command.

Multiple PDPs (Packet Data Protocol) can be configured on the same cellular module by using the controllers cellular <txt> pdp <u32> command. Additionally, you must specify the cellular profile to be used by the PDP interface via the controllers cellular <txt> pdp <u32> profile <id> command.

Finally, you can create a cellular interface by using the interfaces cellular <txt> command. These interfaces need to be linked to a cellular module by using the interfaces cellular <txt> phy <txt> pdp <u32> command.

Accessibility Control 

Verifying availability is hard for connections established through mobile devices. However, other mechanisms can be implemented to verify the connection status.

For this purpose, OSDx boasts a functionality that, once the connection is established, sends pings at an interval and to the IP address configured by the user and then waits for a response (within this interval).

If no response is received before it times out, a second ping is sent and a response is expected within 10 seconds. If there is still no response, two more pings are sent at 5-second intervals. Finally, if there is still no response, the device is reconnected to the network.

This mechanism can be independently enabled on each cellular profile that is configured in the system by adjusting the following parameters of the cellular profile <id> accessibility-control ping command:

address: IP address where pings are sent.
interval: time interval (in seconds) between pings sent.

Personal Identification Number (PIN)

In order to establish a connection to the mobile broadband network, a SIM card must be inserted in the corresponding slot.

Sometimes, the SIM card is locked by a PIN code. In these cases, configure the SIM card’s PIN code using the pin field.

Once the cellular module is configured, the status of the SIM card can be checked via the controllers cellular <value> show network-status operational command.

Example:

admin@osdx$ controllers cellular wwan0 show network-status
SIM status = OK
Registration state = registered
Public Land Mobile Network code = 21407
Public Land Mobile Network name = Movistar
Network technology currently in use = lte
Current Service Domain registered = cs-ps (capable cs-ps)
Current Roaming status = off
3GPP Cell ID = 28195870
Radio Band = eutran-3
Bandwidth = 20
Channel = 1301
LTE Tracking Area Code (TAC) = 11091
RX level (dBm) = -69
Coverage level = 4 (**** )

SIM card errors can sometimes cause network connectivity issues. This can be checked using the previous operational command. Instead of displaying “SIM status = OK”, it will display “SIM Status = LOCKED” and detail the error in brackets.

A list of the most common errors is included below:

SIM not inserted: the system does not find any inserted SIM card.
PIN not configured: the inserted SIM card is locked by a PIN code that has not been added to the configuration.
Incorrect password: the inserted SIM card is locked by a PIN code, and the code added to the configuration is incorrect.
SIM PUK required: the inserted SIM card is locked by a PUK code.

The “SIM PUK required” error usually occurs when the number of attempts to enter a correct PIN code on the SIM card is exceeded. As a result, the SIM is locked by a PUK code. To solve this, the controllers cellular <value> open-at-terminal operational command must be launched and AT+CPIN=”12345678”,”1234” must be written in the AT terminal (with 12345678 as the PUK code and 1234 as the new PIN code that you want to assign to the SIM card). If the AT terminal then displays OK, it means that the SIM card has been successfully unlocked.

Example:

admin@osdx$ controllers cellular wwan0 open-at-terminal
AT+CPIN="12345678","1234"

OK

Network Mode 

Additionally, the type of technology the cellular module used to connect to the mobile broadband network can be selected. This can be done via the controllers cellular <txt> network mode <txt> command, selecting one of the following values (default, automatic).

automatic: using the best technology available.
all-but-5g: using the best technology available except 5G-SA and 5G-NSA.
all-but-5g-sa: using the best technology available except 5G-SA.
5g-nsa: using LTE or LTE + 5G-NSA.
5g-sa: only using 5G-SA.
cdma: only using CDMA.
gprs: only using GPRS.
hrpd: only using CDMA HRPD.
hybrid: using CDMA or CDMA HRPD.
lte: only using LTE.
wcdma: only using UMTS/HSDPA.

Depending on the cellular module installed in the device, some modes from the list above will not be supported. If you try to select a mode that is not supported by a cellular module, an error message will be displayed.

Example:

admin@osdx# set controllers cellular wwan0 network mode cdma
  "cdma" is not a network mode supported by wwan0 (Quectel EC25E). Supported modes are: automatic, all-but-5g, gprs, lte, wcdma
  Value validation failed
  CLI Error: Command error

The technology currently used by the cellular module can be checked via the controllers cellular <value> show network-status operational command.

Example:

admin@osdx$ controllers cellular wwan0 show network-status
SIM status = OK
Registration state = registered
Public Land Mobile Network code = 21407
Public Land Mobile Network name = Movistar
Network technology currently in use = umts
Current Service Domain registered = cs-ps (capable cs-ps)
Current Roaming status = off
3GPP Location Area Code = 1109
3GPP Cell ID = 40106379
Radio Band = wcdma-900
Channel = 3034
WCDMA Primary Scrambling Code (PSC) = 443
WCDMA High-Speed Call Status = hsdpa-hsupa-unsupported
WCDMA High-Speed Service Indication = hsdpa-hsupa-unsupported
EcIo (dB) = -7.5
RX level (dBm) = -82
Coverage level = 3 (***  )

SIM Sockets 

Some cellular modules support multiple SIM sockets, allowing greater flexibility and resilience in connectivity.

For example, on some routers there are three types of sockets available:

socket_1: the primary physical SIM slot.
socket_2: a secondary physical SIM slot (backup).
esim: the embedded SIM (eUICC).

This multi-socket design allows administrators to configure any combination of these sockets to achieve fault tolerance.

For example, if the subscription in socket_1 experiences poor coverage or high latency, the router can seamlessly switch to socket_2 or the esim profile, ensuring continuous connectivity with a different operator.

Configuring SIM Sockets 

To define which sockets are available for a cellular module, you can use the following command:

controllers cellular <txt> sim socket <txt>

The SIM card’s PIN code can be specified with the following command:

controllers cellular <txt> sim socket <txt> pin <txt>

The cellular profile can be specified with the following command:

controllers cellular <txt> sim socket <txt> pdp <u32> profile <id>

One socket must be selected as active with the following command:

controllers cellular <txt> sim select <txt>

Example:

set controllers cellular wwan0 sim select socket_1
set controllers cellular wwan0 sim socket socket_1 pin 1234
set controllers cellular wwan0 sim socket socket_1 pdp 1 profile CELPROFILE_1
set controllers cellular wwan0 sim socket socket_2 pin 5678
set controllers cellular wwan0 sim socket socket_2 pdp 1 profile CELPROFILE_2

Sockets can be switched dynamically through an operational command:

controllers cellular <value> sim select switch <txt>

SIM Socket Supervision 

SIM Socket Supervision is an automated mechanism that monitors connection health and performance, and triggers SIM socket switching when specific criteria are met. This feature enables routers to maintain stable connectivity without requiring manual intervention.

When supervision is enabled, the system periodically evaluates the configured conditions and decides whether to remain on the current SIM or switch to a different socket.

Supervision criteria can be enabled for a specific socket with the following command:

controllers cellular <txt> sim socket <txt> supervision

As of today, the following criteria are supported:

Advisor: uses the status of a system advisor to determine if a switch is necessary. An additional parameter connection-timeout can be used to set the maximum waiting time before the advisor is queried.
Registration-Lost: triggers a switch if the modem remains in a unregistered state for a specified period. The parameter over sets the maximum time the device can remain unregistered, and the parameter check-interval can be used to set how often to evaluate the status.
Inactivity: triggers a switch if the modem remains in a disconnected state for a specified period. The parameter over sets the maximum time the device can remain disconnected, and the parameter check-interval can be used to set how often to evaluate the status.
Technology: forces a switch when the modem is stuck on an undesired technology (e.g., falling back to 3G instead of LTE). The parameter undesired sets the undesired technology, the parameter over sets the maximum time the device can use the undesired technology and the parameter check-interval can be used to set how often to measure the technology.
Usage-Time: forces a switch after a defined period of continuous use, regardless of connectivity state. The parameter over sets the maximum time the selected SIM can be used.
Signal: switches SIM sockets if coverage is degraded. The parameter over sets the maximum time the device can have coverage levels equal to or lower than those configured. The parameter check-interval can be used to set how often to measure the signal strength. Depending on the technology currently used by the cellular module, different types of signal levels can be monitored.
- GSM/GPRS: the rssi-level parameter sets the RSSI level that triggers the switch.
- UMTS/HSDPA: the rscp-level and ecno-level parameters set the RSCP and EcNo levels that trigger the switch.
- LTE/5G: the rsrp-level and rsrq-level parameters set the RSRP and RSRQ levels that trigger the switch.

These criteria can be configured with the following command:

controllers cellular <txt> sim socket <txt> supervision criteria

The target socket is defined with the option sim-switch:

controllers cellular <txt> sim socket <txt> supervision sim-switch <txt>

Different criteria can be combined together to fine-tune the switching policy.

Example:

set controllers cellular wwan0 sim select socket_1
set controllers cellular wwan0 sim socket socket_1 pdp 1 profile CELPROFILE1
set controllers cellular wwan0 sim socket socket_1 supervision criteria usage-time over 30
set controllers cellular wwan0 sim socket socket_1 supervision sim-switch socket_2
set controllers cellular wwan0 sim socket socket_2 pdp 1 profile CELPROFILE2
set controllers cellular wwan0 sim socket socket_2 supervision criteria registration-lost over 4
set controllers cellular wwan0 sim socket socket_2 supervision sim-switch esim
set controllers cellular wwan0 sim socket esim pdp 1 profile CELPROFILE
set controllers cellular wwan0 sim socket esim supervision criteria advisor advisor-id CELL_ADV
set controllers cellular wwan0 sim socket esim supervision sim-switch socket_1

The controllers cellular <value> sim select show command displays whether the supervisor is enabled or not for the currently selected SIM socket. In addition, the currently selected SIM socket, the previously selected SIM socket, and the date and reason for the last SIM socket change are displayed.

Example:

admin@osdx$ controllers cellular wwan0 sim select show
Previous SIM:       socket_1
Current SIM:        socket_2
Last switch date:   2025-09-25 17:05:45.385705+02:00
Last switch reason: Supervision connection lost criteria
SIM supervision:    enabled

The controllers cellular <value> sim select show log command displays a log containing all SIM socket changes that have occurred so far.

Example:

admin@osdx$ controllers cellular wwan0 sim select show log
--------------------------------------------------------------------------------
Socket                 Date                               Reason
--------------------------------------------------------------------------------
socket_1  2025-09-25 16:55:00.519758+02:00                        Initial status
socket_2  2025-09-25 17:05:45.385705+02:00  Supervision connection lost criteria

This log can be cleared using the controllers cellular <value> sim select clear log command, leaving only the last two entries.

Additionally, the controllers cellular <value> sim socket show identifiers command displays the identifiers of those SIM sockets that have been selected at some point during execution.

Example:

admin@osdx$ controllers cellular wwan0 sim socket show identifiers
socket_1:
   IMSI:  214034581526870
   ICCID: 8934014182505368714F
socket_2:
   IMSI:  214019816249848
   ICCID: 8934569821305399747F

eSIM Socket 

The embedded SIM (also known as eSIM or eUICC) is a new generation secure element designed to replace or complement traditional plastic SIM cards. Unlike physical SIMs, which require manual insertion and swapping, an eSIM can securely store and manage multiple mobile network operator subscriptions digitally.

eSIM technology is standardized by the GSMA, ensuring interoperability across devices and operators. It introduces two key components for remote provisioning:

LPA (Local Profile Assistant): a client on the device that requests, downloads, and manages operator profiles.
SM-DP+ (Subscription Manager Data Preparation): a remote server that securely delivers encrypted profiles to the device.

With eSIM support, an OSDx router can seamlessly switch between different operator profiles without physical intervention, making it ideal for remote deployments, IoT and high-availability scenarios.

Once the eSIM socket is selected, the LPA component manages the provisioning of operator profiles. Typically, your carrier provides an activation code (often in the form of a QR code or alphanumeric string).

To install a new profile, you can issue the following command:

controllers cellular <value> sim socket esim install <txt>

Important

This operation requires an active internet connection and functional DNS resolution. Since the router must contact the carrier’s SM-DP+ server, firewalls or network security agents may block profile provisioning if not properly configured.

An eSIM can hold multiple operator profiles, though only one is active per modem at a time. Profiles can be managed at runtime:

To enable a profile, you can issue the following command:

controllers cellular <value> sim socket esim enable <u32>

And, to disable a profile, you can issue the following command:

controllers cellular <value> sim socket esim disable <u32>

Finally, to remove a profile, you can issue the following command:

controllers cellular <value> sim socket esim remove <u32>

The command controllers cellular <value> sim socket esim show identifier can be used to display the eSIM identifier (EID) and the command controllers cellular <value> sim socket esim show profile can be used to display information about installed profiles.

Examples 

Single-APN 

Imagine that you want to configure the wwan0 cellular module, for which a SIM card with PIN code 1234 is inserted. Additionally, you want to bind an interface to this module and connect it to the mobile broadband network through the oper_apn.com APN only using the UMTS/HSDPA technology.

In OSDx, this can be achieved by entering the following commands:

set cellular profile CELPROFILE apn oper_apn.com
set controllers cellular wwan0 pin 1234
set controllers cellular wwan0 network mode wcdma
set controllers cellular wwan0 pdp 1 profile CELPROFILE
set interfaces cellular cell0 phy wwan0 pdp 1
set interfaces cellular cell0 address dhcp

Multi-APN 

Imagine that you want to configure two PDN data calls over the wwan0 cellular module. Additionally, you want to bind two interfaces to this module and connect each of these interfaces to the mobile broadband network as follows:

Using the APN oper_apn1.com for cellular interface cell0.
And, using the APN oper_apn2.com for cellular interface cell1.

In OSDx, this can be achieved by entering the following commands:

set cellular profile CELPROFILE1 apn oper_apn1.com
set cellular profile CELPROFILE2 apn oper_apn2.com
set controllers cellular wwan0 pin 1234
set controllers cellular wwan0 pdp 1 profile CELPROFILE1
set controllers cellular wwan0 pdp 2 profile CELPROFILE2
set interfaces cellular cell0 phy wwan0 pdp 1
set interfaces cellular cell1 phy wwan0 pdp 2
set interfaces cellular cell0 address dhcp
set interfaces cellular cell1 address dhcp

Here, you can find more interfaces cellular examples.

Monitoring 

In OSDx, there are several operational commands related to controllers cellular that can display valuable information or allow some action to be executed on the cellular modules.

Up until now, some of these operational commands have been detailed:

The controllers cellular show capabilities command displays a list of configurable cellular modules, as well as relevant information about them.
The controllers cellular <value> show network-status command shows information about the state of the radio link (SIM status, registration state, network technology currently in use, …).
The controllers cellular <value> open-at-terminal command allows a terminal in which to execute AT commands to be opened (for example, to unlock the SIM card by inserting the PUK code).

But these are not the only operational commands related to controllers cellular that are available.

The controllers cellular <value> show device-info command displays information about the cellular module.

Example:

admin@osdx$ controllers cellular wwan0 show device-info
Module Manufacturer          = Quectel
Module Model                 = EC25E
Module Firmware              = EC25EFAR06A01M4G_TEL
Hardware Revision            = 10000
Modem/App Firmware           = EC25EFAR06A01M4G_TEL_01.300.01.300
IMEI                         = 866308062070222
IMSI                         = 214075541654235
ICCID                        = 8934075700105849704F
Radio Interfaces             = gsm, umts, lte
Data Service Capability      = non-simultaneous-cs-ps
Maximum TX/RX rate supported = 50000/100000 Kbps

The controllers cellular <value> show temperature command displays the current temperature of the cellular module.

Example:

admin@osdx$ controllers cellular wwan0 show temperature
Temperature = 44

The controllers cellular <value> show supported-bands command displays the bands supported by the cellular module.

Example:

admin@osdx$ controllers cellular wwan0 show supported-bands
Bands     = gsm-dcs-1800, gsm-900-extended, gsm-900-primary, wcdma-2100, wcdma-850-us, wcdma-900
LTE bands = 1, 3, 5, 7, 8, 20, 38, 40, 41

The controllers cellular <value> show preferred-bands command shows the preferred bands to be used by the cellular module.

Example:

admin@osdx$ controllers cellular wwan0 show preferred-bands
Bands preference     = gsm-dcs-1800, gsm-900-extended, gsm-900-primary, wcdma-2100, wcdma-850-us, wcdma-900
LTE bands preference = 1, 3, 5, 7, 8, 20, 38, 40, 41

The controllers cellular <value> show cell-info command displays information about the serving cell and neighboring cells.

Example:

admin@osdx$ controllers cellular wwan0 show cell-info
LTE intrafrequency info:
   UE in idle mode                   = no
   PLMN ID coded                     = 21407
   Tracking Area Code                = 11091
   Global cell ID                    = 28195872
   E-UTRA absolute RF channel number = 2850
   LTE serving cell ID               = 290
   Cell #0
      Physical cell ID        = 290
      Current RSRQ (dB)       = -11.300000
      Current RSRP (dBm)      = -109.300000
      Current RSSI (dBm)      = -76.200000
      Cell selection Rx Level = 0
LTE interfrequency info:
   UE in idle mode = no
LTE info - Neighboring GSM:
   UE in idle mode = no
LTE info - Neighboring WCDMA:
   UE in idle mode = no

The controllers cellular <value> show signal-quality command displays information about the quality of the signal received by the cellular module.

Example:

admin@osdx$ controllers cellular wwan0 show signal-quality
LTE:
   RSSI (dBm) = -78
   RSRP (dBm) = -109
   RSRQ (dB)  = -8
   SNR (dB)   = 12.000000
Tx level in traffic (dBm) = 10.200000
Rx Chain #0
   Radio tuned    = yes
   Rx Level (dBm) = -80.700000
   ECIO (dB)      = 8.400000
   RSRP (dBm)     = 109.100000
   Phase (deg)    = 0.000000
Rx Chain #1
   Radio tuned    = yes
   Rx Level (dBm) = -82.200000
   ECIO (dB)      = 8.200000
   RSRP (dBm)     = 110.400000
   Phase (deg)    = 0.000000

The controllers cellular <value> show network-data-connection command displays information about the network data connection.

Example:

admin@osdx$ controllers cellular wwan0 show network-data-connection
PDP #1
   Connection status          = connected
   Traffic channel status     = active
   Max. TX channel rate (bps) = 50000000
   Max. RX channel rate (bps) = 150000000
   IPv4 address               = 37.13.233.100
   IPv4 mask                  = 255.255.255.248
   IPv4 gateway               = 37.13.233.101
   IPv4 primary DNS           = 80.58.61.250
   IPv4 secondary DNS         = 80.58.61.254
PDP #2
   Connection status          = disconnected
PDP #3
   Connection status          = disconnected
PDP #4
   Connection status          = disconnected

Finally, the controllers cellular <value> reconnect command allows the user to force the cellular module to reconnect to the mobile broadband network. Additionally, the controllers cellular <value> pdp <u32> reconnect command can be used to reconnect a specific cellular PDP.

Cellular

Profile 

Accessibility Control 

Personal Identification Number (PIN)

Network Mode 

SIM Sockets 

Configuring SIM Sockets 

SIM Socket Supervision 

eSIM Socket 

Examples 

Single-APN 

Multi-APN 

Monitoring 

Command Summary 

Configuration commands 

Operational commands 