Cellular Network

API Reference


The Cellular Network service ensures that the modem is registered on the network when an user application makes a request for network access. This includes:

  • ensuring that the radio is turned on.
  • ensuring that there is a valid SIM, and it is unlocked.
  • ensuring that the modem is registered on the network.

If all of the above conditions are met, then the service indicates that the network is available.

IPC interfaces binding

All the functions of this API are provided by the cellNetService application service.

Here's a code sample binding to Cellular Network services:

bindings:
{
   clientExe.clientComponent.le_cellnet -> cellNetService.le_cellnet
}

Requesting the Cellular Network

The Cellular Network can be requested using le_cellnet_Request(). This function will turn on the radio if it is switched off and it will unlock the SIM if a PIN code is required (the necessary information will be retrieved from the secure storage, cf. Cellular Network configuration).

Before the cellular network is requested, an application should register a network state handler using le_cellnet_AddStateEventHandler(). Once the cellular network becomes available, the handler will be called to indicate that the modem is now registered on the network.

If the state of the network changes, then the handler will be called with the new state. The current cellular network state can also be retrieved with le_cellnet_GetNetworkState().

Note
There might be a discrepancy between the state notified by the handler and the state retrieved through le_cellnet_GetNetworkState(): the state can have changed between the event notification and its treatment by the application.

To release the cellular network, an application can use le_cellnet_Release(). Once all user applications release the cellular network access, then the service will turn off the radio.

The application can release the network state handler by calling le_cellnet_RemoveStateEventHandler() when it is not needed anymore.

All configuration data required for a network registration, such as the PIN code of the SIM, will be stored in the secure storage by the use of the le_cellnet_SetSimPinCode() function.

Cellular Network configuration

Setting the SIM PIN code in the secure storage and retrieving it is performed by two functions: le_cellnet_SetSimPinCode() and le_cellnet_GetSimPinCode().

The le_cellnet_SetSimPinCode() function stores the PIN code in the secure storage and takes two parameters: the SIM identifier and the SIM card PIN code.

Note
The function erases the previously stored SIM card PIN code.
It is possible to set and retry a void entry ("") corresponding to an unlocked SIM.

The le_cellnet_GetSimPinCode() function retrieves the SIM card PIN code from the secure storage and takes one parameter: the SIM identifier.

Note
The action carried out by the Cellular Network Service when a new SIM is inserted depends on the SIM state:
  • if the SIM is locked, it will automatically read the secure storage in order to try to enter the PIN code for the SIM card. If the PIN code is not set or too long (max 8 digits), an error will be logged and the SIM will not be unlocked.
  • is the SIM is blocked, it just logs an error and does not try to enter the PUK code.