The Modem Radio Control (MRC) APIs is used to control cellular network environments.

It's important for many M2M apps to know details about cellular network environments (like network registration and signal quality). It allows you to limit some M2M services based on the reliability of the network environment, and provides information to control power consumption (power on or shutdown the radio module).

IPC interfaces binding

All the functions of this API are provided by the modemService service.

Here's a code sample binding to modem services:

  bindings:
  {
     clientExe.clientComponent.le_mrc -> modemService.le_mrc
  }

Radio Power Management

le_mrc_SetRadioPower() API allows the application to power up or shutdown the radio module.

le_mrc_GetRadioPower() API displays radio module power state.

A sample code can be seen in the following page:

Sample code for Radio Power Management

Radio Configuration preferences

The following functions let you configure and retrieve the radio configuration preferences: le_mrc_SetAutomaticRegisterMode(), le_mrc_SetManualRegisterMode() and le_mrc_GetRegisterMode() let you set/get the selected Scan mode.

le_mrc_SetBandPreferences(), le_mrc_GetBandPreferences() let you set/get the 2G/3G band preferences by using a bit mask built with le_mrc_BandBitMask_t

The 2G/3G band preferences can be:

Band-Class-0-A-System
Band-Class-0-B-System
Band-Class-1-All-Blocks
Band-Class-2-Placeholder
Band-Class-3-A-System
Band-Class-4-All-Blocks
Band-Class-5-All-Blocks
Band-Class-6
Band-Class-7
Band-Class-8
Band-Class-9
Band-Class-10
Band-Class-11
Band-Class-12
Band-Class-13
Band-Class-14
Band-Class-15
Band-Class-16
Band-Class-17
Band-Class-18
Band-Class-19
GSM-DCS-1800
E-GSM-900 (for Extended GSM 900 band)
Primary-GSM-900
GSM-450
GSM-480
GSM-750
GSM-850
GSMR-900 (for GSM Railways GSM 900 band)
GSM-PCS-1900
WCDMA-EU-J-CH-IMT-2100 (for WCDMA Europe, Japan, and China IMT 2100 band)
WCDMA-US-PCS-1900 (for WCDMA U.S. PCS 1900 band)
WCDMA-EU-CH-DCS-1800 (for WCDMA Europe and China DCS 1800 band)
WCDMA-US-1700 (for WCDMA U.S. 1700 band)
WCDMA-US-850 (for WCDMA U.S. 850 band)
WCDMA-J-800 (for WCDMA Japan 800 band)
WCDMA-EU-2600 (for WCDMA Europe 2600 band)
WCDMA-EU-J-900 (for WCDMA Europe and Japan 900 band)
WCDMA-J-1700 (for WCDMA Japan 1700 band)

le_mrc_SetLteBandPreferences(), le_mrc_GetLteBandPreferences() let you set/get the LTE band preferences by using a bit mask built with le_mrc_LteBandBitMask_t.

The LTE band preferences can be 0 to 43 except 15, 16, 22, 23, and 26 to 32.

le_mrc_SetTdScdmaBandPreferences(), le_mrc_GetTdScdmaBandPreferences() let you set/get the TD-SCDMA band preferences by using a bit mask built with le_mrc_TdScdmaBandBitMask_t

The TD-SCDMA band preferences can be 'A' to 'F'

Warning: Ensure to check the supported preferences for your specific platform.

le_mrc_AddPreferredOperator() , le_mrc_RemovePreferredOperator() to add/remove a preferred operator by specifying the MCC/MNC and the Radio Access Technology.

le_mrc_GetPreferredOperatorsList(), le_mrc_GetFirstPreferredOperator(), le_mrc_GetNextPreferredOperator(), le_mrc_DeletePreferredOperatorsList(), le_mrc_GetPreferredOperatorDetails() let you retrieve a list of the selected preferred operators and get their details.

A sample code can be seen in the following page:

Sample code for Radio Configuration Preferences

Report Network Reject Indication

The application can register a handler function to report network reject with MNC/MCC code and the Radio Access Technology using le_mrc_AddNetworkRejectHandler() API.

le_mrc_RemoveNetworkRejectHandler() API uninstalls the handler function.

Radio Capabilities

le_mrc_GetBandCapabilities() let you get the 2G/3G band capabilities by retrieving a bit mask built with le_mrc_BandBitMask_t

le_mrc_GetLteBandCapabilities() let you get the LTE band capabilities by retrieving a bit mask built with le_mrc_LteBandBitMask_t

le_mrc_GetTdScdmaBandCapabilities() let you get the TD-SCDMA band capabilities by retrieving a bit mask built with le_mrc_TdScdmaBandBitMask_t

A sample code can be seen in the following page:

Sample code for Band Capabilities

Radio Access Technology (RAT)

