API Reference
eCall Overview
eCall sample app
Code samples

eCall is a technology initiative intended to bring rapid assistance to auto accidents anywhere in the European Union. When a serious vehicle accident occurs, sensors automatically trigger an eCall. When activated, the in-vehicle system (IVS) establishes a 112-voice connection.

The Mobile Network Operator handles the eCall like any other 112 call and routes the call to the most appropriate emergency response centre - Public Safety Answering Point (PSAP).

At the same time, a digital "minimum set of data" (MSD) message is sent over the voice call using in-band modem signals. The MSD includes accident information like time, location, driving direction, and vehicle description.

The eCall can also be activated manually. The mobile network operator identifies that the 112 call is an eCall from the “eCall flag” inserted by the vehicle’s communication module.

This API applies for both PAN-EUROPEAN and ERA-GLONASS standards.

Note: eCall service is only available on automotive products.

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_ecall -> modemService.le_ecall
}

Operation modes

The modem can be configured to operate in three different operation modes:

le_ecall_ForceOnlyMode(): this function configures the eCall operation mode to eCall only, only emergency number can be used to start an eCall session. The modem doesn't try to register on the Cellular network. This function forces the modem to behave as eCall only mode whatever U/SIM operation mode. The change doesn't persist over power cycles. This function can be called before making an eCall.
le_ecall_ForcePersistentOnlyMode(): Same as le_ecall_ForceOnlyMode(), but the change persists over power cycles.
le_ecall_ExitOnlyMode(): this function exits from eCall Only mode. It configures the eCall operation mode to Normal mode, the modem uses the default operation mode at power up (or after U/SIM hotswap). The modem behaves following the U/SIM eCall operation mode; for example the U/SIM can be configured only for eCall, or a combination of eCall and commercial service provision.
le_ecall_GetConfiguredOperationMode(): this function allows the user to retrieve the configured Operation mode. The configured operation mode can be:
- LE_ECALL_NORMAL_MODE : normal mode. The modem behaves following the U/SIM eCall operation mode.
- LE_ECALL_ONLY_MODE : eCall only mode according to U/SIM operation mode or forced by application through the le_ecall_ForceOnlyMode() function.
- LE_ECALL_FORCED_PERSISTENT_ONLY_MODE : persistent eCall only mode.

eCall Session

An eCall session is started by creating an eCall object with the le_ecall_Create() function. The eCall session can then be stopped with le_ecall_End().

The eCall type and the kind of activation are specified using different functions to start the eCall session:

le_ecall_StartManual(): initiate a manual eCall session (triggered by a passenger)
le_ecall_StartAutomatic(): initiate an automatic eCall session (automatically triggered by the IVS in case of accident)
le_ecall_StartTest(): initiate a test eCall session (to test the communication between the IVS and the PSAP)

Warning

An application must wait for the end of the ongoing eCall before triggering another one with the le_ecall_StartXxx() functions. An eCall is ended when:

the application successfully ended it with le_ecall_End() returning LE_OK
or the event LE_ECALL_STATE_STOPPED is received
or the event LE_ECALL_STATE_ALACK_RECEIVED_CLEAR_DOWN is received
or the event LE_ECALL_STATE_DISCONNECTED is received and no redial is launched (see Redial management section for more information about the redial process).

When the eCall object is no longer needed, call le_ecall_Delete() to free all allocated resources associated with the object.

The current state of an eCall session can be queried using le_ecall_GetState(). Alternatively, an application can register a handler be notified when the session state changes. The handler can be managed using le_ecall_AddStateChangeHandler() and le_ecall_RemoveStateChangeHandler().

An application can also call le_ecall_GetTerminationReason() to retrieve the reason of the call termination when call state is LE_ECALL_STATE_DISCONNECTED, and also le_ecall_GetPlatformSpecificTerminationCode() to get platform specific termination code (refer to your platform documentation for further details).

Concurrency

