This file contains the the prototype definitions of the high level Modem Radio Control (MRC) APIs.

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).

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.

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.

Radio Access Technology (RAT)

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

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 + TD-SCDMA)
LTE

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

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_RemoveNetRegStateHandler() 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_RegisterCellularNetwork() API registers on a cellular network.

Signal Quality

le_mrc_GetSignalQual() retrieves the received signal strength details.

Current Network Information

le_mrc_GetCurrentNetworkName() retrieves the Current Network Name. le_mrc_GetCurrentNetworkMccMnc() retrieves the Current Network PLMN 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().

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.

Usage example:

le_mrc_ScanInformationListRef_t scanInformationList = NULL;
scanInformationList = le_mrc_PerformCellularNetworkScan(LE_MRC_BITMASK_RAT_ALL);
if (!scanInformationList)
{
    fprintf(stdout, "Could not perform scan\n");
    return;
}
le_mrc_ScanInformationRef_t cellRef;
for (cellRef=le_mrc_GetFirstCellularNetworkScan(scanInformationList);
     cellRef!=NULL;
     cellRef=le_mrc_GetNextCellularNetworkScan(scanInformationList))
{
    le_mrc_Rat rat;
    char mcc[4],mnc[4];
    char name[100];
    rat = le_mrc_GetCellularNetworkRat(cellRef);
    fprintf(stdout, "Rat %d ",rat);
    if (le_mrc_GetCellularNetworkMccMnc(cellRef,mcc,sizeof(mcc),mnc,sizeof(mnc))!=LE_OK)
    {
        fprintf(stdout, "Failed to get operator code.\n");
    }
    else
    {
        fprintf(stdout, "[%s-%s] ",mcc,mnc);
    }
    if (le_mrc_GetCellularNetworkName(cellRef, name, sizeof(name)) != LE_OK)
    {
        fprintf(stdout, "Failed to get operator name.\n");
    }
    else
    {
        fprintf(stdout, "%-32s",name);
    }
    fprintf(stdout,"%-15s,",le_mrc_IsCellularNetworkInUse(cellRef)?"Is used":"Is not used");
    fprintf(stdout,"%-20s,",le_mrc_IsCellularNetworkAvailable(cellRef)?"Is available":"Is not available");
    fprintf(stdout,"%-10s,",le_mrc_IsCellularNetworkHome(cellRef)?"Home":"Roaming");
    fprintf(stdout,"%-10s]\n",le_mrc_IsCellularNetworkForbidden(cellRef)?"Forbidden":"Allowed");
}
le_mrc_DeleteCellularNetworkScan(scanInformationList);

Neighboring Cells Information

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 ressources 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. le_mrc_GetNeighborCellLac() gets the location area code of the cell specified with the le_mrc_CellInfoRef_t parameter. le_mrc_GetNeighborCellRxLevel() gets the signal strength (in dBm) of the cell specified le_mrc_CellInfoRef_t parameter.

Copyright (C) Sierra Wireless Inc. Use of this work is subject to license.