Radio Service

API Reference

---

The Radio Service APIs contain phone and network functions and is applied to configure and obtain wireless cellular network information. By default, the radio service is powered on and available by the system.

IPC interfaces binding

The functions of this API are provided by the tafRadioSvc service.

The following example illustrates how to bind to the Radio service.

bindings:
{
    clientExe.clientComponent.taf_radio -> tafRadioSvc.taf_radio
}

Power Management

Users can power on or power off the radio, but by default it is powered on.

• taf_radio_SetRadioPower() / taf_radio_GetRadioPower() – Sets/gets radio power status.

The following example illustrates powering on the radio.

le_onoff_t power = LE_OFF;

if (taf_radio_SetRadioPower(LE_ON, phoneId) != LE_OK)
    LE_ERROR("Fail to set radio power.");

if (taf_radio_GetRadioPower(&power, phoneId) != LE_OK)
    LE_ERROR("Fail to get radio power status.");

if (power != LE_ON)
    LE_ERROR("Unexpected power status.");

Network Registration

Users can register with the network automatically or manually with specific MCC and MNC.

• taf_radio_SetAutomaticRegisterMode() – Registers with a network automatically.
• taf_radio_SetManualRegisterMode() – Registers with a network with MCC and MNC manually.
• taf_radio_GetRegisterMode() – Gets the network register mode.
• taf_radio_SetManualRegisterModeAsync() – Registers with a network asynchronously with a handler.
• taf_radio_AddNetRegRejectHandler() / taf_radio_RemoveNetRegRejectHandler() – Adds/removes handler for network registration rejection.
• taf_radio_GetPlatformSpecificRegistrationErrorCode() – Gets the network registration error code.

The following example illustrates network registration.

if (taf_radio_SetManualRegisterMode(mccStr1, mncStr1, phoneId) == LE_OK)
    LE_ERROR("Fail to set manual register mode.");

LE_INFO("Platform registration error code: %d.", taf_radio_GetPlatformSpecificRegistrationErrorCode());

bool isManualMode = false;
if (taf_radio_GetRegisterMode(&isManualMode, mccStr2, TAF_RADIO_MCC_BYTES, mncStr2,
    TAF_RADIO_MNC_BYTES, phoneId) != LE_OK)
    LE_ERROR("Fail to get register mode.");

if (!isManualMode)
    LE_ERROR("Unexpected register mode.");

if (strcmp(mccStr1, mccStr2) != 0)
    LE_ERROR("Unexpected MCC.");

if (strcmp(mncStr1, mncStr2) != 0)
    LE_ERROR("Unexpected MNC.");

Preferred Operators

Users can configure the preferences of operators and get the configuration details with a list.

• taf_radio_GetPreferredOperatorsList() / taf_radio_DeletePreferredOperatorsList() – Creates/deletes a preferred operator list reference.
• taf_radio_AddPreferredOperator() / taf_radio_RemovePreferredOperator() – Adds/removes a preferred operator.
• taf_radio_GetFirstPreferredOperator() / taf_radio_GetNextPreferredOperator() – Gets the first/next preferred operator reference.
• taf_radio_GetPreferredOperatorDetails() – Gets the operator details.

The following example illustrates preferred operator list management.

// Add preference.
for (int i = 0; i < PREFERRED_OPERATOR_NUM; i++) {
    taf_radio_AddPreferredOperator(prefMccStr[i], prefMncStr[i], prefRatMask, phoneId);
}

// Create list.
listRef = taf_radio_GetPreferredOperatorsList(phoneId);

// Traverse list
opRef = taf_radio_GetFirstPreferredOperator(listRef);
while (opRef != nullptr) {
    taf_radio_GetPreferredOperatorDetails(opRef, mccStr, TAF_RADIO_MCC_BYTES, mncStr,
        TAF_RADIO_MNC_BYTES, &ratMask);

    // Do something with the operator details.

    opRef = taf_radio_GetNextPreferredOperator(listRef);
}