le_mrc_GetRadioAccessTechInUse() API retrieves the current active Radio Access Technology (RAT).

Note: The API returns the RAT only if the device is registered on the network.

The application can register a handler function to retrieve the Radio Access Technology each time the RAT changes.

le_mrc_AddRatChangeHandler() API installs a RAT change handler.

le_mrc_RemoveRatChangeHandler() API uninstalls the handler function.

le_mrc_SetRatPreferences(), le_mrc_GetRatPreferences() let you set/get the Radio Access Technology preferences by using a bit mask built with le_mrc_RatBitMask_t.

The Radio Access Technology preferences can be:

CDMA (CDMA2000-1X + CDMA2000-HRPD)
GSM
UMTS (UMTS)
TDSCDMA (TD-SCDMA)
LTE

Note: LE_MRC_BITMASK_RAT_ALL value can be used to select the RAT in automatic mode.

A sample code can be seen in the following page:

Sample code for Radio Access Technology

Network Registration

le_mrc_GetNetRegState() API retrieves the radio module network registration status.

The application can register a handler function to retrieve the registration status each time the registration state changes.

le_mrc_AddNetRegStateEventHandler() API installs a registration state handler.

le_mrc_RemoveNetRegStateEventHandler() API uninstalls the handler function.

Note: If only one handler is registered, the le_mrc_RemoveNetRegStateHandler() API resets the registration mode to its original value before any handler functions were added.

le_mrc_SetManualRegisterMode() API registers on a cellular network.

Call le_mrc_SetManualRegisterModeAsync() function to set the manual registration mode asynchronously. The function is not blocking. The response will be returned with the le_mrc_ManualSelectionHandlerFunc_t handler function.

When the network registration fails, the platform specific network registration error code can be known by using le_mrc_GetPlatformSpecificRegistrationErrorCode() API. Please refer to Platform specific error codes for platform specific registration error code description.

A sample code can be seen in the following page:

Sample code for Network Registration

Packet services state

le_mrc_GetPacketSwitchedState() API retrieves the current Packet Switched state le_mrc_NetRegState_t.

The Packet Switched services state can be:

NONE
HOME
ROAMING

The application can register a handler function to retrieve the Packet Switched state each time the service state changes.

le_mrc_AddPacketSwitchedChangeHandler() API installs a Packet Switched state handler.

le_mrc_RemovePacketSwitchedChangeHandler() API uninstalls the handler function.

A sample code can be seen in the following page:

Sample code for Get the Current Packet Switched state

Signal Quality

le_mrc_GetSignalQual() retrieves the received signal strength details.

You must call le_mrc_MeasureSignalMetrics() to measure the signal metrics of the serving cell (aka the 'serving' cell). It returns a reference of le_mrc_MetricsRef_t type.

When the signal metrics are no longer needed, you must call le_mrc_DeleteSignalMetrics() to free all allocated ressources associated with the Metrics object.

le_mrc_GetRatOfSignalMetrics() returns the Radio Access Technology of the signal measures.

le_mrc_GetGsmSignalMetrics() the signal strength in dBm and the bit error rate measured on GSM network.

le_mrc_GetUmtsSignalMetrics() returns the signal metrics measured on UMTS or TD-SCDMA networks.

le_mrc_GetLteSignalMetrics() returns the signal metrics measured on LTE network.

le_mrc_GetCdmaSignalMetrics() returns the signal metrics measured on CDMA network.

The application can register a handler function to get notifications when the signal strength changes of a certain threshold value.

le_mrc_AddSignalStrengthChangeHandler() API installs a signal strength change handler. The RAT, the lower-range and the upper-range thresholds must be passed as input parameters. These parameters are updated each time the function is called, the previous thresholds are replaced by the new ones if the function is called with the same RAT. The event is notified when we cross the range limits in both direction.

Warning: A fatal error will be thrown if the RAT is not valid and the le_mrc_AddSignalStrengthChangeHandler function won't return.

le_mrc_RemoveSignalStrengthChangeHandler() API uninstalls the handler function.

le_mrc_SetSignalStrengthIndThresholds() API changes or sets new thresholds.

le_mrc_SetSignalStrengthIndDelta() API sets a signal strength indication delta value for a specific RAT. The event is notified when the delta range is crossed in both direction.

A sample code can be seen in the following page:

Sample code for Signal Quality

Serving cell's location information

le_mrc_GetServingCellId() retrieves the the serving Cell Identifier.

le_mrc_GetServingCellLocAreaCode() retrieves the Location Area Code of the serving cell.

le_mrc_GetServingCellLteTracAreaCode() retrieves the the Tracking Area Code of the serving cell (LTE only).

A sample code can be seen in the following page:

Sample code for Location information

Current Network Information

