TelSDK simulation enables development of applications using the SDK's APIs on any Linux based hardware. The simulation is intended to enable software development, even before the actual Telematics hardware is available. Users can run the simulation on a Linux desktop if they choose.

The Simulation framework provides libraries which are compile time equivalent to the actual concrete libraries. The simulation libraries provide the behavior of APIs similar to the behavior seen on an actual Telematics device with the concrete libraries.

This allows applications to be developed, compiled, and executed using this framework. An application can link to the simulation libraries to use the functionality of the SDK APIs in this framework. The same application can then be recompiled for the target Telematics device without requiring any redevelopment or code changes.

The Simulation framework is designed to be configurable to tweak the behavior and the responses of the APIs. This provides flexibility to exercise the client code in multiple ways and scenarios. Users can run the Simulation framework within a docker as well if desired.

Components of the simulation framework

This section provides an overview of the components involved in the TelSDK simulation framework.

SDK Simulation Libraries

The telematics simulation library runs in the user space of the Linux system. It interacts with the simulation server and other subsystems to provide various services like phone calls, SMS, etc. These services are exposed by the SDK through the same fixed public APIs that are available on all Telematics platforms that support SDK.

Simulation Server

This is the main daemon that interacts with all the clients using the Simulation framework and provides the functionality for all the public APIs.

Event Injector

Event injector allows the users to inject unsolicited events. It is a Linux based command-line utility that injects events into the simulation framework.
For example: telsdk_event_injector -f tel_card -e cardInfoChanged <slotId> <cardPower> could be triggered to change the card power state.

This tool can also be used to dynamically update JSON files for API behaviors.

Syntax for injecting events: telsdk_event_injector -f <filter/subsystem/manager> -e <event> <arguments>

-f: specifies the filter.
-e: specifies the event that is triggered.

To get help related to the events supported by TelSDK simulation.

telsdk_event_injector -h: provides the list of subsystems for which events are available.
telsdk_event_injector -h <subsystem>: provides the list of supported events in that particular subsystem.
telsdk_event_injector -h <subsystem> <event>: provides detailed information ,i.e., the syntax and arguments for that event.

Build Steps

To build various components of the Simulation framework:

Fetch the source code
1 $ git clone https://git.codelinaro.org/clo/le/platform/vendor/qcom-opensource/snaptel-sdk.git -b telsdk.lnx.2.0.r11-rel telux
2 $ cd telux/
Set up Build dependencies
1 #Install jsoncpp, cmake 3.15.3, gRPC.
2 $ ./build_sim.sh setup <DESTINATION_FOLDER_ROOT_PATH>
Build simulation libraries, TelSDK sample apps, and test apps
1 $ ./build_sim.sh all <DESTINATION_FOLDER_ROOT_PATH>
Note: All the required TelSDK simulation include files, libs, and binaries get installed in <DESTINATION_FOLDER_ROOT_PATH>
To perform a build for user applications
1 $ cmake -DCMAKE_CXX_STANDARD_INCLUDE_DIRECTORIES=<DESTINATION_FOLDER_ROOT_PATH>/include -DCMAKE_INSTALL_PREFIX=<DESTINATION_FOLDER_ROOT_PATH> <APPS_CMAKE_PATH> && make install

Run apps with docker

To run applications within the docker container:

Install docker
1 $ sudo apt update
2 $ sudo apt install apt-transport-https ca-certificates curl software-properties-common
3 $ curl -fsSL https://download.docker.com/linux/ubuntu/gpg | sudo apt-key add -
4 $ sudo add-apt-repository "deb [arch=amd64] https://download.docker.com/linux/ubuntu bionic stable"
5 $ sudo apt update
6 $ sudo apt install docker-ce
Once the installation is complete, we recommend that users do the following to add a docker affiliation group for the current user. This will make it easier to develop and avoid typing the "sudo" prefix every time.
1 $ sudo usermod -aG docker ${USER}
Build docker image
1 $ cd telux/
2 $ ./build_sim.sh docker-image <DESTINATION_FOLDER_ROOT_PATH>
Run docker container
1 $ docker run -ti --rm -h telsdk_simulation -v telsdk_volume:/data/telux telsdk-sim-image
User application can be started or if users wish to run one of the SDK's sample app or test app within the docker, then
1 $ <APP_NAME>

Note:

The docker image built will have user application binaries installed to the docker container /usr/bin/ path.
When the docker container is started, it automatically starts the simulation server in the background.
The path /data/telux/ holds all TelSDK simulation related data.
We are making use of the docker volume, to make this folder /data/telux persistent across multiple boots of the docker.
To reset the persistent data, delete the docker volume.

Run apps without docker

To run applications without the docker container:

