Overview

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 etc. Also constraint Time Uncertainty sub-system consists of API to enable/disable constraint time uncertainty 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.

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.

Telematics SDK classes can be broadly divided into the following types:

• Factory - Factory classes are central classes such as PhoneFactory which can be used to create Manager classes corresponding to their sub-systems such as PhoneManager.
• Manager - Manager classes such as PhoneManager to manage multiple Phone instances, CardManager to manage multiple SIM Card instances etc.
• Observer/ Listener - Listener for unsolicited responses.
• Command Callback - Single-shot response callback for asynchronous API requests.
• Logger - APIs to log messages, control the log levels.

Features

Telematics SDK provides APIs for the following features:

Call Management

CallManager, Phone and PhoneManager APIs of Telematics SDK provides call related control operations such as

• Initiate a voice call
• Answer the incoming call
• Hold the call
• Hangup waiting, held or active call

CallManager and PhoneManager also provides additional functionality such as

• Allowing conference, and switch between waiting or holding call and active call
• Emergency Call (dial 112)
• Notifications about call state change

SMS

SMS Manager APIs of Telematics SDK provides SMS related functionality such as

• Sends and receives SMS messages of type GSM7, GSM8 and UCS2

SIM Card Services

The SIM Card operations are performed by CardManager and SapCardManager.

CardManager APIs of Telematics SDK perform operations on UICC card such as

• Open or close logical/basic channel to ICC card
• Transmit Application Protocol Data Unit (APDU) to the ICC Card over logical/basic channel
• Receive response APDU from the ICC Card with the status
• Notify about ICC card information change

SapCardManager APIs provides SIM Access Profile(SAP) related functionality such as

• Open or close SIM Access Profile(SAP) connection
• Transmit Application Protocol Data Unit (APDU) over SAP connection
• Receive response APDU over SAP connection
• Perform SAP operations such as Answer to Reset(ATR), SIM Power off, SIM Power On, SIM Reset and fetch Card Reader status.

Phone Information

Phone APIs of Telematics SDK provides phone related information such as

• Get Service state of phone i.e. EMERGENCY_ONLY, IN_SERVICE and OUT_OF_SERVICE
• Get Radio state of device i.e RADIO_STATE_OFF, RADIO_STATE_ON and RADIO_STATE_UNAVAILABLE
• Retrieve the signal strength corresponding to the technology supported by SIM
• Device Identity
• Set or Request Operating Mode
• Subscription Information

Location Services

Location Services APIs of Telematics SDK provide the mechanism to register listener and to receive location updates, satellite vehicle information and jammer signals. Following parameters are configurable through the APIs.

• Minimum time interval between two consecutive location reports.
• Minimum distance travelled after which the period between two consecutive location reports depends on the interval specified. Location constraint time uncertainty API of Telematics SDK provide the mechanism to enable/disable constraint time uncertainty feature.

Data Services

Data Services APIs in the Telematics SDK used for cellular connectivity, modem profile management and data filters management.

Data Connection Manager APIs provide functionality such as

• start / stop data call
• listen for data call state changes

Data Profile Manager APIs provide functionality such as

• List available profiles in the modem
• Create / modify / delete / modify modem profiles
• Query for the selected profile

Data Filter Manager APIs provide functionality such as

• get / set data filter mode per data call
• get / set data filter mode for all data call in up state
• add / remove data filter per data call
• add / remove data filter for all data call in up state

Network Selection and Serving System Management

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

• request or set network selection mode (Manual or Automatic)
• scan for available networks
• request or set preferred networks list

Serving System Manager APIs provide functionality such as

• request and set service domain preference and radio access technology mode preference for searching and registering (CS/PS domain, RAT and operation mode)

C-V2X

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

• Enabling C-V2X mode
• Disabling C-V2X mode
• Querying the status of C-V2X
• Updating the C-V2X configuration via a config XML file

Cv2xRadio abstracts a C-V2X radio channel. The API includes methods for

• Obtaining the current capabilities of the radio
• Listen for radio state changes
• Creating and Closing an RX subscription
• Creating and Closing a TX event-driven flow
• Creating and Closing a TX semi-persistent-scheduling (SPS) flow
• Updating TX SPS flow parameters
• Update Source L2 Info

Audio

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

• Query readiness of subSystem
• Query supported "Device Types"
• Query supported "Stream Types"
• Creating Audio Stream
• Deleting Audio Stream

AudioStream abstracts the properties common to different stream types. The API includes methods for

• Query stream type
• Query routed device
• Set device
• Query volume details
• Set volume
• Query mute details
• Set mute

AudioVoiceStream along with inheriting AudioStream, provides additional APIs to manage voice call session as stated below.

• Start Voice Audio Operation
• Stop Voice Audio Operation
• Play DTMF tone
• Detect DTMF tone

AudioPlayStream along with inheriting AudioStream, provides additional APIs to manage audio play session as stated below.

• write audio samples
• Write audio samples for compressed audio format
• Stop Audio for compressed audio format
• Play compressed format audio on voice paths

AudioCaptureStream along with inheriting AudioStream, provides additional APIs to manage audio capture session as stated below.

• read audio samples

AudioLoopbackStream along with inheriting AudioStream, provides additional APIs to manage audio loopback session as stated below.

• Start loopback
• Stop loopback

AudioToneGeneratorStream along with inheriting AudioStream, provides additional APIs to manage audio tone generator session as stated below.

• Play tone
• Stop tone

Transcoder provides APIs to manage audio transcoder which is able to perform below operations.

• Convert one audio format to another

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

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

• get thermal zones with thermal zone description, current temperature, trip points and binding info
• get cooling devices with cooling device type, maximum and current cooling level
• get thermal zone by Id
• get cooling device by Id

Thermal Shutdown Management

Thermal Shutdown Management APIs provide funtionality such as

• Query auto-shutdown mode.
• Set auto-shutdown mode.
• Get notifications on auto-shutdown mode updates.

TCU Activity Management

TCU-activity Manager APIs in Telematics SDK provides TCU-activity state related operations such as

• Query the current TCU-activity state
• Get notifications about the TCU-activity state changes
• Set the system to a desired activity state

Remote SIM

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

• Sending card events (reset, power up, errors) to the modem
• Sending/receiving APDU messages from/to the modem and remote SIM.
• Receiving operations from the modem (disconnect, power up, reset) to the remote SIM.

Modem Config Management

Modem Config APIs in the Telematics SDK provides modem config related functionalities such as

• Request modem config files from modem's storage.
• Load a modem config file to modem's storage.
• Activate/Deactivate a modem config file from modem's storage.
• Get Active config info details.
• Get/Set config auto selection mode.
• Delete a modem config file from modem's storage.
• Ability to get notified whenever a SW config file is activated.