Telematics SDK - Interface Specification
v1.46.14
|
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. Also the location configurator sub-system consists of API to enable/disable constraint time uncertainty, enable/disable PACE, delete all aiding data, configure lever arm parameters, configure the blacklisted satellite vehicle, configure robust location, configure min gps week, request min gps week, configure min sv elevation, request min sv elevation, request robust location, delete specified data, configure dR engine, configure secondary band, request secondary band, configure engine state, provide consent for terrestrial positioning and configure NMEA types.
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.
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.
Debug Logger
Logger consists of API that can be utilized to log messages from SDK Applications.
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.
Location Configurator APIs of Telematics SDK provide mechanism to enable/disable constraint time uncertainty feature, enable/disable PACE, delete all aiding data, configure lever arm parameters, configure blacklisted satellite vehicles, configure robust location, configure min gps week, request min gps week, configure min sv elevation, request min sv elevation, request robust location, delete specified data, configure dR engine, configure secondary band, request secondary band, configure engine state, provide consent for terrestrial positioning and configure NMEA types.
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
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 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 Device Type 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 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 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.
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
Logging APIs in the Telematics SDK provides logging related functionalities such as
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. In order for an application to use the SDK's APIs on such a platform, SELinux interfaces have been defined that the app needs to declare in its policies.
Listed below are the interfaces to be used when an app uses APIs belonging to a given namespace/class of the SDK.
Note For the below list, let us consider the application's security context to be app_t
(also called domain context).
SDK Namespace/Class | 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) |
IThermalManager | telux_allow_thermalmanager() | domain context | telux_allow_thermalmanager(app_t) |
IThermalShutdownManager | telux_allow_thermalshutdown() | domain context | telux_allow_thermalshutdown(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 all SDK data operations.