Snapdragon® Telematics Application Framework (TelAF) Interface Specification
eCall Service

API Reference

eCall is a technology initiative intended to bring rapid assistance to automotive accidents anywhere. When a serious vehicle accident occurs, sensors automatically trigger an eCall. When activated, the in-vehicle system (IVS) establishes a voice connection to a 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. An eCall can also be triggered manually. An emergency call is needed for applications that want to establish emergency communication with a remote party. The emergency call can be over an emergency mobile network or VoIP.

IPC interfaces binding

All functions of the eCall API are provided by the tafECallSvc application service. TafECallSvc allows users to start an eCall, talk/converse through an eCall, send MSD information, and send location info to PSAPs.

The following example illustrates how to bind to eCall services.

 bindings:
 {
     clientExe.clientComponent.taf_ecall -> tafECallSvc.taf_ecall
 }

Operation modes of eCall

The modem can operate in three different eCall modes.

  • taf_ecall_ForceOnlyMode() – This API makes the eCall operating mode eCall only. Only emergency numbers should be used to start eCall sessions in this mode. The modem may not try to register with the cellular network. The modem is forced to behave as only eCalls are allowed regardless of the the U/SIM operation mode.
  • taf_ecall_ForcePersistentOnlyMode() – Same as taf_ecall_ForceOnlyMode(), but this change persists through device reboot, i.e., power cycles.
  • taf_ecall_ExitOnlyMode() – This function causes the device to exit eCall Only mode. It changes the eCall operation mode to Normal. Generally the modem applies the default operation mode at boot up (and after U/SIM hotswap). The modem acts following the U/SIM eCall operation mode. For example the U/SIM can be setup only for eCall or a combination of eCall and normal commercial service provision.
  • taf_ecall_GetConfiguredOperationMode() – This function helps the user fetch the configured operation mode of the modem or NAD. The various operation modes can be:

eCall MSD version

MSD version can be set/got with:

These configurations take effect at the next test eCall and currently only MSD version 2 and 3 are supported.

Session of eCall

taf_ecall_Create() helps to create a new eCall object and returns a reference to the eCall session. taf_ecall_GetType() is used to query the current type of the eCall session. At this point the eCall is not yet started, the eCall session must be started using one of the following functions.

The eCall session can be ended by calling taf_ecall_End(). Note that sometimes, the ongoing eCall session cannot be stopped until a specific eCall state is entered as in the following use cases.

  • When an automatic eCall session is in progress, it is not possible to stop the ongoing session until TAF_ECALL_STATE_ENDED event is reached.
  • For a manual eCall session, it is allowed to end the ongoing session if eCall is not connected/active (TAF_ECALL_STATE_ACTIVE not yet come) and after the TAF_ECALL_STATE_ENDED event is received.

taf_ecall_Answer() is used to answer an incoming eCall when the minimum network registration timer is active.

Warning
An application should wait for end of the existing eCall before dialing another with the taf_ecall_StartXxx() APIs. An eCall is stopped when any of the following occurs.

If the eCall object is no longer required, the application can call taf_ecall_Delete() to free all allocated resources of the eCall object.

The current state of the eCall session may be queried by taf_ecall_GetState(). Apart from this, an application may register a state change handler to be notified when the session state changes. The handler can be controlled using taf_ecall_AddStateChangeHandler() and taf_ecall_RemoveStateChangeHandler().

An application may call taf_ecall_GetTerminationReason() to get the end reason of the eCall when the eCall state is TAF_ECALL_STATE_ENDED and and taf_ecall_GetPlatformSpecificTerminationCode() to get the platform-related termination code.

eCall number

Depending on the operating mode, the standard eCall number is defined by the modem or read from the USIM fixed dialing numbers/service dialing numbers (FDN/SDN).

A third-party eCall number can be set/got with:

To request that the modem reads the number from FDN/SDN, call taf_ecall_UseUSimNumbers() before starting an eCall.

NAD eCall deregistration time

Network Access Device (NAD), i.e. the modem, deregistration allows the device to remain registered to the network for an amount of time after the eCall is ended, either remotely or the user hangs up locally using taf_ecall_End(). The deregistration duration can be set using the taf_ecall_SetNadDeregistrationTime() API and retrieved using the taf_ecall_GetNadDeregistrationTime() API.

The taf_ecall_SetNadDeregistrationTime() API is used to set the time value of a deregistration timer after an eCall ends, so that the NAD remains registered on the network for a duration of time and then automatically deregisters from the network upon expiration of the timer.

Moreover, when NAD (i.e. Modem) is in eCall Only mode and an eCall has been cleared-down by the PSAP or by taf_ecall_End(), then a user can terminate eCall registration anytime after T9 but before T10 expiration by calling the taf_ecall_TerminateRegistration() API.

The taf_ecall_SetNadClearDownFallbackTime() API is used to set the time value of a clear down fallback timer which starts when an eCall connects, so that if the NAD does not receive a clear down indication from network or a clear down message (AL-ACK) from the PSAP during an ecall and then automatically triggers an eCall end upon expiration of the timer.

