The SOME/IP Gateway Server Service supports SOME/IP protocol(http://some-ip.com/) through vsomeip (https://github.com/COVESA/vsomeip) library APIs. It provides TelAF APIs for application to serve as a SOME/IP server which can receive client requests, send responses, produce events and publish the events over SOME/IP-SD message and SOME/IP message in the vehicle network.

IPC interfaces binding

The functions of this API are provided by the tafSomeipGWSvc application service.

The following example illustrates how to bind to the SOME/IP Gateway Server Service.

bindings:
{
    clientExe.clientComponent.taf_someipSvr -> tafSomeipGWSvc.taf_someipSvr
}

System Configuration

Before using any API of the service, the user needs to configure the system properly Since the SOME/IP Gateway Server 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

Multiple networks/VLANs configuration

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

Note: The value of name, routing, and network in configuration file must match the file name, which is tafSomeipGWSvc_1 in this case.

Server Service APIs

Before setting up a server-service-instance, application shall first get the service reference by calling taf_someipSvr_GetService() or taf_someipSvr_GetServiceEx() and use the reference returned for subsequent operations.

Note: One SOME/IP server-service-instance can be only represented by one application.

The following example illustrates how to set up a SOME/IP server-service-instance and offer the service on default network interface.

const uint16_t serviceId = 0x1234;     // Service ID
const uint16_t instanceId = 0x5678;    // Service instance
const uint8_t majorVer = 0x21;         // Major version of the service
const uint32_t minorVer = 0x87654321;  // Minor version of the service
const uint16_t tcpPort = 40000;        // TCP port of the service
const uint16_t udpPort = 40001;        // UDP port of the service
taf_someipSvr_ServiceRef_t serviceRef; // Service reference
// Get the service reference on the default network interface.
serviceRef = taf_someipSvr_GetService(serviceId, instanceId);
LE_ASSERT(serviceRef != NULL);
// Set the service version.
LE_ASSERT(LE_OK == taf_someipSvr_SetServiceVersion(serviceRef, majorVer, minorVer));
// Set the service ports.
LE_ASSERT(LE_OK == taf_someipSvr_SetServicePort(serviceRef, udpPort, tcpPort, true));
// Offer the service with our setting version and port.
LE_ASSERT(LE_OK == taf_someipSvr_OfferService(serviceRef));

Application can call taf_someipSvr_StopOfferService() to stop the service after the service is offered successfully.

Message APIs

After the service reference is got, the application can call taf_someipSvr_AddRxMsgHandler() to register a message handler for that service. Once a SOME/IP request message for the service is received, the message handler will be called and a message reference is passed as an input parameter to the application. The application can use this reference to retrieve the message header and payload, and then call taf_someipSvr_SendResponse() with the reference to send back a response. Finally call taf_someipSvr_ReleaseRxMsg() to release the message.

The following example illustrates how to register a message handler, get the message data and send back a response in a handler.

// Rx message handler function.
void RxMessageHandler
(
    taf_someipSvr_RxMsgRef_t msgRef,
    void* contextPtr
)
{
    // Get the service ID and instance ID.
    uint16_t serviceId;
    uint16_t instanceId;
    LE_ASSERT(LE_OK == taf_someipSvr_GetServiceId(msgRef, &serviceId, &instanceId));
    // Get the method ID client ID and message type.
    uint16_t methodId;
    uint16_t clientId;
    uint8_t msgType;
    LE_ASSERT(LE_OK == taf_someipSvr_GetMethodId(msgRef, &methodId));
    LE_ASSERT(LE_OK == taf_someipSvr_GetClientId(msgRef, &clientId));
    LE_ASSERT(LE_OK == taf_someipSvr_GetMsgType(msgRef, &msgType));
    // Get the payload.
    uint8_t payloadData[128];
    size_t payloadSize = sizeof(payloadData);
    char payloadString[2*sizeof(payloadData) + 1];
    LE_ASSERT(LE_OK == taf_someipSvr_GetPayloadSize(msgRef, &payloadSize));
    // Print out the message information.
    LE_INFO("Rx message(servId/instId/methId/cliId/msgType/len=0x%x/0x%x/0x%x/0x%x/0x%x/0x%x)",
            serviceId, instanceId, methodId, clientId, msgType, payloadSize);
    // Get the payload data if the payload is not empty.
    if (payloadSize != 0)
    {
        // Read the payload data into our buffer.
        payloadSize = sizeof(payloadData);
        LE_ASSERT(LE_OK == taf_someipSvr_GetPayloadData(msgRef, payloadData, &payloadSize));
        // Print out the payload data with hex string format.
        le_hex_BinaryToString(payloadData, payloadSize, payloadString, sizeof(payloadString));
        LE_INFO("MESSAGE PAYLOAD [%s]", payloadString);
    }
    // Send back the response with the same payload data. The Rx message will be automatically
    // released if sending the response succeeds.
    if (LE_OK != taf_someipSvr_SendResponse(msgRef, false, 0, payloadData, payloadSize));
    {
        // Only release the Rx message if sending the response fails.
        LE_ASSERT(LE_OK == taf_someipSvr_ReleaseRxMsg(msgRef));
    }
}
// Register the message handler.
taf_someipSvr_RxMsgHandlerRef_t RxMsgHandlerRef =
    taf_someipSvr_AddRxMsgHandler(ServiceRef, RxMessageHandler, NULL);
LE_ASSERT(RxMsgHandlerRef != NULL);

Note: One SOME/IP server-service-instance can register only one message handler.

Event APIs

After a service is offered, application can call taf_someipSvr_EnableEvent() to set up an event for the service and then call taf_someipSvr_OfferEvent() to offer the event within the vehicle network, later call taf_someipSvr_Notify() to publish the event with given payload data.

The following example illustrates how to set up an event and publish the event.

const uint16_t eventId = 0x8001;      // Event ID, valid range: 0x8001 to 0xFFFE
const uint16_t eventGroupId = 0x1; // Event Group ID, valid range: 0x0001 to 0xFFFE
// Enable the event by adding it to an event group.
LE_ASSERT(LE_OK == taf_someipSvr_EnableEvent(serviceRef, eventId, eventGroupId));
// Offer the event within the vehicle network.
LE_ASSERT(LE_OK == taf_someipSvr_OfferEvent(serviceRef, eventId));
// Publish the event with given payload.
uint8_t payloadData[5] = { 0x1, 0x2, 0x3, 0x4, 0x5 };
LE_ASSERT(LE_OK == taf_someipSvr_Notify(serviceRef, eventId, payloadData, sizeof(payloadData)));

Note: An event must be enabled before offering, and the taf_someipSvr_Notify() is available only after the event is offered.