If another application tries to use the eCall service while a session is already in progress, the le_ecall_StartManual(), le_ecall_StartAutomatic(), le_ecall_StartTest() functions will return a LE_BUSY error. The eCall session in progress won't be interrupted or disturbed. The application can follow the session progress with 'state' functions like le_ecall_GetState() and le_ecall_AddStateChangeHandler(). A manual eCall can't interrupt an automatic eCall, and an automatic eCall can't interrupt a manual eCall.

Minimum Set of Data (MSD)

The dynamic values of the MSD can be set with:

le_ecall_SetMsdPosition() sets the position of the vehicle.
le_ecall_SetMsdPositionN1() sets the first delta position of the vehicle.
le_ecall_SetMsdPositionN2() sets the second delta position of the vehicle.
le_ecall_SetMsdPassengersCount() sets the number of passengers.

The MSD is automatically encoded with the values previously set.

Warning: Those functions return a LE_DUPLICATE error when the MSD has been already imported with le_ecall_ImportMsd() function.

The MSD transmission mode can be set or get with:

The transmission mode can be:

LE_ECALL_TX_MODE_PUSH : the MSD is pushed by the IVS
LE_ECALL_TX_MODE_PULL : the MSD is sent when requested by the PSAP

It's possible to import a prepared MSD using the le_ecall_ImportMsd() function. The prepared MSD must answer the requirements described in the "EN 15722:2013" publication (this publication has been prepared by Technical Committee CEN/TC 278 “Intelligent Transport Systems").

Warning: The imported MSD doesn't take into account the values provided by the le_ecall_SetMsdXxx() functions. It overwrites any previous imported MSD or encoded MSD.; The imported MSD overwrites the control flags (automaticActivation and testCall) set by le_ecall_StartXxx() functions (Manual, Automatic, Test). The User App is in charge of their correct settings.

The encoded MSD can be retrieved with le_ecall_ExportMsd() function.

Note: The User app must perform the MSD transmission by calling le_ecall_SendMsd() when the LE_ECALL_STATE_PSAP_START_IND_RECEIVED event is received. The MSD can be updated before calling le_ecall_SendMsd(), using the e_ecall_ImportMsd() function or the le_ecall_SetMsdXxx() functions.

Date/time on MSD information is set automatically by fetching the time from linux system time (epoch time since 1970-01-01 00:00:00 +0000 (UTC)).

Note: If linux system time is not updated automatically, update system date/time with either Linux date command or by calling le_clk_SetAbsoluteTime() function.

The time given to le_clk_SetAbsoluteTime() function can be retrieved by:

le_data_GetTime()/le_data_GetDate(): the time from the network NTP.
le_gnss_GetEpochTime() the GPS epoch time.

ERA-GLONASS compliancy

To perform an emergency call following the ERA-GLONASS requirements, the 'systemStandard' entry of the configuration database must be set to 'ERA-GLONASS'.

Moreover, the User can set some specific configuration settings in accordance with the PSAP configuration:

le_ecall_SetEraGlonassManualDialAttempts(): set the ECALL_MANUAL_DIAL_ATTEMPTS value. If a dial attempt under manual emergency call initiation failed, it should be repeated maximally ECALL_MANUAL_DIAL_ATTEMPTS-1 times within the maximal time limit of ECALL_DIAL_DURATION. The default value is 10. Redial attempts stop once the call has been cleared down correctly, or if counter / timer reached their limits.

Available for both manual and test modes:
le_ecall_SetEraGlonassAutoDialAttempts(): set the ECALL_AUTO_DIAL_ATTEMPTS value. If a dial attempt under automatic emergency call initiation failed, it should be repeated maximally ECALL_AUTO_DIAL_ATTEMPTS-1 times within the maximal time limit of ECALL_DIAL_DURATION. The default value is 10. Redial attempts stop once the call has been cleared down correctly, or if counter / timer reached their limits.
le_ecall_SetEraGlonassDialDuration(): set the ECALL_DIAL_DURATION time. It is the maximum time the IVS have to connect the emergency call to the PSAP, including all redial attempts. If the call is not connected within this time (or ManualDialAttempts/AutoDialAttempts dial attempts), it will stop.
le_ecall_SetEraGlonassFallbackTime(): set the ECALL_CCFT time. When the specified timer duration is reached and IVS NAD didn't receive a call clear-down indication then the call is automatically terminated.
le_ecall_SetEraGlonassAutoAnswerTime(): sets the ECALL_AUTO_ANSWER_TIME time, the maximum time interval wherein IVDS responds to incoming calls automatically after emergency call completion.
le_ecall_SetEraGlonassMSDMaxTransmissionTime(): sets the ECALL_MSD_MAX_TRANSMISSION_TIME time, the maximum time for MSD transmission.

