vSomeIP &

CommonAPI Overview

André Oliveira
Gonçalo Almeida
Diogo Pedrosa
Discussion
• Who are we?
• Overview SOME/IP | vSomeIP
• Where is it used?
• SOME/IP
• vSomeIP
• CommonAPI & Tools
• Development / Integration

March 28, 2024 | Copyright© COVESA 2023 | 3

Who are we?

March 28, 2024 | Copyright© COVESA 2023 | 4

Overview SOME/IP | vSomeIP

March 28, 2024 | Copyright© COVESA 2023 | 5

Where is it used?

March 28, 2024 | Copyright© COVESA 2023 | 5

 SOME/IP
Scalable service-Oriented MiddlewarE over IP

March 28, 2024 | Copyright© COVESA 2023 | 12

Why SOME/IP

• Based on AUTOSAR specification.

• Automotive middleware solution that can be used for control messages.
• Network layer protocol designed for inter-device client-server serialization.
• Work with different operating systems.
• Replaces for the MOST control channel
• Fully supported in Wireshark

March 28, 2024 | Copyright© COVESA 2023 | 10

Specifications
Supports a wide range of middleware features
• Serialization
Transforms into and from on-wire representation.
• Remote Procedure Call (RPC) and Messaging
Implements remote invocation of functions as well as
other messages.
• Service Discovery (SD)
Detects and offers available services.
• Publish/Subscribe (Pub/Sub)
SOME/IP Message Format [1]
Configures which data is needed and shall be sent to
the client.
• Segmentation of UDP messages
Allows to transport larger SOME/IP messages over UDP
without the need of fragmentation.
[1] SOME/IP Protocol Specification AUTOSAR FO R22-11

March 28, 2024 | Copyright© COVESA 2023 | 6

Service Discovery
SOME/IP-SD is used to:
• Locate service instances.
• Detect if service instances are running.
• Implement the Publish/Subscribe handling.

Service Discovery Messages:

• Find
• Stop Offer
• Offer
• Stop Subscribe
• Subscribe
• Subscribe Nack
• Subscribe Ack

Some Requirements: SOME/IP-SD Message Format. [2]

• Sent over UDP.

• SD Messages shall start with a SOME/IP header.
• Shall support multiple entries that are combined in one
[2] SOME/IP Service Discovery Protocol Specification AUTOSAR FO R22-11
service discovery message.
March 28, 2024 | Copyright© COVESA 2023 | 6
Service Discovery

March 28, 2024 | Copyright© COVESA 2023 | 6

Communication
• Methods
The client can trigger remote procedure calls to
be executed on the server side
• Events
The server informs there is an event,
the client subscribe, and server send the event
• Notification
Are combinations of one or more of the following three:
I. A notifier which sends data on change from the provider
to the subscribers

II. A getter which can be called by the subscriber to

explicitly query the provider for the value

III. A setter which can be called by the subscriber when it wants

to change the value on provider side

March 28, 2024 | Copyright© COVESA 2023 | 6

 vSomeIP

March 28, 2024 | Copyright© COVESA 2023 | 12

Architecture

March 28, 2024 | Copyright© COVESA 2023 | 13

vSomeIP Test Strategy

• Build (Linux and Windows)

• Static Code Analysis (SonarQube)

• Functional Testing (Unit/Network tests)

March 28, 2024 | Copyright© COVESA 2023 | 13

New Features (3.3.0)

• Improved support for SOME/IP-TP

Reworked debounce (milliseconds to microseconds)

• Added internal communication using TCP

Optionally, instead of UDS only

• E2E Profile 4 support for service instances

Allows to specify multiple IDs (instances) for a specific profile/service ID

March 28, 2024 | Copyright© COVESA 2023 | 13

New Features (3.3.0)

• Support for external (or no) Restrict IPC implementations

Disable the RestrictIPC (via compile switch)
Replace the RestrictIPC implementation by a user defined library

• Client-specific Debouncing
Specify debounce within the application code, replacing debounce conf. file