The taf_ecall_SetNadMinNetworkRegistrationTime() API is used to set the time value of a minimum network registration timer which starts right after an eCall ends, so that the NAD shall remain registered on the serving network after an eCall ends and automatically receive calls from the PSAP, and then automatically deregisters from the network upon expiration of the timer.

NAD eCall HLAP timer state

The taf_ecall_GetHlapTimerState() API is used to get the timer status and elapsed time based on HLAP timer type.

Concurrency of eCall

If another application wants to use the eCall service when a session is already active, the taf_ecall_StartManual(), taf_ecall_StartAutomatic(), taf_ecall_StartTest(), taf_ecall_StartPrivate() functions will return LE_BUSY error and the eCall session which is in progress will not be interrupted or disturbed. The application may get the session progress 'state' using API like taf_ecall_GetState() and taf_ecall_AddStateChangeHandler(). A manual eCall cannot disturb an automatic eCall and vice-versa.

Minimum Set of Data (MSD)

The dynamic values of MSD can be written with the following APIs.

The MSD is automatically encoded with the previous MSD values set earlier.

Warning
The above functions may return a LE_DUPLICATE error when MSD has already been imported using the taf_ecall_ImportMsd() API.

The MSD transmission mode can be set and retrieved using the following APIs.

The transmission modes can be:

An application can import an existing MSD using the taf_ecall_ImportMsd() API. The existing MSD must follow the requirements presented in the "EN15722:2020" publication (this publication is prepared by Technical Committee CEN/TC 278 “Intelligent Transport Systems").

Warning
The imported MSD does not consider the values provided by the taf_ecall_SetMsdXxx() APIs. It overwrites any MSD imported or encoded previously.
The imported MSD may overwrite the control flags (automatic and test eCall) set by taf_ecall_StartXxx() APIs (Manual, Automatic, Test). The user app is responsible for the proper settings.

The encoded MSD can be fetched with the taf_ecall_ExportMsd() API.

Note
The user application should perform the MSD transmission by using taf_ecall_SendMsd() when the TAF_ECALL_STATE_PSAP_START_RECEIVED event arrives. The MSD may be modified before calling taf_ecall_SendMsd() by the e_ecall_ImportMsd() API or the taf_ecall_SetMsdXxx() APIs.

Start of emergency call

An emergency call can be started by using taf_ecall_StartAutomatic() with the ecallRef passed as a parameter. To get ECallRef we need to call taf_ecall_Create() with no parameters. This creates an ECallRef object and returns it. Applicatons can cache the ECallRef for future use. 

 static taf_ecall_CallRef_t ECallRef = taf_ecall_Create();
 if (!ECallRef)
 {
    le_result_t res = taf_ecall_StartAutomatic(ECallRef);
    LE_ASSERT(res == LE_OK);
 }

Before the emergency call is started, an application registers a state change handler using taf_ecall_AddStateChangeHandler(). Once the emergency call is established, the handler will be called indicating it's now connected. If the state of the emergency call changes, then the handler will be called with the new state. 

 taf_ecall_StateChangeHandlerRef = taf_ecall_AddStateChangeHandler((taf_ecall_StateChangeHandlerFunc_t) tafECallStateHandler, NULL);

To end an emergency call, an application can use taf_ecall_End().

Applications must use taf_ecall_Delete() to release taf_ecall_CallRef_t emergency call reference object when it is no longer used.

Typical application call flow

eCall_usage_flow.jpg

eCall apps can use the TelAF eCall service to start an eCall with a PSAP, enable conversation over a voice channel, and end the eCall.

#1 – Create an eCall session and get the eCall reference which will be used to make an eCall with PSAP.

#2 – Register the state change handler to get notifications from the TelAF eCall service when the eCall state gets changed.

#3 – Construct MSD message, including position information from the GNSS service, vehicle information, passenger count, etc.

#4 – Start an eCall via the eCall Service. The eCall service will initiate a corresponding eCall to PSAP. After this, the state change handler will be notified that the eCall state is DIALING and then ALERTING which means that the eCall successfully reached the PSAP.

After the eCall is answered by the PSAP, the eCall state changes to ACTIVE and in MSD Pull mode, the eCall Service gets a state indication TAF_STATE_MSD_UPDATE_REQ from the PSAP to receive MSD. Without this state indication, as of now, the client application should update MSD to the NAD (i.e., modem) by calling the taf_ecall_SendMsd() API. Later, when the NAD gets an indication from the PSAP in pull mode, NAD will use the updated MSD and send it to the PSAP.

#5 – Start sending encoded MSD via the eCall Service to the PSAP. The eCall state becomes TAF_STATE_MSD_TRANSMISSION_STARTED and the TAF_STATE_LL_ACK_RECEIVED.

After PSAP successfully receives the MSD, the eCall state changes to TAF_STATE_MSD_TRANSMISSION_SUCCESS and the state change hander will be notified.

Call active: The eCall app might need to stay active to reserve a voice call channel to enable the passenger to talk with the PSAP.

#6 – When the conversation is finished, the eCall app can end the call using the eCall Service API. This will send the BYE signal to the PSAP. After the eCall is successfully ended, the eCall state will change to ENDED and the state change handler will be notified of the same.