Available for test mode only:
le_ecall_SetEraGlonassPostTestRegistrationTime(): sets the ECALL_POST_TEST_REGISTRATION_TIME, the time interval wherein IVS remains registered in the network after the completion of transmission of test results to System Operator. The ECALL_POST_TEST_REGISTRATION_TIME default time value is 120 seconds.

The corresponding getter functions let you retrieve the configuration settings values:

le_ecall_GetEraGlonassManualDialAttempts(): get the ECALL_MANUAL_DIAL_ATTEMPTS value.
le_ecall_GetEraGlonassAutoDialAttempts(): get the ECALL_AUTO_DIAL_ATTEMPTS value.
le_ecall_GetEraGlonassDialDuration(): get the ECALL_DIAL_DURATION time.
le_ecall_GetEraGlonassFallbackTime(): get the ECALL_CCFT time.
le_ecall_GetEraGlonassAutoAnswerTime(): get the ECALL_AUTO_ANSWER_TIME time.
le_ecall_GetEraGlonassMSDMaxTransmissionTime(): get the ECALL_MSD_MAX_TRANSMISSION_TIME time.
le_ecall_GetEraGlonassPostTestRegistrationTime(): get the ECALL_POST_TEST_REGISTRATION_TIME time.

ERA-GLONASS MSD additional data

ERA-GLONASS additional data are optional and provided in the MSD message if any. They are located in MSD data block number 12 as optional additional data.

ERA-GLONASS MSD additional data for MSD version 1 describes:

The crash severity (Accident Severity Index - ASI15)
The diagnostic result
The crash information

ERA-GLONASS MSD additional data for MSD version 2 describes:

The crash severity (Accident Severity Index - ASI15)
The diagnostic result
The crash information
The coordinate system type

ERA-GLONASS MSD additional data can be specified through the following functions:

ERA-GLONASS additional data is encoded using the OID version "1.4.1" for MSD version 1 and the OID version "1.4.2" for MSD version 2. This was assigned to ERA-GLONASS optional additional data by CEN.

Content of data block in the AdditionalData for MSD version 1 should be:

ERAOADASN1Module
DEFINITIONS
AUTOMATIC TAGS ::=
BEGIN
ERADataFormatId::= INTEGER (1)
 
ERAAdditionalData ::= SEQUENCE {
   crashSeverity INTEGER(0..2047) OPTIONAL,
   diagnosticResult DiagnosticResult OPTIONAL,
   crashInfo CrashInfo OPTIONAL,
   ...
}
 
DiagnosticResult ::= SEQUENCE {
   micConnectionFailure BOOLEAN OPTIONAL,
   micFailure BOOLEAN OPTIONAL,
   rightSpeakerFailure BOOLEAN OPTIONAL,
   leftSpeakerFailure BOOLEAN OPTIONAL,
   speakersFailure BOOLEAN OPTIONAL,
   ignitionLineFailure BOOLEAN OPTIONAL,
   uimFailure BOOLEAN OPTIONAL,
   statusIndicatorFailure BOOLEAN OPTIONAL,
   batteryFailure BOOLEAN OPTIONAL,
   batteryVoltageLow BOOLEAN OPTIONAL,
   crashSensorFailure BOOLEAN OPTIONAL,
   firmwareImageCorruption BOOLEAN OPTIONAL,
   commModuleInterfaceFailure BOOLEAN OPTIONAL,
   gnssReceiverFailure BOOLEAN OPTIONAL,
   raimProblem BOOLEAN OPTIONAL,
   gnssAntennaFailure BOOLEAN OPTIONAL,
   commModuleFailure BOOLEAN OPTIONAL,
   eventsMemoryOverflow BOOLEAN OPTIONAL,
   crashProfileMemoryOverflow BOOLEAN OPTIONAL,
   otherCriticalFailires BOOLEAN OPTIONAL,
   otherNotCriticalFailures BOOLEAN OPTIONAL
}
 
