[开发工具]SOMEIP编译指导与应用解析

1. 编译说明

1.1. 依赖

• 需要启用 C++11 的编译器，例如 gcc >= 5.2。
• cmake编译工具
• 软件版本在1.55级以上的Boost库

1.2 编译

1.2.1 基础编译

• 工程下载：

  git clone https://github.com/GENIVI/vsomeip.git		# github地址
  # 如果上述地址clone失败，可以使用gitee链接
  git clone https://gitee.com/UItogether/vsomeip.git	# fork github project： GENIVI/vsomeip
  

• 编译安装：

  mkdir build
  cd build
  cmake ..
  make
  make install  # 可能需要： sudo make install
  

1.2.2 自定义安装目录

默认安装路径为/usr/local/，如果想自定安装路径（如 --prefix=）.

编译命令：

mkdir build
cd build
cmake -DCMAKE_INSTALL_PREFIX:PATH=$YOUR_PATH ..
make
make install

1.2.3 Compilation with predefined base path

预定义base path，用于创建本地套接字的路径。默认的base path是/tmp。
编译命令：

cmake -DBASE_PATH=<YOUR BASE PATH> ..

1.2.4 Compilation with predefined unicast and/or diagnosis address

• 预定义unicast地址

cmake -DUNICAST_ADDRESS=<YOUR IP ADDRESS> ..

• 预定义diagnosis address

cmake -DDIAGNOSIS_ADDRESS=<YOUR DIAGNOSIS ADDRESS> ..

1.2.5 Compilation with custom default configuration file

修改默认配置文件，编译命令:

cmake -DDEFAULT_CONFIGURATION_FILE=<DEFAULT CONFIGURATION FILE> ..

1.2.6 Compilation with signal handling

启动vsomeip信号(SIGINT/SIGTERM)处理的能力，编译命令:

cmake -DENABLE_SIGNAL_HANDLING=1 ..

1.2.7 Compilation with user defined “READY” message

使用用户定义的消息信号编译 vsomeip，IP 路由准备发送/接收消息。编译命令:

cmake -DROUTING_READY_MESSAGE=<YOUR MESSAGE> ..

1.2.8 Compilation with configuration overlays

启用配置覆盖，编译命令:

cmake -DENABLE_CONFIGURATION_OVERLAYS=1 ..

1.2.9 Compilation with vSomeIP 2 compatibility layer

启动 vsomeip 2兼容层，编译命令:

cmake -DENABLE_COMPAT=1 ..

1.3 编译样例

mkdir build
cd build
cmake ..
make example

1.4 编译测试

要编译test，首先将gtest解压到希望的位置。部分测试要求在同一网络中添加第二个节点。两个cmake变量可以自适应用于网络设置的json文件:

• TEST_IP_MASTER : master IP地址
• TEST_IP_SLAVE: slave IP地址
  如果其中某一变量未被设置，只可运行使用本地通信的测试。此外，单元测试需要启动信号处理，可以通过cmake变量ENABLE_SIGNAL_HANDLING来启动。
  编译命令:

mkdir build
cd build
export GTEST_ROOT=$PATH_TO_GTEST/gtest-1.7.0/
cmake -DENABLE_SIGNAL_HANDLING=1 -DTEST_IP_MASTER=10.0.3.1 -DTEST_IP_SLAVE=10.0.3.125 ..
make check

1.5 编译vsomeip_ctrl

mkdir build
cd build
cmake ..
make vsomeip_ctrl

1.6 生成文档

要生成文档，请按照 中的描述调用 cmake，然后调用 make doc。

• The README file in html: $BUILDDIR/documentation/README.html
• A doxygen documentation in $BUILDDIR/documentation/html/index.html

2. 启用someip应用与使用环境变量

vsomeip应用运行时，将读取下列环境变量信息：