// Delete list.
taf_radio_DeletePreferredOperatorsList(listRef);

// Remove preference.
for (int i = 0; i < PREFERRED_OPERATOR_NUM; i++) {
    taf_radio_RemovePreferredOperator(prefMccStr[i], prefMncStr[i], phoneId);
}

Radio Access Technology

Users can get RAT in use, and configure RAT preferences.

• taf_radio_GetRadioAccessTechInUse() – Gets radio access technology in use.
• taf_radio_AddRatChangeHandler() / taf_radio_RemoveRatChangeHandler() – Adds/removes RAT change handler.
• taf_radio_SetRatPreferences() / taf_radio_GetRatPreferences() – Sets/gets RAT peferences.

The following example illustrates RAT change indication.

// RAT change indication handler.
static void RatChangeHandler(const taf_radio_RatChangeInd_t* indPtr, void* contextPtr)
{
    LE_INFO("RAT: %d", indPtr->rat);
}

// Add handler for RAT change.
handlerRef = taf_radio_AddRatChangeHandler((taf_radio_RatChangeHandlerFunc_t)RatChangeHandler, NULL);

// RAT change in some cases.

Packet-Switched State

Users can get the packet-switched (PS) state.

• taf_radio_GetPacketSwitchedState() – Gets the PS state.
• taf_radio_AddPacketSwitchedChangeHandler() / taf_radio_RemovePacketSwitchedChangeHandler() – Adds/removes PS change handler.

The following example illustrates the PS change indication.

// PS change indication handler.
static void PsChangeHandler(const taf_radio_NetRegState_t state, void* contextPtr)
{
    LE_INFO("PS state: %d", state);
}

// Add handler for PS change.
handlerRef = taf_radio_AddPacketSwitchedChangeHandler(
   (taf_radio_PacketSwitchedChangeHandlerFunc_t)PsChangeHandler, NULL);

// PS change in some cases.

Signal Metrics

Users can measure signal and get metrics for different RATs.

• taf_radio_GetSignalQual() – Gets the highest signal strength level.
• taf_radio_MeasureSignalMetrics() / taf_radio_DeleteSignalMetrics() – Creates/deletes the signal metrics reference.
• taf_radio_GetRatOfSignalMetrics() – Gets RATs of signal metrics.
• taf_radio_GetGsmSignalMetrics() / taf_radio_GetUmtsSignalMetrics() / taf_radio_GetLteSignalMetrics() / taf_radio_GetCdmaSignalMetrics() – Gets GSM/UMTS/LTE/CDMA signal metrics.
• taf_radio_AddSignalStrengthChangeHandler() / taf_radio_RemoveSignalStrengthChangeHandler() – Adds/removes signal strength change handler.
• taf_radio_SetSignalStrengthIndThresholds() / taf_radio_SetSignalStrengthIndDelta() – Sets signal strength reporting criteria. Either the threshold or delta can be set at a time.
• taf_radio_SetSignalStrengthIndHysteresis() / taf_radio_SetSignalStrengthIndHysteresisTimer() – Sets the optional parameters for signal strength reporting criteria. Hysteresis is applicable only when threshold is set. Hysteresis timer is applicable for both threshold and delta.This API needs to be called before taf_radio_SetSignalStrengthIndThresholds() and taf_radio_SetSignalStrengthIndDelta().

The following example illustrates getting LTE signal metrics.

metricRef = taf_radio_MeasureSignalMetrics(phoneId);
ratMask = taf_radio_GetRatOfSignalMetrics(metricRef);
if (ratMask & TAF_RADIO_RAT_BIT_MASK_LTE) {
    if (taf_radio_GetLteSignalMetrics(metricsRef, &ss, &rsrq, &rsrp, &snr) == LE_OK) {
        LE_INFO("LTE signal strength in dBm: %d\n", ss);
        LE_INFO("LTE reference signal receive quality in dB : %d\n", rsrq);
        LE_INFO("LTE reference signal receive power in dBm : %d\n", rsrp);
        LE_INFO("LTE signal-to-noise ratio in 0.1 dB : %d\n", snr);
    } else {
        LE_ERROR("Fail to get LTE signal metrics.");
    }
}