CrashInfo ::= SEQUENCE {
   crashFront BOOLEAN OPTIONAL,
   crashLeft BOOLEAN OPTIONAL,
   crashRight BOOLEAN OPTIONAL,
   crashRear BOOLEAN OPTIONAL,
   crashRollover BOOLEAN OPTIONAL,
   crashSide BOOLEAN OPTIONAL,
   crashFrontOrSide BOOLEAN OPTIONAL,
   crashAnotherType BOOLEAN OPTIONAL
}
END

Content of data block in the AdditionalData for MSD version 2 should be:

ERAOADASN1Module
DEFINITIONS
AUTOMATIC TAGS ::=
BEGIN
ERADataFormatId::= INTEGER (1)
 
ERAAdditionalData ::= SEQUENCE {
   crashSeverity INTEGER(0..2047) OPTIONAL,
   diagnosticResult DiagnosticResult OPTIONAL,
   crashInfo CrashInfo OPTIONAL,
   coordinateSystemType CoordinateSystemType DEFAULT wgs84,
   ...
}
 
DiagnosticResult ::= SEQUENCE {
   micConnectionFailure BOOLEAN OPTIONAL,
   micFailure BOOLEAN OPTIONAL,
   rightSpeakerFailure BOOLEAN OPTIONAL,
   leftSpeakerFailure BOOLEAN OPTIONAL,
   speakersFailure BOOLEAN OPTIONAL,
   ignitionLineFailure BOOLEAN OPTIONAL,
   uimFailure BOOLEAN OPTIONAL,
   statusIndicatorFailure BOOLEAN OPTIONAL,
   batteryFailure BOOLEAN OPTIONAL,
   batteryVoltageLow BOOLEAN OPTIONAL,
   crashSensorFailure BOOLEAN OPTIONAL,
   firmwareImageCorruption BOOLEAN OPTIONAL,
   commModuleInterfaceFailure BOOLEAN OPTIONAL,
   gnssReceiverFailure BOOLEAN OPTIONAL,
   raimProblem BOOLEAN OPTIONAL,
   gnssAntennaFailure BOOLEAN OPTIONAL,
   commModuleFailure BOOLEAN OPTIONAL,
   eventsMemoryOverflow BOOLEAN OPTIONAL,
   crashProfileMemoryOverflow BOOLEAN OPTIONAL,
   otherCriticalFailires BOOLEAN OPTIONAL,
   otherNotCriticalFailures BOOLEAN OPTIONAL
}
 
CrashInfo ::= SEQUENCE {
   crashFront BOOLEAN OPTIONAL,
   crashLeft BOOLEAN OPTIONAL,
   crashRight BOOLEAN OPTIONAL,
   crashRear BOOLEAN OPTIONAL,
   crashRollover BOOLEAN OPTIONAL,
   crashSide BOOLEAN OPTIONAL,
   crashFrontOrSide BOOLEAN OPTIONAL,
   crashAnotherType BOOLEAN OPTIONAL
}
 
CoordinateSystemType ::= ENUMERATED {
   wgs64 (1),
   ps90 (2)
}
END

Redial management

In the case of PAN-EUROPEAN, the redial can be performed as many times as desired but should be performed within 2 minutes. (EN 16062:2014 -7.14.3).

In the case of ERA-GLONASS, the redial can be performed ECALL_MANUAL_DIAL_ATTEMPTS times within the maximal time limit of ECALL_DIAL_DURATION (GOST 54620 2013 -- Appendix A).

The LE_ECALL_STATE_END_OF_REDIAL_PERIOD state event notifies the User of the redial period end.

eCall configuration

Some parameters used by the eCall service can be configured through APIs. This includes the number to dial, the deregistration time, the redial interval, and some MSD information.