• VSOMEIP_APPLICATION_NAME : 用于指定应用程序的名称。用于将客户端 ID 映射到配置文件中的应用程序。 独立于应用程序的二进制名称。
• VSOMEIP_CONFIGURATION: vsomeip使用默认配置文件/etc/vsomeip.json，或者默认配置文件夹/etc/vsomeip。可以修改该变量可以使用自定义配置文件。
• VSOMEIP_MANDATORY_CONFIGURATION_FILES: vsomeip允许使用mandatory配置文件来加快应用的启动速度。虽然强制配置文件由所有应用程序读取，但所有其他配置文件仅由负责连接到外部设备的应用程序读取。默认mandatory配置文件是：vsomeip_std.json, vsomeip_app.json和vsomeip_plc.json
• VSOMEIP_CLIENTSIDELOGGING: 将此变量设置为空字符串，以便在充当路由管理器代理的所有应用程序中将任何接收到的消息记录到 DLT。

注意：

• 如果由 VSOMEIP_CONFIGURATION 配置的文件/文件夹不存在，则将使用默认配置位置。
• vsomeip 将解析和使用配置文件夹中所有文件的配置，但不会考虑配置文件夹中的目录。

3. 配置json文件

vsomeip的配置文件由多个键值对和键值对数组构成：

• object是一组无序的名称/值对。object以{开始，以}结束，每一个键值对用:连接，多个键值对用,隔开。

• array是值的有序集合，array以[开始，以]结束，多个值由,隔开。

• 值可以是双引号中的 string，或 number，或 true 或 false 或 null，或 object 或 array。 这些结构可以嵌套。

3.1 基础配置

• unicast : 主机IP地址
• netmask : 主机的子网掩码
• device : 如果指定，IP endpoints将绑定到此设备
• diagnosis : 将用于构建客户端标识符的diagnosis address（一个字节）。如果未另行指定（例如通过预定义的 clientID），则diagnosis address将分配给所有客户端标识符中的最高有效字节。
• diagnosis_mask : 诊断掩码（2 字节）用于控制 ECU 上允许的最大并发 vsomeip 客户端数量和客户端 ID 的起始值。
• netmask : 网络标识符用于一个主机上支持多个路由的情况。这个设置改变了/dev/shm 中共享内存段的名字和/tmp/ 中unix 域套接字的名字。默认情况下，共享内存将被命名为/dev/shm/vsomeip 并且 unix 域套接字将被命名为 /tmp/vsomeip-$CLIENTID。

3.2 logging

• logging
  • level : 明确日志级别，有效值: trace, debug, info, warning, error, fatal。
  • console : 明确log是否通过控制台输出，有效值: true，false。
  • file
    • enable : 明确是否创建log文件，有效值: true，false。
    • path : log文件的绝对路径
  • dlt : 明确是否使能DLT(Diagnostic Log and Trace)，有效值: true，false。

3.3 Applications

• applications (array)
  • name : 应用名
  • id : 应用ID号
  • …
• services (array)
  • service : service id
  • instance : service instance id
  • reliable : 使用TCP协议进行通信，指定与服务的通信可靠
    • port : TCP endpoint port
    • enable-magic-cookies : 指定是否启用magic cookies，有效值：true，false。
  • unreliable : 使用 UDP 协议进行通信，指定与服务的通信不可靠，有效值: UDP的端口号
  • events (array)
    • event : event id
    • is_field : 指定事件是否为字段类型。字段是 getter、setter 和notification事件的组合。 它至少包含一个 getter、setter 或notification。notifier发送事件消息，该消息在更改时传输字段的当前值。
    • is_reliable : 是否使用TCP协议发送来指定通信是否可靠，有效值: true，false，false表示使用UDP协议。
  • eventgroups (array)
    • eventgroup: event group id
    • events (array) :
    • multicast : 指定用于发布事件组的multicast
    • address : multicast address
    • port : multicast port
    • …
  • …
• clients (array)
  • service
  • instance
  • reliable (array) : 用于与给定服务实例进行可靠 (TCP) 通信的client ports列表。
  • unreliable (array) : 用于与给定服务实例进行不可靠 (UDP) 通信的client ports列表
  • reliable_remote_ports :
  • unreliable_remote_ports :
  • …