le_mrc_GetCurrentNetworkName() retrieves the Current Network Name. le_mrc_GetCurrentNetworkMccMnc() retrieves the Current Network PLMN information.

A sample code can be seen in the following page:

Sample code for Get Current Network Information

Network Scan

Call le_mrc_PerformCellularNetworkScan() to fill a list of all network in sight. You can go through all Scan Information by calling le_mrc_GetFirstCellularNetworkScan() and le_mrc_GetNextCellularNetworkScan().

Call le_mrc_PerformCellularNetworkScanAsync() to start a network scan asynchronously. The function is not blocking. The scan list reference will be returned with the handler function response (le_mrc_CellularNetworkScanHandlerFunc_t).

For each Scan Information, you can call:

le_mrc_GetCellularNetworkMccMnc() to have the operator code.
le_mrc_GetCellularNetworkName() to get the operator name.
le_mrc_GetCellularNetworkRat() to get the radio access technology.
le_mrc_IsCellularNetworkInUse() to check if this is currently in use by the network.
le_mrc_IsCellularNetworkAvailable() to check if this is available.
le_mrc_IsCellularNetworkHome() to check if this is in home status.
le_mrc_IsCellularNetworkForbidden() to check if this is forbidden by the network.

le_mrc_DeleteCellularNetworkScan() should be called when you do not need the list anymore.

A sample code can be seen in the following page:

Sample code for Network Scan

PCI Network Scan

Call le_mrc_PerformPciNetworkScan() to fill a list of all neighboring cells. The Pci scan is used to get the according MCC/MNC for each neightboring cells ID. Not that a cell may contain more than one MCC/MNC when sevral plmn sharing the same cell. You can go through all Scan Information by calling le_mrc_GetFirstPciScanInfo() and le_mrc_GetNextPciScanInfo(). Note that each cell info contains a list of mcc/mnc, you can go through all mcc/mnc Information for each cell by calling le_mrc_GetFirstPlmnInfo() and le_mrc_GetNextPlmnInfo(), this two APIs return a reference to PlmnInformation, then use le_mrc_GetPciScanMccMnc() by giving this reference as parameter to get the Mcc/Mnc of the Plmn. Call le_mrc_PerformPciNetworkScanAsync()to start a pci scan asynchronously. The function is not blocking. The scan list reference will be returned with the handler function response (le_mrc_PciNetworkScanHandlerFunc_t).

For Pci Network Scan Information, you can call:

le_mrc_GetPciScanCellId() to get the id of each cell.
le_mrc_GetPciScanMccMnc() to get the Mcc/Mnc of each plmn on each cell.
le_mrc_DeletePciNetworkScan() should be called when you do not need the list anymore.

This code sample shows how to use the PCI scan API and display the apropriate values