The following example illustrates setting the signal strength reporting criteria.

The signal strength notifications are sent based on the configurations of delta or threshold on the RAT(s) list. Additionally, the hysteresis dB can be applied on top of the threshold list. Furthermore, time hysteresis (hysteresis ms) can be applied either on top of the delta or on the threshold list, or even on top of both the threshold list and the hysteresis dB.

For NR5G and LTE only RSRP change will be notified to clients. For other RATs only RSSI change will be notified to clients.

• Delta (delta): A notification is sent when the difference between the current signal strength value and the last reported signal strength value crosses the specified delta. The value should be a non-zero positive integer, in units of 0.1dBm. For example, to set a delta of 10dBm, the value should be 100.

The default values for delta is as follows. Measurement type : value RSSI_DELTA : 50 (in dBm) RSRP_DELTA : 60 (in dBm)

• Threshold (lowerRange/upperRange): A notification is sent when the current signal strength crosses over or under any of the thresholds specified. For example, to set thresholds at -95 dBm and -80 dBm, the threshold list values are -950, -800, since the listed values are in units of 0.1 dBm.
• Hysteresis dB (optional): Prevents the generation of multiple notifications when the signal strength is close to a threshold value and experiencing frequent small changes. With a non-zero hysteresis, the signal strength indicators should cross over or under by more than the hysteresis value for a notification to be sent. To apply hysteresis, the value should be a non-zero positive integer, in units of 0.1 dBm. For example, to set a hysteresis dB of 10 dBm, the value should be 100.
• Hysteresis ms (optional): Time hystersis can be applied to avoid multiple notifications even when all the other criteria for a notification are met. The time hystersis can be applied on top of any other criteria (delta, threshold, threshold and hysteresis).

If the hysteresis(dB or ms) value is set to 0, the signal strength notification criteria just considers the threshold or delta. Once configured, the hysteresis value for a signal strength type is retained, until explicitly reconfigured to 0 again or device reboot. This configuration is a global setting. The signal strength setting does not persist through device reboot and needs to be configured again. Default signal strength configuration is set after a device reboot.

// Set the optional hysteresis time parameter. Applicable to delta and threshold.
// Is a global variable and once set will be applicable to all RATs.
taf_radio_SetSignalStrengthIndHysteresisTimer(hysteresis ms,phoneId);
// Set the optional hysteresis dBm parameter. Applicable to threshold.
// Is applicable to a sigType.
taf_radio_SetSignalStrengthIndHysteresis(sigType,hysteresis dB,phoneId);

// Call below API to set the signal strength for threshold criteria.
taf_radio_SetSignalStrengthIndThresholds(sigType,lowerRange,upperRange,phoneId);
// Call below API to set the signal strength for delta criteria.
taf_radio_SetSignalStrengthIndDelta(sigType,delta,phoneId);

Serving Cellular Network Information

Users can get serving cellular network information.

• taf_radio_GetServingCellId() – Gets the cell ID.

  Warning

  Only applicable for GSM/LTE/WCDMA/TDSCDMA.

• taf_radio_GetServingCellLocAreaCode() – Gets the location area code.

  Warning

  Only applicable for GSM/WCDMA/TDSCDMA.

• taf_radio_GetServingCellLteTracAreaCode() – Gets the tracking area code.

  Warning

  Only applicable for LTE.

• taf_radio_GetServingCellEarfcn() – Gets the E-UTRA absolute radio frequency channel number.

  Warning

  Only applicable for LTE.

• taf_radio_GetServingCellTimingAdvance() – Gets the timing advance.

  Warning

  Only applicable for GSM/LTE.

• taf_radio_GetPhysicalServingLteCellId() – Gets the physical cell ID.

  Warning

  Only applicable for LTE.