• tcp-restart-aborts-max : 由于未完成的 TCP 握手，设置限制 TCP 客户端端点重启中止的次数。
• tcp-connect-time-max : 定义 TCP 客户端端点连接尝试完成之前的最长时间。
• udp-receive-buffer-size : 指定用于 UDP 客户端和服务器端点的套接字接收缓冲区（SO_RCVBUF）的大小（以字节为单位）。 （默认：1703936）
• routing : 负责路由的应用程序的名称
• service-discovery
  • enable : 指定是否启用Service Discovery，有效值: true，false。默认值是true。
  • multicast : Service Discovery消息将被发送到的multicast地址。默认值：224.0.0.1。
  • port : port of the Service Discovery，默认值：30490。
  • protocol : 用于发送Service Discovery消息的协议，有效值：TCP，UDP，默认值：UDP。
  • initial_delay_min ：第一次提供信息前的最小延迟
  • initial_delay_max ：第一次提供信息前的最大延迟
  • repetitions_base_delay ：Base delay sending offer messages within the repetition phase.
  • repetitions_max ：重复阶段内所提供服务的最大重复次数
  • ttl : 提供的服务以及消费的服务和事件组的条目的生命周期
  • cyclic_offer_delay : 主阶段中OfferService消息的周期
  • request_response_delay : 从单播消息到多播消息提供的服务和事件组的最小延时
  • offer_debounce_time ：

3.4 json文件配置样例

// 应用someip通信时，多个application的json要合并为一个。
// 注意: 运行应用前，务必确认json文件中不要有注释内容，会引发报错。
{
    "unicast":"172.31.3.67",	// 单播地址
    "diagnosis":"0x43",			// 一个字节
    "logging":		// log设置
    {
        "level":"debug",		// log level
        "console":"true",		// 在控制台输出
        "file" : 	// 设置日志文件
        {
            "enable" : "true",			// 创建日志文件
            "path" : "/**/vsomeip.log"	// 生成日志文件的绝对路径
        }
    },

    "applications": 	// 应用列表
    [
        {
            "name":"app_a",		// 应用名
            "id":"0x4300"		// 应用ID
        },
        {
            "name": "app_2",	// 应用名
            "id": "0x797"		// 应用ID
        } 
    ],

    "services":		// 服务列表
    [
        {	// 服务1
            "service":"0x1010",		// 服务ID
            "instance":"0x0013",	// instance ID
            "reliable":"30517"		// TCP传输
        },
		{	// 服务2
            "service": "0xB008",	// 服务ID
            "instance": "0x01",		// instance ID
            "unreliable": "41509",	// UDP传输
            "events": [		// 同一服务下的event列表
                {
                    "event": "0x0001",
                    "is_field": "false"
                },
                {
                    "event": "0x0002",
                    "is_field": "false"
                }
            ]
        },
        {	// 服务3
            "service": "0xB045",
            "instance": "0x01",
            "unreliable": "41570",
            "eventgroups": [	// 事件组
                {
                    "eventgroup" : "0x4455",
                    "events" : [ "0x777", "0x778" ]
                },
                {
                    "eventgroup" : "0x4465",
                    "events" : [ "0x778", "0x779" ],
                    "is_multicast" : "true"                                        
                },
                {
                    "eventgroup" : "0x4555",
                    "events" : [ "0x777", "0x779" ] 
                }
            ]
        }
    ],

    "udp-receive-buffer-size":"200000",
    "routing":"app_1",			// routing名
    "service-discovery":		// service-discovery配置
    {
        "enable" : "true",				// 使能SOMEIP-SD服务
        "multicast" : "239.127.3.1",	// 组播地址
        "port" : "30490",				// 端口
        "protocol" : "udp",				// 传输协议, someip-sd只能使用UDP传输协议
        "initial_delay_min" : "10",
        "initial_delay_max" : "50",
        "repetitions_base_delay" : "50",
        "repetitions_max" : "3",
        "ttl" : "300",
        "cyclic_offer_delay" : "1000",
        "request_response_delay" : "30"
    }
}

3.5 Autoconfiguration

vsomeip 支持自动配置客户端标识符和路由。如果没有明确配置，第一个开始使用 vsomeip 的应用程序将自动成为routing manager。客户端标识符是从诊断地址生成的，可以通过在编译vsomeip时定义DIAGNOSIS_ADDRESS来指定。vsomeip 将使用诊断地址作为高字节，并在客户端标识符的低字节内枚举连接的应用程序。

4. vsomeip – Hello World

4.1 编译执行vsomeip官方案例

4.1.1 案例说明