*void DisplayPciScanInfo
*(
     void
 )
 {
     uint16_t celId = O;
     char mcc[LE_MRC_MCC_BYTES] = {0};
     char mnc[LE_MRC_MNC_BYTES] = {0};
     le_mrc_PciScanInformationListRef_t scanInfoListRef = NULL;
     le_mrc_PciScanInformationRef_t     scanInfoRef = NULL;
     le_mrc_PlmnInformationRef_t        plmnInfoRef = NULL;
 
     scanInfoListRef = le_mrc_PerformPciNetworkScan(LE_MRC_BITMASK_RAT_LTE);
     LE_ASSERT(scanInfoListRef != NULL);
 
     // Get the information (cell, Mcc,Mnc) of the first cell.
     scanInfoRef = le_mrc_GetFirstCellularNetworkScan(scanInfoListRef);
 
     celId = le_mrc_GetPciScanCellId (scanInfoRef);
 
     // Get the first plmn information of the first cell.
     PlmnInfoRef = le_mrc_GetFirstPlmnInfo(scanInfoRef);
     le_mrc_GetPciScanMccMnc(PlmnInfoRef, mcc, LE_MRC_MCC_BYTES, mnc, LE_MRC_MCC_BYTES);
     LE_INFO("Cell id is %"PRIu16", Mcc is %s, Mnc is %s !",celId, mcc, mnc");
 
     // Get the next plmn information of the first cell.
     while ((PlmnInfoRef = le_mrc_GetNextPlmnInfo(scanInfoRef)) != NULL)
     {
         le_mrc_GetPciScanMccMnc(PlmnInfoRef, mcc, LE_MRC_MCC_BYTES, mnc, LE_MRC_MCC_BYTES);
          LE_INFO("Cell id is %"PRIu16", Mcc is %s, Mnc is %s !",celId, mcc, mnc");
     }
 
     // Get the information (cell, Mcc,Mnc) of the next cells.
     while ((scanInfoRef = le_mrc_GetNextCellularNetworkScan(scanInfoListRef)) != NULL)
     {
         celId = le_mrc_GetPciScanCellId (scanInfoRef);
 
         PlmnInfoRef = le_mrc_GetFirstPlmnInfo(scanInfoRef);
         le_mrc_GetPciScanMccMnc(PlmnInfoRef, mcc, LE_MRC_MCC_BYTES, mnc, LE_MRC_MCC_BYTES);
         LE_INFO("Cell id is %"PRIu16", Mcc is %s, Mnc is %s !",celId, mcc, mnc");
         while ((PlmnInfoRef = le_mrc_GetNextPlmnInfo(scanInfoRef)) != NULL)
         {
             le_mrc_GetPciScanMccMnc(PlmnInfoRef, mcc, LE_MRC_MCC_BYTES, mnc, LE_MRC_MCC_BYTES);
             LE_INFO("Cell id is %"PRIu16", Mcc is %s, Mnc is %s !",celId, mcc, mnc");
         }
     }
     le_mrc_DeletePciNetworkScan(scanInfoListRef);
 }

Neighboring Cells Information

Warning: The following functions do not apply to CDMA network.

You must call le_mrc_GetNeighborCellsInfo() to retrieve the neighboring cells information. It returns a reference of le_mrc_NeighborCellsRef_t type.

When the neighboring cells information is no longer needed, you must call le_mrc_DeleteNeighborCellsInfo() to free all allocated resources associated with the object.

Then, you can use the following function to get the information:

le_mrc_GetFirstNeighborCellInfo() and le_mrc_GetFirstNeighborCellInfo() allow to go among the single cell information retrieved with le_mrc_GetNeighborCellsInfo(). These two functions return a reference of le_mrc_CellInfoRef_t type.
le_mrc_GetNeighborCellId() gets the identifier of the cell specified with the le_mrc_CellInfoRef_t parameter (can be called for any kind of RAT). UINT32_MAX value is returned if the value is not available.
le_mrc_GetNeighborCellLocAreaCode() gets the location area code of the cell specified with the le_mrc_CellInfoRef_t parameter (can be called for any kind of RAT). UINT16_MAX value is returned if the value is not available.
le_mrc_GetNeighborCellRxLevel() gets the signal strength (in dBm) of the cell specified with the le_mrc_CellInfoRef_t parameter (can be called for any kind of RAT).
le_mrc_GetNeighborCellRat() gets the Radio Access Technology of the cell specified with the le_mrc_CellInfoRef_t parameter.
le_mrc_GetNeighborCellUmtsEcIo() gets the Ec/Io (the received energy per chip divided by the power density in the band measured in dBm on the primary CPICH channel of serving cell) of the cell specified with the le_mrc_CellInfoRef_t parameter.
le_mrc_GetNeighborCellLteIntraFreq() gets the RSRP and RSRQ of the Interfrequency of the cell specified with the le_mrc_CellInfoRef_t parameter.
le_mrc_GetNeighborCellLteInterFreq() gets the RSRP and RSRQ of the Interfrequency of the cell specified with the le_mrc_CellInfoRef_t parameter.

A sample code can be seen in the following page:

Sample code for Neighboring Cells Information

Jamming detection

The jamming detection algorithm is based on power measurements and cell synchronization actions performed during a GSM network scan procedure. During this procedure some intermediate results are reported, that allows user to take some preventive actions if necessary. This result is reported as a jammed state probability. See le_mrc_JammingStatus_t enumeration for probability description. Each time the jamming status changes during the scan procedure, it is reported to the user. See le_mrc_JammingReport_t enumeration for details.

The jamming status is reported:

In an unsolicited way, each time the protocol stack initiates a scan for PLMN selection or reselection.
On user demand, when a user PLMN scan is performed.

Call le_mrc_StartJammingDetection() to launch jamming monitoring. By registering a handler by calling le_mrc_AddJammingDetectionEventHandler(), the notification on jamming detection can be sent to the registered application.

For each jamming detection monitoring, the following APIs can be called:

le_mrc_StartJammingDetection() to start the jamming monitoring.
le_mrc_StopJammingDetection() to stop the jamming monitoring.
le_mrc_AddJammingDetectionEventHandler() to register an event handler.
le_mrc_RemoveJammingDetectionEventHandler() to remove an event handler.

SAR backoff

SAR (Specific Absorption Rate) is a measure of RF energy absorption by the human body. Users can dynamically select a pre-configured SAR backoff state so they can adjust the SAR depending on their needs. To manage SAR backoff, these API should be used:

le_mrc_SetSarBackoffState() to set a new SAR backoff state.
le_mrc_GetSarBackoffState() to get the current SAR backoff state. This feature may be unsupported by some targets. Also, the number of supported states may vary depending on the target. Please refer to Modem Control platform constraints for further details.