eCall number

By default, the number to dial is read from the FDN/SDN (Fixed Dialling Numbers/Service Dialling Numbers) of the U/SIM, depending upon the eCall operating mode.

However, the PSAP phone number can be queried and set with:

    LE_ASSERT_OK(le_ecall_SetPsapNumber("0102030405"));
 
    char psapNumber[LE_MDMDEFS_PHONE_NUM_MAX_BYTES] = {0};
    LE_ASSERT_OK(le_ecall_GetPsapNumber(psapNumber, sizeof(psapNumber)));
    LE_INFO("PSAP number: %s", psapNumber);

Note: That PSAP number is not applied to a manual or an automatically initiated eCall. For these modes, an emergency call is launched.

Warning: These two functions don't modify or read the U/SIM content.

When modem is in LE_ECALL_FORCED_PERSISTENT_ONLY_MODE or LE_ECALL_ONLY_MODE, le_ecall_UseUSimNumbers() API can be called to request the modem to read the number to dial from the FDN/SDN of the U/SIM.

Note: If FDN directory is updated with new dial numbers, be sure that the SIM card is refreshed.

NAD deregistration time

The NAD (Network Access Device, i.e. the Modem) deregistration time value can be set with the le_ecall_SetNadDeregistrationTime() API and retrieved with the le_ecall_GetNadDeregistrationTime() API.

    LE_ASSERT_OK(le_ecall_SetNadDeregistrationTime(180));
 
    uint16_t deregistrationTime = 0;
    LE_ASSERT_OK(le_ecall_GetNadDeregistrationTime(&deregistrationTime));
    LE_INFO("Deregistration time: %d minutes", deregistrationTime);

PAN-EUROPEAN standard (EN 16062) defines the T9 and T10 timers. After an eCall clear-down, an eCall only IVS shall:
- Remain registered on the network for at least the duration of T9, which is set to one hour by default.
- Deregister from the network after the expiration of T10, which duration is set to twelve hours by default.
ERA-GLONASS standard (ENG_GOST_R_54620) defines the NAD_DEREGISTRATION_TIME with a minimal value of two hours and a maximum value of twelve hours. After an eCall clear-down, the IVS shall remain registered on the network and deregister from the network after the expiration of the NAD_DEREGISTRATION_TIME.

The le_ecall_SetNadDeregistrationTime() API is used to set the duration of a deregistration timer: after an eCall clear-down, the IVS remains registered on the network for the duration of this timer and then automatically deregisters from the network upon its expiration.

PAN-EUROPEAN standard

As the T9 timer duration is fixed to one hour, the notified events depend on the deregistration timer duration:

If its duration is set to one hour, the LE_ECALL_STATE_TIMEOUT_T9 event will be reported. In this case deregistration is automatically performed when the T9 timeout indication is received.
If its duration is set to more than one hour and less than twelve hours then the LE_ECALL_STATE_TIMEOUT_T10 event will be reported when the deregistration timer expires. The T9 timeout (LE_ECALL_STATE_TIMEOUT_T9 event) will not be notified. In this case deregistration is automatically performed when the deregistration timer expires, provided that the application didn't already deregister from the network before.

ERA-GLONASS standard

The LE_ECALL_STATE_TIMEOUT_T9 event is not reported as it is not defined in the ERA-GLONASS standard.
The NAD_DEREGISTRATION_TIME default value is eight hours, as defined by GOST_R 54620 Table A.1. It can be changed with le_ecall_SetNadDeregistrationTime() and the value must be set between two and twelve hours.
The LE_ECALL_STATE_TIMEOUT_T10 event will be reported when the NAD_DEREGISTRATION_TIME expires. In this case deregistration is automatically performed when the timer expires.

Timer value

Although the time is set in minutes the value is taken in hours, for example:

from 1 to 60 minutes -> 1 hour
from 61 to 120 minutes -> 2 hours, etc.

Example: if deregTime parameter unit is minutes, the effective time is:

ECallConfiguration.nad_deregistration_time = (deregTime+59)/60;

