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 etc.

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

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 and satellite vehicle information. Following parameters are configurable through the APIs.

• Minimum time interval between two consecutive location reports.
• Timeout period for location reports.
• Horizontal accuracy level.

Data Services

Data Services APIs in the Telematics SDK used for cellular connectivity and modem profile 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

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 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

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 is mapped per below table, in future releases of SDK it will be made configurable. This configurability provides flexibility to map different Audio HAL devices to SDK representation.

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

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 Qualcomm'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

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