Telematics SDK - API Reference
v1.63.4
|
The Telematics library runs in the user space of the Linux system. It interacts with Telephony services and other sub-systems to provide various services like phone calls, SMS etc. These services are exposed by the SDK through fixed public APIs that are available on all Telematics platforms that support SDK. The Telematics APIs are grouped into the following functional modules:
Telephony
Telephony sub-system consists of APIs for functions related to Phone, Call, SMS and Signal Strength, Network Selection and Serving System Management.
SIM Card Services
SIM Card services sub-system consists of APIs to perform SIM card operations such as Send APDU messages to SIM card applications, SIM Access Profile(SAP) operations etc.
Location Services
Location Services sub-system consists of APIs to receive location details such as GNSS Positions, Satellite Vehicle information, Jammer Data signals, nmea and measurements information. The location manager sub-system also consists of APIs to get location system info, request energy consumed, get year of hardware information, get terrestrial position information and cancel terrestrial position information. LocationConfigurator allows general engine configurations (example: TUNC, PACE etc),configuration of specific engines like SPE (example: minSVElevation, minGPSWeek etc) or DRE, deletion of warm and cold aiding data, NMEA configuration and support for XTRA feature.
Connection Management
Connection Management sub-system consists of APIs for establishing Cellular WAN/ Backhaul connection sessions and for Connection Profile Management etc.
Audio Management
Audio Management sub-system consists of APIs for Audio management such as setting up audio streams, switching devices on streams, apply volume/mute etc
Thermal Management
Thermal Management sub-system consists of APIs to get list of thermal zones, cooling devices and binding information. The sub-system also provides notifications about certain thermal related events such as when trip event occur for any thermal zone or cooling device changes its level.
Thermal Shutdown Mangement
Thermal shutdown management sub-system consists of APIs to get/set the thermal auto-shutdown mode and listen to its updates.
TCU Activity Management
TCU Activity Management sub-system consists of APIs to get TCU-activity state updates, set the TCU-activity state, etc.
Remote SIM Services
Remote SIM sub-system consists of APIs that allow a device that does not have a SIM physically connected to it to access a SIM remotely (e.g. over BT, Ethernet, etc.) and perform card operations on that SIM, such as requesting reset, transmitting APDU messages, etc.
Modem Config Services
Modem Config sub-system consists of APIs that allow to request modem config files, load/delete a modem config file from modem's storage, activate/deactivate a modem config file, get/set auto selection mode for config files.
Data Network Management
Data Network Management sub-system consists of APIs to setup VLAN, static NAT, Firewall, Socks, etc.
Sensor services
The sensor sub-system provides API to configure and acquire data from underlying hardware sensors like accelerometers, gyroscopes among others.
Platform services
The platform sub-system provides APIs to configure and control platform functionalities, like starting an EFS backup, control filesystem for ECALL and OTA operations. This sub-system also provides notifications about certain system related events, for instance filesystem events such as EFS restore and backup events.
Remote SIM Provisioning
Remote SIM provisioning provides API to add profile, delete profile, activate/deactivate profile on the embedded SIMs (eUICC) , get list of profiles, get server address like SMDP+ and SMDS and update SMDP+ address, update nick name of profile and retrieve Embedded Identity Document(EID) of the SIM.
Debug Logger
Logger consists of API that can be utilized to log messages from SDK Applications.
WLAN Management
The WLAN management subsystem consists of APIs to configure, enable, and set access point and station configurations.
Diagnostics Services
The Diagnostics services subsystem consists of APIs to configure, start and stop diagnostic logging.
Telematics SDK classes can be broadly divided into the following types:
Telematics SDK provides APIs for the following features:
CallManager, Phone and PhoneManager APIs of Telematics SDK provides call related control operations such as
CallManager and PhoneManager also provides additional functionality such as
SMS Manager APIs of Telematics SDK provides SMS related functionality such as
The SIM Card operations are performed by CardManager and SapCardManager.
CardManager APIs of Telematics SDK perform operations on UICC card such as
SapCardManager APIs provides SIM Access Profile(SAP) related functionality such as
Phone APIs of Telematics SDK provides phone related information such as
Location Services APIs of Telematics SDK provide the mechanism to register listener and to receive location updates, satellite vehicle information, jammer signals, nmea and measurement updates. The location manager sub-system also consists of APIs to get location system info, request energy consumed, get year of hardware information, get terrestrial position information and cancel terrestrial position information. Following parameters are configurable through the APIs.
LocationConfigurator allows general engine configurations (example: TUNC, PACE etc),configuration of specific engines like SPE (example: minSVElevation, minGPSWeek etc) or DRE, deletion of warm and cold aiding data, NMEA configuration and support for XTRA feature.
Data Services APIs in the Telematics SDK used for cellular connectivity, modem profile management, filters management, and networking.
Data Connection Manager APIs provide functionality such as
Data Profile Manager APIs provide functionality such as
Data Serving System Manager APIs provide functionality such as
Data Filter Manager APIs provide functionality such as
Data VLAN Manager APIs provide functionality such as
Data Static LAN Manager APIs provide functionality such as
Data Firewall Manager APIs provide functionality such as
Data Socks Manager APIs provide functionality such as
Data L2TP Manager APIs provides functionality such as
Data Software Bridge Manager provides interface to enable packet acceleration for non-standard WLAN and Ethernet physical interfaces. It facilitates to configure a software bridge between the interface and Hardware accelerator. Its APIs provide functionality such as
Data Serving System Manager provides the interface to access network and modem low level services. The API includes method for:
Network Selection and Service System Management APIs in the Telematics SDK used for configuring the networks and preferences
Network Selection Manager APIs provide functionality such as
Serving System Manager APIs provide functionality such as
The C-V2X sub-system contains APIs that support Cellular-V2X operation.
Cellular-V2X APIs in the Telematics SDK include Cv2xRadioManager and Cv2xRadio interfaces.
Cv2xRadioManager provides an interface to a C-V2X capable modem. The API includes methods for
Cv2xRadio abstracts a C-V2X radio channel. The API includes methods for
The Audio subSystem contains of APIs that support Audio operation.
Audio APIs in the Telematics SDK include AudioManager, AudioStream, AudioVoiceStream, AudioPlayStream, AudioCaptureStream, AudioLoopbackStream, AudioToneGenerator, Transcoder interfaces.
AudioManager provides an interface for creation/deletion of audio stream. The API includes methods for
AudioStream abstracts the properties common to different stream types. The API includes methods for
AudioVoiceStream along with inheriting AudioStream, provides additional APIs to manage voice call session as stated below.
AudioPlayStream along with inheriting AudioStream, provides additional APIs to manage audio play session as stated below.
AudioCaptureStream along with inheriting AudioStream, provides additional APIs to manage audio capture session as stated below.
AudioLoopbackStream along with inheriting AudioStream, provides additional APIs to manage audio loopback session as stated below.
AudioToneGeneratorStream along with inheriting AudioStream, provides additional APIs to manage audio tone generator session as stated below.
Transcoder provides APIs to manage audio transcoder which is able to perform below operations.
Audio SDK provides details of supported "Device Types" and "Stream Types" in the audio subsystem of Reference Telematics platform.
“Device Type” encapsulates the type of device supported in Reference Telematics platform. The representation of these devices would be made available via public header file <usr/include/telux/audio/AudioDefines.hpp>.
Example: DEVICE_TYPE_XXXX
Internally SDK DeviceTypes are mapped to Audio HAL devices as per <usr/include/system/audio.h>.
In current release it is mapped per below table.
Current Device Mapping Table:
SDK Audio Device Representation | Audio HAL Representation |
---|---|
DEVICE_TYPE_SPEAKER | AUDIO_DEVICE_OUT_SPEAKER |
DEVICE_TYPE_MIC | AUDIO_DEVICE_IN_BACK_MIC |
However Device Mapping is configurable as stated below. This configurability provides flexibility to map different Audio HAL devices to SDK representation.
Update tel.conf file with below details before boot of system.
NUM_DEVICES specifies the number of device types supported
DEVICE_TYPE specifies the SDK type of each device (in comma separated values)
DEVICE_DIR specifies the device direction for each device in order above (in comma separated values)
AHAL_DEVICE_TYPE specifies the mapped Audio HAL type of each device (in comma separated values)
Example:
Note: The default values provided here are based on QTI's reference design.
NUM_DEVICES=6
DEVICE_TYPE=1,2,3,257,258,259
DEVICE_DIR=1,1,1,2,2,2
AHAL_DEVICE_TYPE=2,1,4,2147483776,2147483652,2147483664
For any stream types, maximum device supported would be one. Single stream per multiple devices not supported. For voice stream Rx Device would decide corresponding Tx Device pair as decided by Audio HAL.
NOTE FOR SYSTEM INTEGRATORS:
The mapping of Audio devices to Audio HAL devices is static currently based on QTI's Reference Telematics platform. For custom platforms this mapping need to be updated.
“Stream Type” encapsulates the type of stream supported in Reference Telematics Platform. The representation of these stream types made available via public header file <usr/include/telux/audio/AudioDefines.hpp>.
Example: VOICE_CALL, PLAY, CAPTURE, LOOPBACK, TONE_GENERATOR etc
Volume Support Table:
This table captures scenarios where the volume could be modified.
Stream Type | Stream Direction (RX) | Stream Direction (Tx) |
---|---|---|
VOICE_CALL | Applicable | Not Applicable |
PLAY | Applicable | Not Applicable |
CAPTURE | Not Applicable | Applicable |
LOOPBACK | Not Applicable | Not Applicable |
TONE_GENERATOR | Not Applicable | Not Applicable |
In case QTI's reference design does not support volume for specific stream category, API responds with error.
Mute Support Table:
This table captures when stream could be muted and in which direction.
Stream Type | Stream Direction (RX) | Stream Direction (Tx) |
---|---|---|
VOICE_CALL | Applicable | Applicable |
PLAY | Applicable | Not Applicable |
CAPTURE | Not Applicable | Applicable |
LOOPBACK | Not Applicable | Not Applicable |
TONE_GENERATOR | Not Applicable | Not Applicable |
In case QTI's reference design does not support mute for specific stream category, API responds with error. Note: If mute operations is performed for play or capture stream direction(Tx or RX), the stream will get muted irrespective of the direction provided.
Thermal Management APIs in the Telematics SDK are used for reading thermal zone, cooling device and binding information.
Thermal Management APIs provide functionality such as
Thermal Shutdown Management APIs provide funtionality such as
TCU-activity Manager APIs in Telematics SDK provides TCU-activity state related operations such as
Remote SIM APIs in the Telematics SDK allow a device to use the WWAN capabilities of a SIM on another device.
Remote SIM APIs provide functionality such as
Modem Config APIs in the Telematics SDK provides modem config related functionalities such as
The sensor sub-system provides APIs to
In addition to the sensor sub-system APIs, configuration items relevant to the underlying sensors are also available in /etc/sensors.conf on the device filesystem. This includes the range for the sensors, the limits on sampling frequency and batch count among other parameters.
The platform sub-system provides APIs to
The Telematics Application can leverage Remote SIM Provisioning (RSP) APIs to perform eUICC profile management operations.
Remote SIM Provisioning APIs in Telematics SDK provides operations such as
When modem LPA/eUICC needs to reach SMDP+/SMDS server on the cloud for HTTP transaction, the HTTP request is sent to RSP service i.e RSP HTTP daemon. The RSP HTTP Daemon performs these HTTP transactions on behalf of modem with SMDP+/SMDS server running on the cloud. The HTTP response from cloud is sent back to modem LPA/eUICC to take appropriate action.
Logging APIs in the Telematics SDK provides logging related functionalities such as
WLAN management APIs in the Telematics SDK provide services related to the following Wi-Fi functionality.
Two methods are supported to collect logs; file and callback method. In file method, logs are captured and saved to file. In callback method, log is passed to client provided callback whenever new log is generated. Logging is also provided per device or peripheral level. With device level logging, logs from all peripherals in that device is collected. With peripheral logging, logs from client selected perihpherals only are captured. Diagnostic services APIs in the Telematics SDK provide the following functionality.
Subsystem restart events occur when device operating system or services crashes due to any reason and then reboots to operational state. This section explains notifications that are sent to application when such an event occurs, the impact on application, notifications that are sent to application when device recovers to operating state, and suggested action application should take after recovery.
Examples of Subsystem Restart events:
If application is running on either application processors when it crashes, application is expected to be restarted to initial state. For other scenarios, details are explained below for each subsystem.
Data services behavior when Subsystem Restart event occur is shown in table below:
SELinux is an access control framework provided by the Linux kernel. It provides a mechanism to restrict/control access to system resources such as file nodes and sockets. SELinux framework expects any process running in userspace to declare all its interactions with the system resources in the form of SELinux policies. On platforms enabled with SELinux, an app that uses an SDK API would also need to declare its usage through SELinux policies to ensure that it has all the required permissions.
Listed below are the SELinux Interfaces which are generic for any API in particular namespace that app needs to declare in its policies.
Note For the below list, let us consider the application's security context to be app_t
(also called domain context).
Namespace | SELinux interface | Arguments | Usage |
---|---|---|---|
tel | telux_allow_tel() | domain context | telux_allow_tel(app_t) |
data | telux_allow_data() | domain context | telux_allow_data(app_t) |
audio | telux_allow_audio() | domain context | telux_allow_audio(app_t) |
loc | telux_allow_loc() | domain context | telux_allow_loc(app_t) |
thermal | telux_allow_thermalmanager() | domain context | telux_allow_thermalmanager(app_t) |
power | telux_allow_power() | domain context | telux_allow_power(app_t) |
config | telux_allow_modemconfig() | domain context | telux_allow_modemconfig(app_t) |
cv2x | telux_allow_v2x() | domain context | telux_allow_v2x(app_t) |
sensor | telux_allow_sensor() | domain context | telux_allow_sensor(app_t) |
platform | telux_allow_platform() | domain context | telux_allow_platform(app_t) |
The following example illustrates how an application can incorporate the SELinux interfaces exposed by SDK in its SELinux policies. Below code snippet is part of a Type Enforcement (TE) file of the application which grants required permissions to perform SDK data operations.
In addition to the above SELinux interfaces list, below are the SELinux interfaces specific to a usecase. When an app needs to use any API, it should identify which SELinux interface to be used corresponding to the permission type from the below table and add it to the policy file.
To determine which permission type to be used for a API, please refer to the documentation for the API in the API Reference or in the API header file
Note The system integrator has the option to turn on/off this feature, where APIs related to a particular use case require certain permissions. If this feature is turned off, the use case specific permissions listed below are not required by the caller.
Tech Area | Permission Type | SELinux Interface |
---|---|---|
Audio | TELUX_AUDIO_VOICE | telux_allow_audio_voice |
TELUX_AUDIO_PLAY | telux_allow_audio_play | |
TELUX_AUDIO_FACTORY_TEST | telux_allow_audio_factory_test | |
TELUX_AUDIO_CAPTURE | telux_allow_audio_capture | |
TELUX_AUDIO_TRANSCODE | telux_allow_audio_transcode | |
Data | TELUX_DATA_SETTING | telux_allow_data_setting |
TELUX_DATA_CALL_OPS | telux_allow_data_call_ops | |
TELUX_DATA_CALL_PROPS | telux_allow_data_call_props | |
TELUX_DATA_PROFILE_OPS | telux_allow_data_profile_ops | |
TELUX_DATA_FILTER_OPS | telux_allow_data_filter_ops | |
TELUX_DATA_NETWORK_CONFIG | telux_data_network_config | |
ModemConfig | TELUX_CONFIG_MODEM_CONFIG | telux_allow_config_modem_config |
Power | TELUX_POWER_CONTROL_STATE | telux_allow_power_control_state_t |
Sensor | TELUX_SENSOR_DATA_READ | telux_allow_sensor_data_read |
TELUX_SENSOR_PRIVILEGED_OPS | telux_allow_sensor_privileged_ops | |
TELUX_SENSOR_FEATURE_CONTROL | telux_allow_sensor_feature_control | |
Telephony | TELUX_TEL_CARD_POWER | telux_allow_tel_card_power |
TELUX_TEL_CARD_OPS | telux_allow_tel_card_ops | |
TELUX_TEL_PRIVATE_INFO_READ | telux_allow_tel_private_info_read | |
TELUX_TEL_CARD_PRIVILEGED_OPS | telux_allow_tel_card_privileged_ops | |
TELUX_TEL_SAP | telux_allow_tel_sap | |
TELUX_TEL_CELL_BROADCAST_CONFIG | telux_allow_tel_cell_broadcast_config | |
TELUX_TEL_CELL_BROADCAST_LISTEN | telux_allow_tel_cell_broadcast_listen | |
TELUX_TEL_SIM_PROFILE_OPS | telux_allow_tel_sim_profile_ops | |
TELUX_TEL_SIM_PROFILE_USER_CONSENT | telux_allow_tel_sim_profile_user_consent | |
TELUX_TEL_SIM_PROFILE_CONFIG | telux_allow_tel_sim_profile_config | |
TELUX_TEL_SIM_PROFILE_READ | telux_allow_tel_sim_profile_read | |
TELUX_TEL_SIM_PROFILE_HTTP_PROXY | telux_allow_tel_sim_profile_http_proxy | |
TELUX_TEL_REMOTE_SIM | telux_allow_tel_remote_sim | |
TELUX_TEL_SMS_OPS | telux_allow_tel_sms_ops | |
TELUX_TEL_SMS_LISTEN | telux_access_tel_sms_listen_t | |
TELUX_TEL_SMS_CONFIG | telux_access_tel_sms_config | |
TELUX_TEL_IMS_SETTINGS | telux_allow_tel_ims_settings | |
TELUX_TEL_SRV_SYSTEM_CONFIG | telux_allow_tel_srv_system_config | |
TELUX_TEL_SRV_SYSTEM_READ | telux_allow_tel_srv_system_read | |
TELUX_TEL_NETWORK_SELECTION_OPS | telux_allow_tel_network_selection_ops | |
TELUX_TEL_NETWORK_SELECTION_READ | telux_allow_tel_network_selection_read | |
TELUX_TEL_MULTISIM_MGMT | telux_allow_tel_multisim_mgmt | |
TELUX_TEL_PRIVATE_INFO_READ | telux_allow_tel_private_info_read | |
TELUX_TEL_SUB_PRIVATE_INFO | telux_allow_tel_sub_private_info_read | |
TELUX_TEL_SUBSCRIPTION_READ | telux_allow_tel_subscription_read | |
TELUX_TEL_CALL_INFO_READ | telux_allow_tel_call_info_read | |
TELUX_TEL_CALL_MGMT | telux_allow_tel_call_mgmt | |
TELUX_TEL_CALL_PRIVATE_INFO | telux_allow_tel_call_private_info | |
TELUX_TEL_EMERGENCY_OPS | telux_allow_tel_emergency_ops | |
TELUX_TEL_ECALL_MGMT | telux_allow_tel_ecall_mgmt | |
TELUX_TEL_PHONE_MGMT | telux_allow_tel_phone_mgmt | |
TELUX_TEL_PRIVATE_INFO_READ | telux_access_tel_private_info_read | |
TELUX_TEL_PHONE_CONFIG | telux_allow_tel_phone_config | |
TELUX_TEL_ECALL_CONFIG | telux_allow_tel_ecall_config | |
TELUX_TEL_SUPP_SERVICES | telux_allow_tel_supp_services |
The following example illustrates how to declare permissions for an application that wants to use telux::data::IDataConnectionManager::startDataCall() to setup a cellular data connection.The documentation of this API indicates that the caller needs to have TELUX_DATA_CALL_OPS permission. From the above table, the permission maps to telux_allow_data_call_ops SELinux interface:
In order for the app to use the API the below code snippet needs to be entered in the Type Enforcement (TE) file of the application.