开发了一个由客户端和服务组成的 Hello World 程序。 客户端向服务发送一条包含字符串的消息。服务端将接收到的字符串附加到字符串 Hello 并将其发送回客户端。收到来自服务端的响应后，客户端打印响应的负载（“Hello World”）。

4.1.2 编译执行

• 按照vsomeip基础编译安装vsomeip

  mkdir build
  cd bbuild
  cmake ..
  make
  sudo make install
  

• 新建cmake工程并编译

  • 保留hello_world_client.hpp， hello_world_client_main.cpp， hello_world_service.hpp， hello_world_service_main.cpp， helloworld-local.json

  • CMakeLists.txt文件内容

    cmake_minimum_required(VERSION 2.8.7)
    
    # project name
    project(helloworld)
    
    # set compiler
    set(CMAKE_CXX_FLAGS "${CMAKE_CXX_FLAGS} -Wall -std=c++11 -g")
    
    # target
    add_executable(server src/hello_world_service_main.cpp)
    target_link_libraries(server pthread vsomeip3)
    
    add_executable(client src/hello_world_client_main.cpp)
    target_link_libraries(client pthread vsomeip3)
    

  • 工程目录结构

    hello_world
    |
    |----config
    |      |----helloworld-local.json
    |----src
    |      |----hello_world_client.hpp
    |      |----hello_world_client_main.cpp
    |      |----hello_world_service.hpp
    |      |----hello_world_service_main.cpp
    |----CMakeLists.txt
    
    

• 执行helloworld程序

  新建两个脚本：client.sh和server.sh，先执行server.sh，再执行client.sh。

  • client.sh内容

    #!/bin/bash
    
    env VSOMEIP_CONFIGURATION=./config/helloworld-local.json
    VSOMEIP_APPLICATION_NAME=client
    ./build/client
    

  • server.sh内容

    #!/bin/bash
    env VSOMEIP_CONFIGURATION=./config/helloworld-local.json
    VSOMEIP_APPLICATION_NAME=server
    ./build/server
    

• 运行结果

  • 服务端运行结果

    

  • 客户端运行结果

    

4.2 代码解析

4.2.1 服务端代码流程

• step1 - main() : 首先初始化应用程序，然后启动应用程序。
• step2 - init() : 注册message、state句柄
  • 注册message句柄：声明回调函数 on_message_cbk();
  • 注册state句柄：当发生状态更改时，声明回调函数: on_state_cbk()。
• step3 - start() ：启动app，只有当app stop时start()才返回。
• step4 :
  • on_state_cbk() : 当应用程序在运行时成功注册，则提供特定服务。
  • on_message_cbk() :当收到来自客户端的指定服务的消息/请求时调用此函数。首先创建基于请求的响应，然后，字符串“Hello”将与客户端请求的负载连接。之后，创建响应的有效负载。最后，发送响应到户端并停止应用程序。
• step5 - stop()：stop()函数会挂起，当on_message_cbk()完成响应调用terminate()函数时，将执行stop动作。
• step6 - teriminate(): 停止提供服务，注销message和state句柄，关闭应用。

4.2.2 客户端代码流程

• step1 - main() : 首先初始化应用程序，然后启动应用程序。
• step2 - init() : 注册message、availability和state句柄
  • 注册state句柄： 当发生状态更改时，声明回调函数: on_state_cbk()
  • 注册message句柄： 声明回调函数: on_message_cbk()，用于从任何服务、任何服务实例和任何方法接收的消息。
  • 注册availability句柄：声明回调函数: on_availability_cbk()。
• step3 :
  • on_state_cbk() : 当应用程序在运行时成功注册，则请求特定服务。
  • on_message_cbk() : 收到消息/响应时调用此函数。当响应来自请求的服务，类型为“RESPONSE”并且返回代码为“OK”，则打印响应的有效负载。然后停止运行。
  • on_availability_cbk() :
    • 首先检查可用性的更改是否与“hello world 服务”相关，并且可用性更改为 true。
    • 如果检查成功，则会创建服务请求并设置相应的服务信息（服务 ID、服务实例 ID、服务方法 ID）
    • 创建请求的有效负载， 设置有效载荷的数据。
    • 发送服务请求。
• step4 - stop() : 注销event、message句柄并关闭应用