DOCSEARCHbyAlgolia
Submit Docs

vSomeIP Documentation

repository·master·Indexed 23 days ago

https://github.com/covesa/vsomeip

A C++ implementation of the Scalable service-Oriented MiddlewarE over IP (SOME/IP) protocol for automotive communication. The stack includes core libraries for SOME/IP, configuration, service discovery, and E2E protection. Documentation covers building and installation on Linux, Windows, and Android, configuring IP multicast, and running Request/Response and Subscribe/Notify examples.

Tokens
24.5K
Snippets
58
Records
97
Agent score
80%

What's inside vSomeIP

  1. Overview of the vSomeIP stack

    master

    vSomeIP is a stack that implements the Scalable service-Oriented MiddlewarE over IP (SOME/IP) protocol. The stack is composed of several specialized shared libraries:

    • libvsomeip3.so: The core SOME/IP shared library.
    • libvsomeip3-cfg.so: The configuration module shared library.
    • libvsomeip3-sd.so: The service discovery shared library.
    • libvsomeip3-e2e.so: The E2E (End-to-End) protection module shared library.

  2. vSomeIP Stack Overview

    master

    The vSomeIP stack implements the SOME/IP (Scalable service-Oriented MiddlewarE over IP) protocol. The stack is composed of several shared libraries:

    • libvsomeip3.so: The core SOME/IP shared library.
    • libvsomeip3-cfg.so: Configuration module.
    • libvsomeip3-sd.so: Service Discovery module.
    • libvsomeip3-e2e.so: E2E (End-to-End) protection module.

  3. What is the nPDU feature (Zugverfahren)?

    master

    The nPDU (Network Protocol Data Unit) feature, also known as Zugverfahren, is used to reduce network load by allowing the vsomeip stack to combine multiple vsomeip messages into a single Ethernet frame.

    Key characteristics:

    • Trade-off: It trades network load reduction for increased latency (speed).
    • Configuration Requirement: Because nPDU settings are not transmitted via Service Discovery, they must be explicitly defined in the JSON configuration file used by the application acting as the routing manager.
    • Scope: It does not affect node internal communication over UNIX domain sockets.
    • Units: All timings are defined in milliseconds (ms).
    • Defaults: If debounce times for a method are missing or incomplete, the system uses 2ms debounce time and 5ms max retention time unless overwritten globally.

  4. Understand the vSomeIP Protocol Command Types

    master

    The vSomeIP protocol uses specific command IDs to manage application registration, service discovery, and configuration. Note that several registration-related commands have been deprecated since version 3.7.1 in favor of newer mechanisms.

    Active Commands

    • VSOMEIP_ASSIGN_CLIENT (0x00): Assigns a client.
    • VSOMEIP_ASSIGN_CLIENT_ACK (0x01): Acknowledgment for client assignment.
    • VSOMEIP_APPLICATION_LOST (0x04): Notifies that an application is no longer reachable.
    • VSOMEIP_ROUTING_INFO (0x05): Provides routing information.
    • VSOMEIP_PING (0x07): Connectivity check.
    • VSOMEIP_PONG (0x08): Response to a ping.
    • VSOMEIP_OFFER_SERVICE (0x10): Announces a service availability.
    • VSOMEIP_STOP_OFFER_SERVICE (0x11): Stops service announcement.
    • VSOMEIP_CONFIG (0x31): Used for transmitting configuration data.

    Deprecated Commands (Since 3.7.1)

    • VSOMEIP_REGISTER_APPLICATION (0x02)
    • VSOMEIP_DEREGISTER_APPLICATION (0x03)
    • VSOMEIP_REGISTERED_ACK (0x06)

  5. Configure End-to-End (E2E) protection

    master

    E2E protection can be enabled via the e2e configuration block. It allows you to protect specific events using different profiles.

    Core Keys

    • e2e_enabled: Set to true to enable protection.
    • protected: An array of objects defining the protection parameters for specific events.

    Protected Event Parameters

    • service_id: The service ID.
    • event_id: The event ID.
    • variant: Determines the role of the node:
      • protector: Sends the protection data.
      • checker: Validates the protection data.
      • both: Performs both actions.
    • profile: The E2E profile to use (CRC8, P04, P07, or CRC32 for Custom Ethernet CRC).

  6. Understand the Hello World Client lifecycle

    master

    The hello_world_client follows this execution pattern:

    1. Initialization (init): Registers a message handler (__on_message_cbk__) for any service/method, an event handler (__on_state_cbk__), and an availability handler (__on_availability_cbk__).
    2. Start (start): Starts the application. This call blocks until the application is stopped.
    3. State Change (on_state_cbk): Triggered on state changes; the client uses this to request the specific service.
    4. Availability (on_availability_cbk): Triggered when the requested service becomes available or unavailable. If available, the client creates a service request with the payload 'World' and sends it.
    5. Message Handling (on_message_cbk): Triggered when a message/response is received. If the response is from the requested service, is of type RESPONSE, and has a return code of OK, the payload is printed and the application stops.
    6. Stop (stop): Unregisters handlers and shuts down the application.

  7. Understand vSomeIP Autoconfiguration

    master

    vSomeIP supports automatic configuration of client identifiers and routing.

    • Routing Manager: The first application that starts using vSomeIP becomes the routing manager automatically if not explicitly configured.
    • Client Identifiers: These are generated from the DIAGNOSIS_ADDRESS (set during compilation). The address is used as the high byte, and connecting applications are enumerated in the low byte.

    Warning: Autoconfiguration is not intended for use with vSomeIP Security. If security is activated, every client must have its own credentials configured. If using autoconfiguration, it is only possible to mix with security if credentials for all clients are identical and configured for the overall DIAGNOSIS_ADDRESS range.

  8. Configure vSomeIP routing

    master

    Routing defines how applications communicate via the routing manager.

    Basic Routing

    You can specify routing by providing a single string representing the application name that hosts the routing component. If not specified, the first started application hosts it.

    "routing" : "service-sample",

    Internal Communication via TCP

    To use TCP for internal communication, use a structured routing object. This is useful when applications are on different machines or require specific network settings.

    Host Configuration

    The host object defines the properties of the routing manager:

    • name: Name of the application hosting the routing component.
    • uid/gid: User/Group identifiers (required if credential checks are enabled).
    • unicast: The unicast address for the routing manager.
    • port: The port for the routing manager.

    Guest Configuration

    The guests object defines properties for applications that are NOT the routing manager:

    • unicast: The unicast address for applications to connect to the routing manager. Defaults to the host's unicast address if not set.
    • ports: A set of port ranges used by clients. Each client requires two ports (one for receiving, one for sending).
      • You can specify uid and gid for specific ranges.
      • ranges consists of first and last port numbers.
      • Constraint: Each range must contain an even number of ports. The parity (even/odd) of the first port in a range must match the parity of the routing host port.

    Unix Domain Sockets (UDS)

    Set uds-preferred to true to prefer Unix Domain Sockets over TCP for internal communication between the routing manager and clients.

  9. Understand the Hello World Service lifecycle

    master

    The hello_world_service follows a specific execution pattern:

    1. Initialization (init): Registers a message handler (__on_message_cbk__) for specific service/method IDs and an event handler (__on_event_cbk__).
    2. Start (start): Starts the application. This call blocks until the application is stopped.
    3. State Change (on_state_cbk): Triggered when the application state changes (e.g., successful registration at runtime), at which point the service is offered.
    4. Message Handling (on_message_cbk): Triggered when a client request is received. The service creates a response, concatenates 'Hello' with the request payload, sets the response payload, sends it, and stops the application.
    5. Stop (stop): Unregisters handlers and shuts down the application.

  10. Configure vSomeIP Security using UNIX credentials

    master

    vSomeIP implements security based on UNIX credentials (UID/GID) passed via Unix-Domain-Sockets for local communication. When the security tag is present in the configuration, the routing manager must be configured as an application with a fixed client identifier.

    Key behaviors:

    • Authentication: During connection, the client transfers its UID/GID to the server. If they don't match the configured policy, the socket is closed.
    • Authorization: Once authenticated, the client ID is bound to the socket, allowing vSomeIP to check every incoming message (request/response/notification), service offer, or subscription against defined policies.
    • Audit Mode: You can run security in 'Audit Mode' to log violations without blocking them. To do this, include the security object but set check_credentials to false.
    • External Security: If the security field is left empty (but the tag exists), vSomeIP attempts to load an external security library (e.g., libvsomeip-sec.so.1).

  11. Configure nPDU debounce and retention times

    master

    The nPDU feature is controlled by two primary parameters per method:

    1. debounce-time-xxx: The minimal time required between sending messages to the same method of a remote service over the same connection (defined by src/dst address + src/dst port).
    2. max-retention-xxx: The maximum time a message to the same method of a remote service over the same connection is allowed to be buffered on the sender side.

    These are configured within the "services" section of the JSON file, specifically inside a "debounce-times" object at the service level.