Export library path
1 $ source <DESTINATION_FOLDER_ROOT_PATH>/bin/setup_simulation.sh
Start simulation server in the background
1 $ telsdk_simulation_server &
User application can be started or if users wish to run one of the SDK's sample app or test app, then
1 $ <APP_NAME>

Note:

In the host machine, application binaries are installed to the <DESTINATION_FOLDER_ROOT_PATH>/bin/
The path <DESTINATION_FOLDER_ROOT_PATH>/data/telux/ holds all TelSDK simulation related data.
The path <DESTINATION_FOLDER_ROOT_PATH>/etc/telux/tel.conf holds TelSDK simulation configuration data.

Controlling the behavior of the simulation

Managing subsystem readiness or service availability

TelSDK initializes various subsystems during startup. It marks each subsystem as ready once the initialization procedures are completed for that subsystem. The application must wait until the corresponding subsystem on which it needs to make API requests is ready. TelSDK provides APIs to check whether a subsystem is ready or not.

The Simulation framework simulates subsystem readiness. The behavior and timing of this can be configured via the API specific JSON file. These user configurable JSON files are located under the path /data/telux/json/api/ and the name of the JSON file corresponds to the subsystem name specified in the public headers.

For example: IDataConnectionManager.json present in /data/telux/json/api/

JSON Attribute	Description
IsSubsystemReady	Specifies the subsystem readiness.
IsSubsystemReadyDelay	Specifies time the simulation framework should take to indicate subsystem readiness.

Response Management

TelSDK simulation framework allows simulating each API response via updating the API specific JSON file. The table shows the JSON attributes to modify the behavior of the API in simulation

JSON Attribute	Description
DefaultCallbackDelay	For all the public APIs this delay would be the default delay and would only be considered if callbackDelay is not specified.
status	It specifies the immediate synchronous response that application would receive when the TelSDK API is invoked. It is usually the return status of the API invoked.
callbackDelay	specifies the time that simulation libraries shall take before invoking the callback function and -1 could be configured to avoid callback invocation. This would be given preference over DefaultCallbackDelay.
error	Specifies ErrorCode that will be sent along with the user provided callback function.

The JSON for API behavior could be updated dynamically by injecting the json_update event. Use the telsdk_event_injector help option to get more details.
Syntax to update the json file: telsdk_event_injector -f json_update -e modify <path> <subsystem> <api> <attribute> <val>

For example: Considering the below API entry in JSON

"getDefaultProfile": {
        "callbackDelay": 400,
        "error": "SUCCESS",
        "status": "SUCCESS"
},

The command telsdk_event_injector -f json_update -e modify /api/data/IDataConnectionManager.json IDataConnectionManager getDefaultProfile callbackDelay 300. would update callbackDelay to 300

There will be cases where additional fields in response management would be needed. For example: SMS management.

Sending external events

TelSDK simulation framework lets users simulate certain system level behaviors by injecting unsolicited event using event injector. Use the event injector helper option to get detailed information about the events supported by each subsystem.

Simulation data

The data stored and used by the simulation can be classified into three categories as mentioned below:

API response data: Specifies API responses as described in the section Response Management above. For example: synchronous response or asynchronous response. JSON files under the path /data/telux/json/api/ hold the API responses. Users can modify this file to change the value returned in the response.
Static system data: Specifies static persistent data. For example: IMEI number, thermal zone information, etc. JSON files under the path /data/telux/json/system-info/ hold the system static data. It is used internally by our TelSDK simulation libraries to maintain system states and shall not be altered externally.
Dynamic system data: Specifies dynamic persistent data. For example: RAT preference, VLAN configuration, Backhaul configuration, etc. JSON files under the path /data/telux/json/system-state/ hold the system state. It is used internally by our TelSDK simulation libraries to maintain system states and shall not be altered externally.

Logging in simulation

TelSDK simulation framework supports logging. User configurable logger settings available in /etc/telux/tel.conf are listed below.

LOGGER_LEVEL	Supported log levels are: NONE - No logging PERF - Prints messages with nanoseconds precision timestamp. ERROR - Very minimal logging. Prints error messages only. WARNING - Prints perf, error and warning messages. INFO - Prints errors, warning, and information messages. DEBUG - Full logging including debug messages.It is intended for debugging purposes only.
LOGGER_TYPE	Supported log types are: CONSOLE_LOG - enables console logging FILE_LOG - enables file-based logging. Once file logging is enabled, LOG_FILE_NAME and LOG_FILE_PATH could further be configured by users. SYSLOG_LOG - enables syslog logging.

Multi-SIM configuration in simulation

MULTISIM_CONFIG in etc/telux/tel.conf specifies type of multi-SIM configuration supported. By default, multi-SIM configuration is not enabled.

Simulation under different verticals

The details on how simulation of individual areas can be used and controlled are available below.