|
Snapdragon® Telematics Application Framework (TelAF) Interface Specification
|
The SOME/IP Gateway Client Service supports SOME/IP protocol(http://some-ip.com/) through vsomeip (https://github.com/COVESA/vsomeip) library APIs. It provides a set of simple and high level TelAF APIs for applications to communicate with remote SOME/IP servers, so that the applications can discover and connect to a service, send requests and get responses, subscribe to and receive events, as well as handle errors.
The functions of this API are provided by the tafSomeipGWSvc application service.
The following example illustrates how to bind to the SOME/IP Gateway Client Service.
bindings:
{
clientExe.clientComponent.taf_someipClnt -> tafSomeipGWSvc.taf_someipClnt
}
Before using any API of the service, the user needs to configure the system properly. Since the SOME/IP Gateway Client Service is built upon vsomeip library, the configuration follows the same JSON format as vsomeip. The user can take the default vsomeip JSON file which locates in /legato/systems/current/appsWriteable/tafSomeipGWSvc/tafSomeipGWSvc.json as a template to make their own specific configuration. The default JSON file is as below:
{
"unicast" : "192.168.225.1",
"device" : "bridge0",
"logging" :
{
"level" : "error",
"console" : "true",
"file" : { "enable" : "false", "path" : "/tmp/vsomeip.log" },
"version" : { "enable" : "false", "interval" : "10" },
"dlt" : "false"
},
"applications" :
[
{
"name" : "tafSomeipGWSvc",
"id" : "0x0101"
}
],
"routing" : "tafSomeipGWSvc",
"network" : "tafSomeipGWSvc",
"service-discovery" :
{
"enable" : "true",
"multicast" : "224.0.0.1",
"port" : "30490",
"protocol" : "udp",
"initial_delay_min" : "10",
"initial_delay_max" : "100",
"repetitions_base_delay" : "200",
"repetitions_max" : "3",
"ttl" : "3",
"cyclic_offer_delay" : "2000",
"request_response_delay" : "1500"
}
}
Mandatorily, the unicast and device must be set with the correct IP address and network interface in the system for SOME/IP communications. The id in applications section shall be set with a unique client ID within the given network. Optionally, the SOME/IP-SD parameters (like multicast) in service-discovery section can be changed if needed.
Restart the tafSomeipGWSvc service or reboot the device to make the new configuration take effect after any modifications.
Finally run below command to add a route entry for the SOME/IP-SD multicast address(Suppose the network interface is "bridge0" and the multicast address is "224.0.0.1"):
route add 224.0.0.1 dev bridge0
The default configuration file is only for single network/VLAN which is also the default network. If the user wants to support multiple networks/VLANs in the GW service, they have to create additional configuration files. These configuration files can be tafSomeipGWSvc_1.json to tafSomeipGWSvc_7.json, which means a maximum of 8 networks/VLANs can be supported. For example, the user can create below configuration file to support the second network/VLAN in the GW service:
{
"unicast" : "192.168.226.1",
"device" : "eth1",
"logging" :
{
"level" : "error",
"console" : "true",
"file" : { "enable" : "false", "path" : "/tmp/vsomeip.log" },
"version" : { "enable" : "false", "interval" : "10" },
"dlt" : "false"
},
"applications" :
[
{
"name" : "tafSomeipGWSvc_1",
"id" : "0x0102"
}
],
"routing" : "tafSomeipGWSvc_1",
"network" : "tafSomeipGWSvc_1",
"service-discovery" :
{
"enable" : "true",
"multicast" : "225.0.0.1",
"port" : "30490",
"protocol" : "udp",
"initial_delay_min" : "10",
"initial_delay_max" : "100",
"repetitions_base_delay" : "200",
"repetitions_max" : "3",
"ttl" : "3",
"cyclic_offer_delay" : "2000",
"request_response_delay" : "1500"
}
}
In this case, a second configuration file tafSomeipGWSvc_1.json is created for network interface "eth1" with its own network address and multicast address.
Before setting up a client-service-instance, application shall first get the service reference by calling taf_someipClnt_RequestService() or taf_someipClnt_RequestServiceEx() and use the reference returned for subsequent operations.
The following example illustrates how to set up a SOME/IP client-service-instance and connect to a service on default network interface.
Application can call taf_someipClnt_AddStateChangeHandler() to register a state change handler for that service. Once the service state change happens, the handler will be called and the new state is passed as an input parameter to the application.
The following example illustrates how to register a state change handler, and get the service version once the service state becomes available.
Applications can call taf_someipClnt_GetState() to get the current service state. Applications can also call taf_someipClnt_ReleaseService() to disconnect to the service if the application does not use the service any longer.
Application can send a request message with a given method and payload data to a service after the service is available and get the response message in a callback handler later.
The following example illustrates how to create a request message, send the message, and get the response.
The application can call taf_someipClnt_EnableEventGroup() taf_someipClnt_SubscribeEventGroup() to set up the events with the event group it is interested in for a service. It can then call taf_someipClnt_AddEventMsgHandler() to register an event message handler for that event group. Later, once a SOME/IP event message of that event group is received, the message handler will be called with the service reference and event ID passed as input parameters.
The following example illustrates how to set up two events in an event group, and register an event message handler for that event group.