• Header-only Tracing
Only the header will be logged, not the entire message (removing the payload)

March 28, 2024 | Copyright© COVESA 2023 | 13

vSomeIP Configurations
• Application Configurations: applications of the host system that use this config file

• Service Configurations: services of the service provider

• Routing Manager Configuration: name of the application that is responsible for the routing

• Service Discovery Configurations: settings related to the Service Discovery of the host application

• Security Configurations: implementation based on UNIX credentials

• Tracing Configurations: defining messages that will be forwarded to DLT

• Debounce Configurations: filter high frequency events/fields

https://github.com/COVESA/vsomeip/blob/master/documentation/vsomeipUserGuide

March 28, 2024 | Copyright© COVESA 2023 | 13

vSomeIP Configuration
{ // Internal communication using UDS (OPTION 1)
"routing" : "service-sample",
"unicast" : "10.0.3.1",
"logging" : // Internal communication using TCP (OPTION 2)
{ "routing" : {
"level" : "debug", "host" : {
"console" : "true", "name" : "service-sample",
"unicast" : "10.0.3.1",
"file" : { "enable" : "false", "path" : "/tmp/vsomeip.log" },
"port" : "31000"
"dlt" : "false" },
}, "guests" : {
"applications" : "unicast" : "10.0.3.1",
[ "ports" :
[
{
{
"name" : "client-sample", "first" : "1026",
"id" : "0x1243" "last" : "65535"
}, }
{ ]
}
"name" : "service-sample",
},
"id" : "0x1277"
} "service-discovery" :
], {
"services" : "enable" : "true",
"multicast" : "224.244.224.245",
[
"port" : "30490",
{ "protocol" : "udp"
"service" : "0x1234", }}
"instance" : "0x5678",
"reliable" : { "port" : "30509", "enable-magic-cookies" : "false" },
"unreliable" : "31000"
}
],

March 28, 2024 | Copyright© COVESA 2023 | 13