After termination of an emergency call the in-vehicle system remains registered on the network for the period of time, defined by the installation parameter NAD_DEREGISTRATION_TIME.

Warning: Be sure to check the possible values of NAD_DEREGISTRATION_TIME for your specific platform.

Post test registration time

The ECALL_POST_TEST_REGISTRATION_TIME time value can be set with the le_ecall_SetEraGlonassPostTestRegistrationTime() function and retrieved by the le_ecall_GetEraGlonassPostTestRegistrationTime() function.

    res = le_ecall_SetEraGlonassPostTestRegistrationTime(500);
    LE_ASSERT((LE_OK == res) || ((LE_UNSUPPORTED == res)));
 
    res = le_ecall_GetEraGlonassPostTestRegistrationTime(&duration);
    LE_ASSERT((LE_OK == res) || ((LE_UNSUPPORTED == res)));
    LE_INFO("Post Test registration time: %d seconds", duration);

Redial interval

The minimum interval value between dial attempts can be set or get with:

    LE_ASSERT_OK(le_ecall_SetIntervalBetweenDialAttempts(30));
 
    uint16_t pause = 0;
    LE_ASSERT_OK(le_ecall_GetIntervalBetweenDialAttempts(&pause));
    LE_INFO("Interval between dial attempts: %d seconds", pause);

The default value is set to 30 seconds.

The time is counted from the start of the first dial attempt.

If more time has expired during the dial attempt, it will wait for 1 second to allow hangup before redialing.

If less time has expired during the dial attempt, it will wait for (interval - 'dial attempt duration') seconds to allow hangup before redialing.

In the case the call was connected, the redial will be immediate.

le_ecall_SetIntervalBetweenDialAttempts() is available for both manual and test modes.

Miscellaneous

The preferred system standard defaults to PAN-EUROPEAN It can be set an gotten with the following functions:

    LE_ASSERT_OK(le_ecall_SetSystemStandard(LE_ECALL_ERA_GLONASS));
 
    le_ecall_SystemStandard_t systemStandard;
    LE_ASSERT_OK(le_ecall_GetSystemStandard(&systemStandard));
    LE_INFO("System standard: %d", systemStandard);

The MSD version can be set and and gotten with the following functions:

    LE_ASSERT_OK(le_ecall_SetMsdVersion(1))
 
    uint32_t msdVersion = 0;
    LE_ASSERT_OK(le_ecall_GetMsdVersion(&msdVersion));
    LE_INFO("MSD version: %d", msdVersion);

The vehicle type can be set and gotten with the following functions:

    LE_ASSERT_OK(le_ecall_SetVehicleType(LE_ECALL_MSD_VEHICLE_BUS_M2));
 
    le_ecall_MsdVehicleType_t vehicleType;
    LE_ASSERT_OK(le_ecall_GetVehicleType(&vehicleType));
    LE_INFO("Vehicle type: %d", vehicleType);

The vehicle identifier can be set and gotten with the following functions:

    LE_ASSERT_OK(le_ecall_SetVIN("VF37BRFVE12345678"));
 
    char vin[LE_ECALL_VIN_MAX_BYTES] = {0};
    LE_ASSERT_OK(le_ecall_GetVIN(vin, sizeof(vin)));
    LE_INFO("VIN: %s", vin);

The propulsion type can be set and gotten with the following functions:

    LE_ASSERT_OK(le_ecall_SetPropulsionType(LE_ECALL_PROPULSION_TYPE_OTHER));
 
    le_ecall_PropulsionTypeBitMask_t propulsionType;
    LE_ASSERT_OK(le_ecall_GetPropulsionType(&propulsionType));
    LE_INFO("Propulsion type: 0x%02x", propulsionType);

Code samples

A sample code that implements an eCall test session with a local voice prompt can be found in eCallWPrompt.c file (please refer to Sample code of an eCall test session with a local voice prompt page).

A sample code that implements an eCall test session with a voice call connection can be found in eCallWVoice.c file (please refer to Sample code an eCall test session with a voice call connection page).

If you want to have a look at a more in-depth usage of these APIs, please refer to the le_ecall_interface.h.