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
Network Registration
Signal Quality
Home Network Information
Network Scan
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.

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_ConnectCellularNetwork() API connects to one 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_ScanInformation_ListRef_t scanInformationList = NULL;

    scanInformationList = le_mrc_PerformCellularNetworkScan(LE_MRC_RAT_ALL);

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

    le_mrc_ScanInformation_Ref_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);

Configuration tree

The configuration database path for the MRC is:

   /
       modemServices/
           radioControl/
               preferredList/
                   network-0/
                       mcc<int> = <MCC_VALUE>
                       mnc<int> = <MNC_VALUE>
                       rat/
                           rat-0<string> = <RAT_VALUE>
                           ...
                           rat-n<string> = <RAT_VALUE>
                   ...
                   network-n/
                       mcc<int> = <MCC_VALUE>
                       mnc<int> = <MNC_VALUE>
                       rat/
                           rat-0<string> = <RAT_VALUE>
                           ...
                           rat-n<string> = <RAT_VALUE>
               scanMode/
                   manual<bool>
                   mcc<int> = <MCC_VALUE>
                   mnc<int> = <MNC_VALUE>

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"
- "UTMS"
- "LTE"
- "GSM compact"