Tracing Configuration
{
"tracing": { Filter Types:
"filters": [{
"channel": "TC",
"services": ["0xfc2a", "0xfc3a", "0xfc4a", "0xfc5a", "0xfc6a", "0xfc7a", "0xfc8a"],
"type": "positive"
Positive
}
} • Only logs that service/instance/method in DLT
}

{​
"tracing": {​
"filters": [{​ Negative
"channel": "TC",​
"services": ["0xc15a", "0xc15b", "0xc15c", "0xc15d", "0xc15e", "0xc1be", • Do not log that service/instance/method in DLT
"0xf0ce", "0xf0cf"],​
"type": "negative"​ • Avoid spamming the logs
},{​
"channel": "TC",​
• Hide sensitive information
"matches" : [​
{ "service" : "0x2c58", "instance" : "any", "method" : "0x8001" },​
{ "service" : "0x2c58", "instance" : "any", "method" : "0x8002" }​
],​
"type": "header-only"​
Header-Only
}]​
}​ • Only logs the full SOME/IP Header (16 Bytes)
}
• Avoid spamming the logs

March 28, 2024 | Copyright© COVESA 2023 | 13

Debounce Configuration
{
"debounce" :
[
{
"service" : "0x1230",
"instance" : "0x0001",
"events" : The debounce is used to filter high frequency events/fields.
[
{
"event" : "0x8001",
"on_change" : "false",
• Checks if a specified interval has been elapsed since the
}
"interval" : "50"
last forwarding.
]
}, • Optionally, it is also possible to send all the event/field
{
"service" : "0x2349", payload changes (on_change = true).
"instance" : "0x0001",
"events" :
[
{
"event" : "0x0008",
"on_change" : "true",
"interval" : "100"
}
]
}
]
}

March 28, 2024 | Copyright© COVESA 2023 | 13

 CommonAPI & Tools
CommonAPI

CommonAPI-SomeIP

CommonAPI-DBus

Tools

March 28, 2024 | Copyright© COVESA 2023 | 12

CommonAPI Integration Overview
• Standardized C++ API specification for the development of distributed applications that
communicate via a middleware for inter-process communication.
• Main intention is to make the C++ interface for applications independent from the
underlying IPC stack.

Application
Core
Validator
Franca IDL
CommonAPI C++ Core .cpp/hpp Core Code Generator *.fidl

SOME/IP or import
D-Bus
Validator
(SOME/IP or D-Bus)
CommonAPI C++ (SOME/IP or .cpp/hpp (SOME/IP or D-Bus) Code
Deployment
D-Bus) Binding Generator
*.fdepl

vSomeIP or D-Bus

March 28, 2024 | Copyright© COVESA 2023 | 13

Internal Runtime CommonAPI APIs
The user API of CommonAPI is divided up into two parts:
• A FrancaIDL based, generated part which contains
API functions that are related to the types, attributes
and methods of the Aplication FrancaIDL files.
• A "common" part (Runtime API) which contains API
functions for loading the runtime environment, creating
proxies and so on.

Generate code for Implement a service

Create the proxy in
Create client and service with the methods in
the client and use
the FrancaIDL files. using the CAPI the generated
its methods
generator. skeleton.

March 28, 2024 | Copyright© COVESA 2023 | 13

CommonAPI C++ Load Libraries

• The application must link against

the CommonAPI runtime library and against the
generated CommonAPI C++ code but not
against any binding specific code.

• The CommonAPI C++ configuration file contains

the information if the D-Bus glue-code or the
SOME/IP glue-code shall be loaded by the runtime
linker.

• Flexible procedure that even allows it to create

two instances of the same interface in one
application and one instance can be accessed via
D-Bus; the other via SOME/IP.

March 28, 2024 | Copyright© COVESA 2023 | 13

 Franca IDL and Deployment examples
E01HelloWorld.fidl E01HelloWorld-SomeIP.fdepl

package commonapi.examples import "platform:/plugin/org.genivi.commonapi.someip/deployment/CommonAPI-4-SOMEIP_deployment_spec.fdepl"

import "E01HelloWorld.fidl"
interface E01HelloWorld {
version { major 0 minor 1 } define org.genivi.commonapi.someip.deployment for interface commonapi.examples.E01HelloWorld {
SomeIpServiceID = 4660
method sayHello {
in { method sayHello {
String name SomeIpMethodID = 30000 Interface Name
} SomeIpReliable = true
out { ...
String message } Unique ServiceID
} }
}
} define org.genivi.commonapi.someip.deployment for provider as Service {
instance commonapi.examples.E01HelloWorld as HelloWorld {
InstanceId = "commonapi.examples.HelloWorld" Instance Name

SomeIpInstanceID = 22136

SomeIpUnicastAddress = "192.168.0.2" Instance Ids

SomeIpReliableUnicastPort = 30499
SomeIpUnreliableUnicastPort = 30499
}
}

https://github.com/COVESA/capicxx-core-tools/tree/master/CommonAPI-Examples

March 28, 2024 | Copyright© COVESA 2023 | 13

Application example: Hello World
Service Client

Stub

March 28, 2024 | Copyright© COVESA 2023 | 13

Application Architecture

March 28, 2024 | Copyright© COVESA 2023 | 13

 Development / Integration

March 28, 2024 | Copyright© COVESA 2023 | 12

Covesa branches

maintain/2.6 maintain/3.1 master

vSomeIP 2.6 vSomeIP 3.1 vSomeIP 3.3

Released 10 years ago Released 3 years ago Released this year

Not supported Support until April 30th, 2023 Development in progress

March 28, 2024 | Copyright© COVESA 2023 | 13

Covesa vs Internal Branch

March 28, 2024 | Copyright© COVESA 2023 | 13

Announcements

• Propose meeting with COVESA community every 3 months

• With the vSomeIP 3.3 release there are no further features planned

• New improvement/feature ideas are welcome through:

https://github.com/COVESA/vsomeip/discussions/categories/ideas

March 28, 2024 | Copyright© COVESA 2023 | 13

 Any questions?

Thank you

March 28, 2024 | Copyright© COVESA 2023 | 12