• taf_radio_GetServingCellGsmBsic() – Gets the base station ID.

  Warning

  Only applicable for GSM.

• taf_radio_GetServingCellScramblingCode() – Gets the primary scrambling code.

  Warning

  Only applicable for WCDMA.

Network Information

Users can use the following APIs to get the current network and discover nearby networks by scanning.

• taf_radio_GetCurrentNetworkName() – Gets the current network name.
• taf_radio_GetCurrentNetworkMccMnc() – Gets the current network MCC and MNC.
• taf_radio_PerformCellularNetworkScan() / taf_radio_DeleteCellularNetworkScan() – Creates/deletes a list reference for network scanning.
• taf_radio_PerformCellularNetworkScanAsync() – Asynchronously performs a network scan with a handler.
• taf_radio_GetFirstCellularNetworkScan() / taf_radio_GetNextCellularNetworkScan() – Gets the first/next operator reference in the network scan list.
• taf_radio_GetCellularNetworkMccMnc() – Gets MCC and MNC of a network scan operator.
• taf_radio_GetCellularNetworkName() – Gets the name of a network scan operator.
• taf_radio_IsCellularNetworkInUse() – Checks if using the network scan operator's network.
• taf_radio_IsCellularNetworkAvailable() – Checks if the network is available.
• taf_radio_IsCellularNetworkHome() – Checks if it is the home network.
• taf_radio_IsCellularNetworkForbidden() – Checks if the network is forbidden.

When users fail to register to the current network, they may scan and find the nearby networks, and register to an available network with MCC and MNC manually. The following example illustrates network scanning.

// Create list and perform network scan.
listRef = taf_radio_PerformCellularNetworkScan(phoneId);

// Traverse list
opRef = taf_radio_GetFirstCellularNetworkScan(listRef);
while (opRef != nullptr) {
    if (taf_radio_GetCellularNetworkName(opRef, name, TAF_RADIO_NETWORK_NAME_MAX_LEN) != LE_OK) {
        LE_ERROR("Fail to get network name.");
        break;
    }

    if (taf_radio_GetCellularNetworkMccMnc(opRef, mcc, TAF_RADIO_MCC_BYTES,
        mnc, TAF_RADIO_MNC_BYTES) != LE_OK) {
        LE_ERROR("Fail to get network MCC and MNC.");
        break;
    }

    inUse = taf_radio_IsCellularNetworkInUse(opRef);
    available = taf_radio_IsCellularNetworkAvailable(opRef);
    fobbiden = taf_radio_IsCellularNetworkForbidden(opRef);
    home = taf_radio_IsCellularNetworkHome(opRef);

    // Do something with the network scan information.

    opRef = taf_radio_GetNextCellularNetworkScan(listRef);
}

// Delete list.
taf_radio_DeleteCellularNetworkScan(listRef);

RAT Capability Information

Users can get the number of SIMs and RAT capabilities in given slot.

• taf_radio_GetHardwareSimConfig() – Gets the maximum number of SIMs that can be supported simultaneously and the maximum number of SIMs that can be simultaneously active.If the maximum active SIM number is less than the maximum number, any combination of the SIMs can be active and the remaining can be in standby.
• taf_radio_GetHardwareSimRatCapabilities() – simRatCapMask - Gets the supported SIM RAT capabilities which intersects with the device supported RAT capabilities and the device supported RAT capabilities in given slot. deviceRatCapMask - Gets the supported device RAT capabilities supported in given slot.

The following example illustrates the API usage.

// Gets sim count
uint8_t totalSimCount = 0;
uint8_t maxActiveSims = 0;
le_result_t result = taf_radio_GetHardwareSimConfig(&totalSimCount,&maxActiveSims);

// Gets RAT Capabilities
taf_radio_RatBitMask_t deviceRatCapMask;
taf_radio_RatBitMask_t simRatCapMask;
result = taf_radio_GetHardwareSimRatCapabilities(&deviceRatCapMask,&simRatCapMask,phoneId);

---