Modem Radio Control

Click here for the API reference documentation.

---

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

Radio Power Management
Radio Access Technology
Network Registration
Signal Quality
Home Network Information
Network Scan
Neighboring Cells Information
Radio configuration tree

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 Access Technology

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.

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

Home Network Information

le_mrc_GetHomeNetworkName() retrieves the Home Network Name. This value can be empty even if connected to a GSM network.

Note

Maybe need to provide an API to get 'Mobile country code' and 'Mobile Network Code'.

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_IsCellularNetworkRatAvailable() to check is this is 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_RAT_ALL);

if (!scanInformationList)
{
    fprintf(stdout, "Could not perform scan\n");
    return;
}

le_mrc_ScanInformationRef_t cellRef;

uint32_t i;
for (i=1;i<LE_MRC_RAT_ALL;i=i<<1)
{

    for (cellRef=le_mrc_GetFirstCellularNetworkScan(scanInformationList);
         cellRef!=NULL;
         cellRef=le_mrc_GetNextCellularNetworkScan(scanInformationList))
    {
        char mcc[4],mnc[4];
        char name[100];

        if (le_mrc_IsCellularNetworkRatAvailable(cellRef,i)) {

            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.

Radio configuration tree

The configuration database path for the Radio is:

 /
     modemServices/
         radio/
             preferredOperators/
                 0/
                     mcc<int> = <MCC_VALUE>
                     mnc<int> = <MNC_VALUE>
                     rat/
                         0<string> = <RAT_VALUE>
                         1<string> = <RAT_VALUE>
                         ...
                 1/
                     mcc<int> = <MCC_VALUE>
                     mnc<int> = <MNC_VALUE>
                     rat/
                         0<string> = <RAT_VALUE>
                         1<string> = <RAT_VALUE>
                         ...
                 ...

             scanMode/
                 manual<bool>
                 mcc<int> = <MCC_VALUE>
                 mnc<int> = <MNC_VALUE>

             preferences/
                 rat/
                     0<string> == <Rat>
                     1<string> == <Rat>
                     2<string> == <Rat>
                     ...
                 band/
                     0<string> == <Band>
                     1<string> == <Band>
                     2<string> == <Band>
                     ...
                 lteBand/
                     0<string> == <LteBand>
                     1<string> = <LteBand>
                     2<string> = <LteBand>
                     ...
                 tdScdmaBand/
                     0<string> = <TdScdmaBand>
                     1<string> = <TdScdmaBand>
                     2<string> = <TdScdmaBand>
                     ...

The preferred operators can be set using the following choices (string type):

• MCC_VALUE is the Mobile Country Code
• MNC_VALUE is the Mobile Network Code
• RAT_VALUE is the Radio Access technology.Possible values are:
  • "GSM"
  • "UMTS"
  • "LTE"

The Radio Access Technology preferences can be set with the following choices (string type):

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

The 2G/3G Band preferences can be set with the following choices (string type):

• "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)

The LTE Band preferences can be set by specifying the number of E-UTRA operating band, 0 to 43 except: 15, 16, 22, 23, and 26 to 32.

The TD-SCDMA Band preferences can be set with the following choices (string type): "A" to "F".

---

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