1vsomeip 2======= 3// This enables a nice TOC as a sidebar 4:toc2: 5// Show all headings in TOC 6:toclevels: 4 7// Show icons if e.g. TIP: or IMPORTANT is used 8:icons: 9// Set the directory where the default icons can be found 10:iconsdir: {asciidoc-confdir}/{iconsdir} 11// number all headings 12:numbered: 13// this embeds images (e.g. the icons for TIP: $TEXT) into the html file 14:data-uri: 15 16Copyright 17+++++++ 18Copyright (C) 2015-2019, Bayerische Motoren Werke Aktiengesellschaft (BMW AG) 19 20License 21+++++++ 22This Source Code Form is subject to the terms of the Mozilla Public 23License, v. 2.0. If a copy of the MPL was not distributed with this 24file, You can obtain one at http://mozilla.org/MPL/2.0/. 25 26Version 27+++++++ 28// set the version to the one we get from cmake 29// or pass it via -a version=$VSOMEIP_VERSION to asciidoc 30This documentation was generated for version {version} of vsomeip. 31 32vsomeip Overview 33---------------- 34The vsomeip stack implements the http://some-ip.com/[Scalable service-Oriented 35MiddlewarE over IP (SOME/IP)] protocol. The stack consists out of: 36 37* a shared library for SOME/IP (`libvsomeip.so`) 38* a second shared library for SOME/IP's service discovery (`libvsomeip-sd.so`) 39 which is loaded during runtime if the service discovery is enabled. 40 41Build Instructions 42------------------ 43Dependencies 44~~~~~~~~~~~~ 45* A C++11 enabled compiler like gcc >= 5.2 is needed. 46* vsomeip uses cmake as buildsystem. 47* vsomeip uses Boost >= 1.55: 48** Ubuntu 14.04: 49*** `sudo apt-get install libboost-system1.55-dev libboost-thread1.55-dev 50 libboost-log1.55-dev` 51** Ubuntu 12.04: a PPA is necessary to use version 1.54 of Boost: 52*** URL: https://launchpad.net/~boost-latest/+archive/ubuntu/ppa 53*** `sudo add-apt-repository ppa:boost-latest/ppa` 54*** `sudo apt-get install libboost-system1.55-dev libboost-thread1.55-dev 55 libboost-log1.55-dev` 56* For the tests Google's test framework 57 https://code.google.com/p/googletest/[gtest] in version 1.7.0 is needed 58** URL: https://googletest.googlecode.com/files/gtest-1.7.0.zip[direct link, 59 version 1.7.0] 60* To build the documentation asciidoc, source-highlight, doxygen and graphviz is needed: 61** `sudo apt-get install asciidoc source-highlight doxygen graphviz` 62 63Compilation 64~~~~~~~~~~~ 65anchor:Compilation[] 66For compilation call: 67[source, bash] 68---- 69mkdir build 70cd build 71cmake .. 72make 73---- 74 75To specify a installation directory (like `--prefix=` if you're used to 76autotools) call cmake like: 77[source, bash] 78---- 79cmake -DCMAKE_INSTALL_PREFIX:PATH=$YOUR_PATH .. 80make 81make install 82---- 83 84Compilation with predefined base path 85^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 86To predefine the base path, the path that is used to create the local sockets, 87call cmake like: 88[source,bash] 89---- 90cmake -DBASE_PATH=<YOUR BASE PATH> .. 91---- 92The default base path is /tmp. 93 94Compilation with predefined unicast and/or diagnosis address 95^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 96To predefine the unicast address, call cmake like: 97[source,bash] 98---- 99cmake -DUNICAST_ADDRESS=<YOUR IP ADDRESS> .. 100---- 101 102To predefine the diagnosis address, call cmake like: 103[source,bash] 104---- 105cmake -DDIAGNOSIS_ADDRESS=<YOUR DIAGNOSIS ADDRESS> .. 106---- 107The diagnosis address is a single byte value. 108 109Compilation with custom default configuration folder 110^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 111To change the default configuration folder, call cmake like: 112[source,bash] 113---- 114cmake -DDEFAULT_CONFIGURATION_FOLDER=<DEFAULT CONFIGURATION FOLDER> .. 115---- 116The default configuration folder is /etc/vsomeip. 117 118Compilation with custom default configuration file 119^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 120To change the default configuration file, call cmake like: 121[source,bash] 122---- 123cmake -DDEFAULT_CONFIGURATION_FILE=<DEFAULT CONFIGURATION FILE> .. 124---- 125The default configuration file is /etc/vsomeip.json. 126 127Compilation with signal handling 128^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 129To compile vsomeip with signal handling (SIGINT/SIGTERM) enabled, 130call cmake like: 131[source,bash] 132---- 133cmake -DENABLE_SIGNAL_HANDLING=1 .. 134---- 135In the default setting, the application has to take care of shutting 136down vsomeip in case these signals are received. 137 138Compilation with user defined "READY" message 139^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 140To compile vsomeip with a user defined message signal the IP routing 141to be ready to send/receive messages, call cmake like: 142[source,bash] 143---- 144cmake -DROUTING_READY_MESSAGE=<YOUR MESSAGE> .. 145---- 146 147Compilation with configuration overlays 148^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 149To compile vsomeip with configuration overlays enabled, call cmake 150like: 151[source,bash] 152---- 153cmake -DENABLE_CONFIGURATION_OVERLAYS=1 .. 154---- 155 156Compilation with vSomeIP 2 compatibility layer 157^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 158To compile vsomeip with enabled vSomeIP 2 compatibility layer, call 159cmake like: 160[source,bash] 161---- 162cmake -DENABLE_COMPAT=1 .. 163---- 164 165Compilation of examples 166^^^^^^^^^^^^^^^^^^^^^^^ 167For compilation of the examples call: 168[source, bash] 169---- 170mkdir build 171cd build 172cmake .. 173make examples 174---- 175 176Compilation of tests 177^^^^^^^^^^^^^^^^^^^^ 178To compile the tests, first unzip gtest to location of your desire. 179Some of the tests require a second node on the same network. There are two cmake 180variables which are used to automatically adapt the json files to the used 181network setup: 182 183* `TEST_IP_MASTER`: The IP address of the interface which will act as test 184 master. 185* `TEST_IP_SLAVE`: The IP address of the interface of the second node which will 186 act as test slave. 187 188If one of this variables isn't specified, only the tests using local 189communication exclusively will be runnable. 190 191Additionally the unit tests require enabled signal handling which can be enabled 192via the `ENABLE_SIGNAL_HANDLING` cmake variable. 193 194Example, compilation of tests: 195[source, bash] 196---- 197mkdir build 198cd build 199export GTEST_ROOT=$PATH_TO_GTEST/gtest-1.7.0/ 200cmake -DENABLE_SIGNAL_HANDLING=1 -DTEST_IP_MASTER=10.0.3.1 -DTEST_IP_SLAVE=10.0.3.125 .. 201make check 202---- 203 204Additional make targets for the tests: 205 206* Call `make build_tests` to only compile the tests 207* Call `ctest` in the build directory to execute the tests without a verbose 208 output 209* To run single tests call `ctest --verbose --tests-regex $TESTNAME` short 210 form: `ctest -V -R $TESTNAME` 211* To list all available tests run `ctest -N`. 212* For further information about the tests please have a look at the 213 `readme.txt` in the `test` subdirectory. 214 215For development purposes two cmake variables exist which control if the 216json files and test scripts are copied (default) or symlinked into the build 217directory. These settings are ignored on Windows. 218 219* `TEST_SYMLINK_CONFIG_FILES`: Controls if the json and scripts needed 220 to run the tests are copied or symlinked into the build directory. (Default: 221 OFF, ignored on Windows) 222* `TEST_SYMLINK_CONFIG_FILES_RELATIVE`: Controls if the json and scripts needed 223 to run the tests are symlinked relatively into the build directory. 224 (Default: OFF, ignored on Windows) 225 226Example cmake call: 227[source, bash] 228---- 229cmake -DTEST_SYMLINK_CONFIG_FILES=ON -DTEST_SYMLINK_CONFIG_FILES_RELATIVE=ON .. 230---- 231 232For compilation of only a subset of tests (for a quick 233functionality check) the cmake variable `TESTS_BAT` has 234to be set: 235 236Example cmake call: 237[source, bash] 238---- 239cmake -DTESTS_BAT=ON .. 240---- 241 242Compilation of vsomeip_ctrl 243^^^^^^^^^^^^^^^^^^^^^^^^^^^ 244For compilation of the <<vsomeip_ctrl>> utility call: 245[source, bash] 246---- 247mkdir build 248cd build 249cmake .. 250make vsomeip_ctrl 251---- 252 253Generating the documentation 254^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 255To generate the documentation call cmake as described in <<Compilation>> and 256then call `make doc`. 257This will generate: 258 259* The README file in html: `$BUILDDIR/documentation/README.html` 260* A doxygen documentation in `$BUILDDIR/documentation/html/index.html` 261 262Starting vsomeip Applications / Used environment variables 263---------------------------------------------------------- 264On startup the following environment variables are read out: 265 266* `VSOMEIP_APPLICATION_NAME`: This environment variable is used to specify the 267 name of the application. This name is later used to map a client id to the 268 application in the configuration file. It is independent from the 269 application's binary name. 270* `VSOMEIP_CONFIGURATION`: vsomeip uses the default configuration file `/etc/vsomeip.json` 271 and/or the default configuration folder `/etc/vsomeip`. This can be overridden by a 272 local configuration file `./vsomeip.json` and/or a local configuration folder `./vsomeip`. 273 If `VSOMEIP_CONFIGURATION` is set to a valid file or directory path, this is used instead 274 of the standard configuration (thus neither default nor local file/folder will be parsed). 275* `VSOMEIP_MANDATORY_CONFIGURATION_FILES`: vsomeip allows to specify mandatory configuration 276 files to speed-up application startup. While mandatory configuration files are read by all 277 applications, all other configuration files are only read by the application that is 278 responsible for connections to external devices. If this configuration variable is not set, 279 the default mandatory files vsomeip_std.json, vsomeip_app.json and vsomeip_plc.json are used. 280* `VSOMEIP_CLIENTSIDELOGGING`: Set this variable to an empty string to enable logging of 281 any received messages to DLT in all applications acting as routing manager proxies. For 282 example add the following line to the application's systemd service file: 283 `Environment=VSOMEIP_CLIENTSIDELOGGING=""` 284 To enable service-specific logs, provide a space- or colon-separated list of ServiceIDs (using 285 4-digit hexadecimal notation, optionally followed by dot-separted InstanceID). For example: 286 `Environment=VSOMEIP_CLIENTSIDELOGGING="b003.0001 f013.000a 1001 1002"` 287 `Environment=VSOMEIP_CLIENTSIDELOGGING="b003.0001:f013.000a:1001:1002"` 288 289NOTE: If the file/folder that is configured by `VSOMEIP_CONFIGURATION` does _not_ exist, 290the default configuration locations will be used. 291 292NOTE: vsomeip will parse and use the configuration from all files in a configuration folder 293but will _not_ consider directories within the configuration folder. 294 295In the following example the application `my_vsomeip_application` is started. 296The settings are read from the file `my_settings.json` in the current working 297directory. The client id for the application can be found under the name 298`my_vsomeip_client` in the configuration file. 299 300[source, bash] 301---- 302#!/bin/bash 303export VSOMEIP_APPLICATION_NAME=my_vsomeip_client 304export VSOMEIP_CONFIGURATION=my_settings.json 305./my_vsomeip_application 306---- 307 308Configuration File Structure 309---------------------------- 310The configuration files for vsomeip are http://www.json.org/[JSON]-Files and are 311composed out of multiple key value pairs and arrays. 312 313[quote, , json.org] 314____ 315* An object is an unordered set of name/value pairs. An object begins with `{ 316(left brace)` and ends with `} (right brace)`. Each name is followed by `: 317(colon)` and the name/value pairs are separated by `, (comma)`. 318 319* An array is an ordered collection of values. An array begins with `[ (left 320bracket)` and ends with `] (right bracket)`. Values are separated by `, 321(comma)`. 322 323* A value can be a _string_ in double quotes, or a _number_, or `true` or `false` 324or `null`, or an _object_ or an _array_. These structures can be nested. 325____ 326 327Configuration file element explanation: 328 329 330* 'unicast' 331+ 332The IP address of the host system. 333+ 334* 'netmask' 335+ 336The netmask to specify the subnet of the host system. 337+ 338* 'device' (optional) 339+ 340If specified, IP endpoints will be bound to this device. 341+ 342* 'diagnosis' 343+ 344The diagnosis address (byte) that will be used to build client identifiers. The 345diagnosis address is assigned to the most significant byte in all client 346identifiers if not specified otherwise (for example through a predefined client 347ID). 348+ 349* 'diagnosis_mask' 350+ 351The diagnosis mask (2 byte) is used to control the maximum amount of allowed 352concurrent vsomeip clients on an ECU and the start value of the client IDs. 353+ 354The default value is `0xFF00` meaning 355the most significant byte of the client ID is reserved for the diagnosis 356address and the client IDs will start with the diagnosis address as specified. 357The maximum number of clients is 255 as the Hamming weight of the inverted mask 358is 8 (2^8 = 256 - 1 (for the routing manager) = 255). The resulting client ID 359range with a diagnosis address of for example 0x45 would be 0x4501 to 0x45ff. 360+ 361Setting the mask to `0xFE00` doubles client ID range to 511 clients as the 362Hamming weight of the inverted mask is greater by one. With a diagnosis address 363of 0x45 the start value of client IDs is 0x4401 as bit 8 in 0x4500 is masked 364out. This then yields a client ID range of 0x4400 to 0x45ff. 365 366* 'network' 367+ 368Network identifier used to support multiple routing managers on one host. This 369setting changes the name of the shared memory segment in `/dev/shm` and the name 370of the unix domain sockets in `/tmp/`. Defaults to `vsomeip` meaning the shared 371memory will be named `/dev/shm/vsomeip` and the unix domain sockets will be 372named `/tmp/vsomeip-$CLIENTID` 373+ 374//Logging 375* 'logging' 376+ 377** 'level' 378+ 379Specifies the log level (valid values: _trace_, _debug_, _info_, _warning_, 380_error_, _fatal_). 381+ 382** 'console' 383+ 384Specifies whether logging via console is enabled (valid values: _true, false_). 385+ 386** 'file' 387+ 388*** 'enable' 389+ 390Specifies whether a log file should be created (valid values: _true, false_). 391+ 392*** 'path' 393+ 394The absolute path of the log file. 395+ 396** 'dlt' 397+ 398Specifies whether Diagnostic Log and Trace (DLT) is enabled (valid values: 399_true, false_). 400+ 401** 'version' 402+ 403Configures logging of the vsomeip version 404+ 405*** 'enable' 406+ 407Enable or disable cyclic logging of vsomeip version, defaults to true (valid 408values: _true, false_) 409+ 410*** 'interval' 411+ 412Configures interval in seconds to log the vsomeip version. Default value is 10. 413+ 414** 'memory_log_interval' 415+ 416Configures interval in seconds in which the routing manager logs its used 417memory. Setting a value greater than zero enables the logging. 418+ 419** 'status_log_interval' 420+ 421Configures interval in seconds in which the routing manager logs its internal 422status. Setting a value greater than zero enables the logging. 423+ 424//Tracing 425* anchor:config-tracing[]'tracing' (optional) 426+ 427** 'enable' 428+ 429Specifies whether the tracing of the SOME/IP messages is enabled 430(valid values: _true, false_). Default value is _false_. 431If tracing is enabled, the messages will be forwarded to DLT by 432the <<traceconnector, Trace Connector>> 433+ 434** 'sd_enable' 435+ 436Specifies whether the tracing of the SOME/IP service discovery messages is 437enabled (valid values: _true, false_). Default value is _false_. 438+ 439** 'channels (array)' (optional) 440+ 441Contains the channels to DLT. 442+ 443NOTE: You can set up multiple channels to DLT over that you can forward the 444messages. 445+ 446*** 'name' 447+ 448The name of the channel. 449+ 450*** 'id' 451+ 452The id of the channel. 453+ 454** 'filters (array)' (optional) 455+ 456Contains the filters that are applied on the messages. 457+ 458NOTE: You can apply filters respectively filter rules on the messages with 459specific criterias and expressions. So only the filtered messages are forwarded 460to DLT. 461+ 462*** 'channel' (optional) 463+ 464The id of the channel over that the filtered messages are forwarded to DLT. If 465no channel is specified the default channel (TC) is used. If you want to use a 466filter in several different channels, you can provide an array of channel ids. 467+ 468NOTE: If you use a positive filter with multiple channels, the same message 469will be forwared multiple times to DLT. 470+ 471*** 'matches' (optional) 472+ 473Specification of the criteria to include/exclude a message into/from the trace. 474You can either specify lists (array) or ranges of matching elements. 475+ 476A list may contain single identifiers which match all messages from/to all 477instances of the corresponding service or tuples consisting of service-, 478instance- and method-identifier. 'any' may be used as a wildcard for matching 479all services, instances or methods. 480+ 481A range is specified by two tuples "from" and "to", each consisting of 482service-, instance-and method-identifier. All messages with service-, 483instance-and method-identifiers that are greater than or equal to "from" 484and less than or equal to "to" are matched. 485+ 486*** 'type' (optional) 487+ 488Specifies the filter type (valid values: "positive", "negative"). When a positive 489filter is used and a message matches one of the filter rules, the message will be 490traced/forwarded to DLT. With a negative filter messages can be excluded. So when a 491message matches one of the filter rules, the message will not be traced/forwarded to 492DLT. Default value is "positive". 493+ 494//Applications 495* 'applications (array)' 496+ 497Contains the applications of the host system that use this config file. 498+ 499** 'name' 500+ 501The name of the application. 502+ 503** 'id' 504+ 505The id of the application. Usually its high byte is equal to the diagnosis address. In this 506case the low byte must be different from zero. Thus, if the diagnosis address is 0x63, valid 507values range from 0x6301 until 0x63FF. It is also possible to use id values with a high byte 508different from the diagnosis address. 509+ 510** 'max_dispatchers' (optional) 511+ 512The maximum number of threads that shall be used to execute the application callbacks. Default is 10. 513+ 514** 'max_dispatch_time' (optional) 515+ 516The maximum time in ms that an application callback may consume before the callback is 517considered to be blocked (and an additional thread is used to execute pending 518callbacks if max_dispatchers is configured greater than 0). The default value if not specified is 100ms. 519+ 520** 'threads' (optional) 521+ 522The number of internal threads to process messages and events within an application. 523Valid values are 1-255. Default is 2. 524+ 525** 'io_thread_nice' (optional) 526+ 527The nice level for internal threads processing messages and events. POSIX/Linux only. 528For actual values refer to nice() documentation. 529+ 530** 'request_debounce_time' (optional) 531+ 532Specifies a debounce-time interval in ms in which request-service messages are sent to 533the routing manager. If an application requests many services in short same time 534the load of sent messages to the routing manager and furthermore the replies from the 535routing manager (which contains the routing info for the requested service if available) 536can be heavily reduced. The default value if not specified is 10ms. 537+ 538** 'plugins' (optional array) 539+ 540Contains the plug-ins that should be loaded to extend the functionality of vsomeip. 541+ 542*** 'name' 543+ 544The name of the plug-in. 545+ 546*** 'type' 547+ 548The plug-in type (valid values: _application_plugin_). 549+ 550An application plug-in extends the functionality on application level. It gets informed 551by vsomeip over the basic application states (INIT/START/STOP) and can, based on these 552notifications, access the standard "application"-API via the runtime. 553+ 554** 'overlay' (optional) 555+ 556Contains the path to a configuration that overwrites specific configuration elements 557(unicast, netmask, device, network, diagnosis address & mask, service discovery) for the 558application. This allows to manage different network addresses from a single process. 559+ 560NOTE: This feature is only available if vsomeip was compiled with ENABLE_CONFIGURATION_OVERLAYS. 561+ 562* `services` (array) 563+ 564Contains the services of the service provider. 565 566** `service` 567+ 568The id of the service. 569 570** `instance` 571+ 572The id of the service instance. 573 574** `protocol` (optional) 575+ 576The protocol that is used to implement the service instance. The default setting 577is _someip_. If a different setting is provided, vsomeip does not open the specified 578port (server side) or does not connect to the specified port (client side). Thus, 579this option can be used to let the service discovery announce a service that is 580externally implemented. 581 582** `unicast` (optional) 583+ 584The unicast that hosts the service instance. 585+ 586NOTE: The unicast address is needed if external service instances shall be used, 587but service discovery is disabled. In this case, the provided unicast address 588is used to access the service instance. 589 590** `reliable` 591+ 592Specifies that the communication with the service is reliable respectively the 593TCP protocol is used for communication. 594 595*** `port` 596+ 597The port of the TCP endpoint. 598 599*** `enable-magic-cookies` 600+ 601Specifies whether magic cookies are enabled (valid values: _true_, _false_). 602 603** `unreliable` 604+ 605Specifies that the communication with the service is unreliable respectively the 606UDP protocol is used for communication (valid values: the _port_ of the UDP 607endpoint). 608 609** `events` (array) 610+ 611Contains the events of the service. 612 613*** `event` 614+ 615The id of the event. 616 617*** `is_field` 618+ 619Specifies whether the event is of type field. 620+ 621NOTE: A field is a combination of getter, setter and notification event. It 622contains at least a getter, a setter, or a notifier. The notifier sends an event 623message that transports the current value of a field on change. 624 625*** `is_reliable` 626+ 627Specifies whether the communication is reliable respectively whether the event 628is sent with the TCP protocol (valid values: _true_,_false_). 629+ 630If the value is _false_ the UDP protocol will be used. 631 632** `eventgroups` (array) 633+ 634Events can be grouped together into on event group. For a client it is thus 635possible to subscribe for an event group and to receive the appropriate events 636within the group. 637 638*** `eventgroup` 639+ 640The id of the event group. 641 642*** `events` (array) 643+ 644Contains the ids of the appropriate events. 645 646*** `multicast` 647+ 648Specifies the multicast that is used to publish the eventgroup. 649 650**** `address` 651+ 652The multicast address. 653 654**** `port` 655+ 656The multicast port. 657 658*** `threshold` 659+ 660Specifies when to use multicast and when to use unicast to send a notification event. 661Must be set to a non-negative number. If it is set to zero, all events of the eventgroup 662will be sent by unicast. Otherwise, the events will be sent by unicast as long as the 663number of subscribers is lower than the threshold and by multicast if the number 664of subscribers is greater or equal. This means, a threshold of 1 will lead to all events 665being sent by multicast. The default value is _0_. 666 667** `debounce-times` (object) 668+ 669Used to configure the nPDU feature. This is described in detail in 670<<npdu,vSomeIP nPDU feature>>. 671 672** `someip-tp` (object) 673+ 674Used to configure the SOME/IP-TP feature. There's an example available at 675<<someiptp, SOME/IP-TP>>. 676 677*** `service-to-client` (array) 678+ 679Contains the IDs for responses, fields and events which are sent from the node 680to a remote client which can be segmented via SOME/IP-TP if they exceed the 681maximum message size for UDP communication. If an ID isn't listed here the 682message will otherwise be dropped if the maximum message size is exceeded. 683 684*** `client-to-service` (array) 685+ 686Contains the IDs for requests, which are sent from the node 687to a remote service which can be segmented via SOME/IP-TP if they exceed the 688maximum message size for UDP communication. If an ID isn't listed here the 689message will otherwise be dropped if the maximum message size is exceeded. 690Please note that the unicast key has to be set to the remote IP address of the 691offering node for this setting to take effect. 692 693 694* `clients` (array) 695+ 696The client-side ports that shall be used to connect to a specific service. 697For each service, an array of ports to be used for reliable / unreliable 698communication can be specified. vsomeip will take the first free port of 699the list. If no free port can be found, the connection will fail. If 700vsomeip is asked to connect to a service instance without specified port(s), 701the port will be selected by the system. This implies that the user has 702to ensure that the ports configured here do not overlap with the ports 703automatically selected by the IP stack. 704 705** `service` 706** `instance` 707+ 708Together they specify the service instance the port configuration shall be applied to. 709 710** `reliable` (array) 711+ 712The list of client ports to be used for reliable (TCP) communication to the given 713service instance. 714 715** `unreliable` (array) 716+ 717The list of client ports to be used for unreliable (UDP) communication to the given 718service instance. 719 720+ 721Additionally there is the possibility to configure mappings between ranges of client 722ports and ranges of remote service ports. 723(If a client port is configured for a specific service / instance, the port range mapping is ignored) 724 725** `reliable_remote_ports` 726+ 727Specifies a range of reliable remote service ports 728 729** `unreliable_remote_ports` 730+ 731Specifies a range of unreliable remote service ports 732 733** `reliable_client_ports` 734+ 735Specifies the range of reliable client ports to be mapped to the reliable_remote_ports range 736 737** `unreliable_client_ports` 738+ 739Specifies the range of unreliable client ports to be mapped to the unreliable_remote_ports range 740 741 742** `first` 743+ 744Specifies the lower bound of a port range 745 746** `last` 747+ 748Specifies the upper bound of a port range 749 750* `payload-sizes` (array) 751+ 752Array to limit the maximum allowed payload sizes per IP and port. If not 753specified otherwise the allowed payload sizes are unlimited. The settings in 754this array only affect communication over TCP. To limit the local payload size 755`max-payload-size-local` can be used. 756 757** `unicast` 758+ 759On client side: the IP of the remote service for which the payload size should 760be limited. 761+ 762On service side: the IP of the offered service for which the payload size for 763receiving and sending should be limited. 764 765** `ports` (array) 766+ 767Array which holds pairs of port and payload size statements. 768 769*** `port` 770+ 771On client side: the port of the remote service for which the payload size should 772be limited. 773+ 774On service side: the port of the offered service for which the payload size for 775receiving and sending should be limited. 776 777*** `max-payload-size` 778+ 779On client side: the payload size limit in bytes of a message sent to the 780remote service hosted on beforehand specified IP and port. 781+ 782On service side: the payload size limit in bytes of messages received and sent 783by the service offered on previously specified IP and port. 784+ 785If multiple services are hosted on the same port they all share the limit 786specified. 787 788* `max-payload-size-local` 789+ 790The maximum allowed payload size for node internal communication in bytes. By 791default the payload size for node internal communication is unlimited. It can be 792limited via this setting. 793 794* `max-payload-size-reliable` 795+ 796The maximum allowed payload size for TCP communication in 797bytes. By default the payload size for TCP communication is 798unlimited. It can be limited via this setting. 799 800* `max-payload-size-unreliable` 801+ 802The maximum allowed payload size for UDP communication via SOME/IP-TP in 803bytes. By default the payload size for UDP via SOME/IP-TP communication is 804unlimited. It can be limited via this setting. This setting only applies for 805SOME/IP-TP enabled methods/events/fields (otherwise the UDP default of 1400 806bytes applies). See <<someiptp, SOME/IP-TP>> for an example configuration. 807 808* `endpoint-queue-limits` (array) 809+ 810Array to limit the maximum allowed size in bytes of cached outgoing messages per 811IP and port (message queue size per endpoint). If not specified otherwise the 812allowed queue size is unlimited. The settings in this array only affect external 813communication. To limit the local queue size `endpoint-queue-limit-local` can 814be used. 815 816** `unicast` 817+ 818On client side: the IP of the remote service for which the queue size of sent 819requests should be limited. 820+ 821On service side: the IP of the offered service for which the queue size for 822sent responses should be limited. This IP address is therefore 823identical to the IP address specified via `unicast` setting on top level of the 824json file. 825 826** `ports` (array) 827+ 828Array which holds pairs of port and queue size statements. 829 830*** `port` 831+ 832On client side: the port of the remote service for which the queue size of sent 833requests should be limited. 834+ 835On service side: the port of the offered service for which the queue size for 836send responses should be limited. 837 838*** `queue-size-limit` 839+ 840On client side: the queue size limit in bytes of messages sent to the 841remote service hosted on beforehand specified IP and port. 842+ 843On service side: the queue size limit in bytes for responses sent by the service 844offered on previously specified IP and port. 845+ 846If multiple services are hosted on the same port they all share the limit 847specified. 848 849* `endpoint-queue-limit-external` 850+ 851Setting to limit the maximum allowed size in bytes of cached outgoing messages 852for external communication (message queue size per endpoint). By default the 853queue size for external communication is unlimited. It can be limited via this 854setting. Settings done in the `endpoint-queue-limits` array override this 855setting. 856 857* `endpoint-queue-limit-local` 858+ 859Setting to limit the maximum allowed size in bytes of cached outgoing messages 860for local communication (message queue size per endpoint). By default the queue 861size for node internal communication is unlimited. It can be limited via this 862setting. 863 864* `buffer-shrink-threshold` 865+ 866The number of processed messages which are half the size or smaller than the 867allocated buffer used to process them before the memory for the buffer is 868released and starts to grow dynamically again. This setting can be useful in 869scenarios where only a small number of the overall messages are a lot bigger 870then the rest and the memory allocated to process them should be released in a 871timely manner. If the value is set to zero the buffer sizes aren't reseted and 872are as big as the biggest processed message. (default is 5) 873+ 874Example: `buffer-shrink-threshold` is set to 50. A message with 500 bytes has to 875be processed and the buffers grow accordingly. After this message 50 consecutive 876messages smaller than 250 bytes have to be processed before the buffer size is 877reduced and starts to grow dynamically again. 878 879* `tcp-restart-aborts-max` 880+ 881Setting to limit the number of TCP client endpoint restart aborts due to unfinished TCP handshake. 882After the limit is reached, a forced restart of the TCP client endpoint is done if the connection attempt is still pending. 883 884* `tcp-connect-time-max` 885+ 886Setting to define the maximum time until the TCP client endpoint connection attempt should be finished. 887If `tcp-connect-time-max` is elapsed, the TCP client endpoint is forcely restarted if the connection attempt is still pending. 888 889* `udp-receive-buffer-size` 890+ 891Specifies the size of the socket receive buffer (`SO_RCVBUF`) used for 892UDP client and server endpoints in bytes. (default: 1703936) 893 894* `internal_services` (optional array) 895+ 896Specifies service/instance ranges for pure internal service-instances. 897This information is used by vsomeip to avoid sending Find-Service messages 898via the Service-Discovery when a client is requesting a not available service- 899instance. Its can either be done on service/instance level or on service level 900only which then includes all instance from 0x0000-0xffff. 901 902** `first` 903+ 904The lowest entry of the internal service range. 905 906*** `service` 907+ 908The lowest Service-ID in hex of the internal service range. 909 910*** `instance` (optional) 911+ 912The lowest Instance-ID in hex of a internal service-instance range. 913If not specified the lowest Instance-ID is 0x0000. 914 915** `last` 916+ 917The highest entry of the internal service range. 918 919*** `service` 920+ 921The highest Service-ID in hex of a internal service range. 922 923*** `instance` (optional) 924+ 925The highest Instance-ID in hex of a internal service-instance range. 926If not specified the highest Instance-ID is 0xFFFF. 927 928* `debounce` (optional array) 929+ 930Events/fields sent by external devices will be forwarded to the 931applications only if a configurable function evaluates to true. The 932function checks whether the event/field payload has changed and whether 933a specified interval has been elapsed since the last forwarding. 934 935** `service` 936+ 937Service ID which hosts the events to be debounced. 938 939** `instance` 940+ 941Instance ID which hosts the events to be debounced. 942 943** `events` 944+ 945Array of events which shall be debounced based on the following 946configuration options. 947 948*** `event` 949+ 950Event ID. 951 952*** `on_change` 953+ 954Specifies whether the event is only forwared on 955paylaod change or not. (valid values: _true_, _false_). 956 957*** `ignore` 958+ 959Array of payload indexes with given bit mask (optional) 960to be ignored in payload change evaluation. 961Instead of specifying an index / bitmask pair, one can only define the paylaod index 962which shall be ignored in the evaluation. 963 964**** `index` 965+ 966Payload index to be checked with given bitmask. 967 968**** `mask` 969+ 9701Byte bitmask applied to byte at given payload index. 971Example mask: 0x0f ignores payload changes in low nibble of the byte at given index. 972 973*** `interval` 974+ 975Specifies if the event shall be debounced based on elapsed time interval. 976(valid values: _time in ms_, _never_). 977 978*** `on_change_resets_interval_` (optional) 979Specifies if interval timer is reset when payload change was detected. 980(valid values: _false_, _true_). 981 982* `routing` 983+ 984The name of the application that is responsible for the routing. 985 986* `routing-credentials` 987+ 988The UID / GID of the application acting as routing manager. 989(Must be specified if credentials checks are enabled using _check_credentials_ set to _true_ in order to successfully check the routing managers credentials passed on connect) 990 991** `uid` 992+ 993The routing managers UID. 994 995** `gid` 996+ 997The routing managers GID. 998 999* `shutdown_timeout` 1000+ 1001Configures the time in milliseconds local clients wait for acknowledgement of 1002their deregistration from the routing manager during shutdown. Defaults to 10035000ms. 1004 1005* `warn_fill_level` 1006+ 1007The routing manager regulary checks the fill level of the send buffers to its 1008clients. This variable defines the minimum fill level in percent that leads to 1009a warning being logged. Defaults to 67. 1010 1011* `service-discovery` 1012+ 1013Contains settings related to the Service Discovery of the host application. 1014 1015** `enable` 1016+ 1017Specifies whether the Service Discovery is enabled (valid values: _true_, 1018_false_). The default value is _true_. 1019 1020** `multicast` 1021+ 1022The multicast address which the messages of the Service Discovery will be sent 1023to. The default value is _224.0.0.1_. 1024 1025** `port` 1026+ 1027The port of the Service Discovery. The default setting is _30490_. 1028 1029** `protocol` 1030+ 1031The protocol that is used for sending the Service Discovery messages (valid 1032values: _tcp_, _udp_). The default setting is _udp_. 1033 1034** `initial_delay_min` 1035+ 1036Minimum delay before first offer message. 1037 1038** `initial_delay_max` 1039+ 1040Maximum delay before first offer message. 1041 1042** `repetitions_base_delay` 1043+ 1044Base delay sending offer messages within the repetition phase. 1045 1046** `repetitions_max` 1047+ 1048Maximum number of repetitions for provided services within the 1049repetition phase. 1050 1051** `ttl` 1052+ 1053Lifetime of entries for provided services as well as consumed services and eventgroups. 1054 1055** `ttl_factor_offers` (optional array) 1056+ 1057Array which holds correction factors for incoming remote offers. If a value 1058greater than one is specified for a service instance, the TTL field of the 1059corresponding service entry will be multiplied with the specified factor. + 1060Example: An offer of a service is received with a TTL of 3 sec and the TTL 1061factor is set to 5. The remote node stops offering the service w/o sending a 1062StopOffer message. The service will then expire (marked as unavailable) 15 seconds 1063after the last offer has been received. 1064 1065*** `service` 1066+ 1067The id of the service. 1068 1069*** `instance` 1070+ 1071The id of the service instance. 1072 1073*** `ttl_factor` 1074+ 1075TTL correction factor 1076 1077** `ttl_factor_subscriptions` (optional array) 1078+ 1079Array which holds correction factors for incoming remote subscriptions. If a 1080value greater than one is specified for a service instance, the TTL field of the 1081corresponding eventgroup entry will be multiplied with the specified factor. + 1082Example: A remote subscription to an offered service is received with a TTL of 3 1083sec and the TTL factor is set to 5. The remote node stops resubscribing to the 1084service w/o sending a StopSubscribeEventgroup message. The subscription will 1085then expire 15 seconds after the last resubscription has been received. 1086 1087*** `service` 1088+ 1089The id of the service. 1090 1091*** `instance` 1092+ 1093The id of the service instance. 1094 1095*** `ttl_factor` 1096+ 1097TTL correction factor 1098 1099** `cyclic_offer_delay` 1100+ 1101Cycle of the OfferService messages in the main phase. 1102 1103 1104** `request_response_delay` 1105+ 1106Minimum delay of a unicast message to a multicast message for 1107provided services and eventgroups. 1108+ 1109 1110** `offer_debounce_time` 1111+ 1112Time which the stack collects new service offers before they enter the 1113repetition phase. This can be used to reduce the number of 1114sent messages during startup. The default setting is _500ms_. 1115+ 1116 1117** `max_remote_subscribers` 1118+ 1119Limit the number of possible remote subscribers from same remote IP address 1120to an eventgroup provided by a service/instance if the remote subscriber uses 1121different ports for its subscriptions. The default setting is _3_. 1122+ 1123 1124//Watchdog 1125* anchor:config-watchdog[]`watchdog` (optional) 1126+ 1127The Watchdog sends periodically pings to all known local clients. 1128If a client isn't responding within a configurred time/amount of pongs 1129the watchdog deregisters this application/client. 1130If not configured the watchdog isn't activated. 1131+ 1132** `enable` 1133+ 1134Specifies whether the watchdog is enabled or disabled. 1135(valid values: _true, false_), (default is _false_). 1136+ 1137** `timeout` 1138+ 1139Specifies the timeout in ms the watchdog gets activated if a ping 1140isn't answered with a pong by a local client within that time. 1141(valid values: _2 - 2^32_), (default is _5000_ ms). 1142+ 1143** `allowed_missing_pongs` 1144+ 1145Specifies the amount of allowed missing pongs. 1146(valid values: _1 - 2^32_), (default is _3_ pongs). 1147+ 1148//CAPI-Selective Broadcasts support 1149* anchor:config-supports_selective_broadcasts[]`supports_selective_broadcasts` (optional array) 1150+ 1151This nodes allow to add a list of IP addresses on which CAPI-Selective-Broadcasts feature is supported. 1152If not specified the feature can't be used and the subscription behavior of the stack is same as with 1153normal events. 1154+ 1155** `address` 1156+ 1157Specifies an IP-Address (in IPv4 or IPv6 notation) on which the "selective"-feature is supported. 1158Multiple addresses can be configured. 1159 1160Security 1161-------- 1162vsomeip has a security implementation based on UNIX credentials. 1163If activated every local connection is authenticated during connect using the standard UNIX credential passing mechanism. 1164During authentication a client transfers its client identifier together with its credentials (UID / GID) to the server which is then matched against the configuration. 1165If received credentials don't match the policy the socket will be immediately closed by the server and an message is logged. 1166If accepted the client identifier is bound to the receiving socket and can therefore be used to do further security checks on incoming messages (vsomeip messages as well as internal commands). 1167 1168In general clients can be configured to be allowed/denied to request (means communicate with) and offer different service instances. 1169Every incoming vsomeip message (request/response/notification) as well as offer service requests or local subscriptions are then checked against the policy. 1170If an incoming vsomeip message or another operation (e.g. offer/subscribe) violates the configured policies it is skipped and a message is logged. 1171 1172Furthermore if an application receives informations about other clients/services in the system, it must be received from the authenticated routing manager. 1173This is to avoid malicious applications faking the routing manager and therefore being able to wrongly inform other clients about services running on the system. 1174Therefore, whenever the "security" tag is specified, the routing manager (e.g. routingmanagerd/vsomeipd) must be a configured application with a fixed client identifier. 1175See chapter "Configuration File Structure" on how to configure an application to use a specific client identifier. 1176 1177Credential passing is only possible via Unix-Domain-Sockets and therefore only available for local communication. 1178However if security is activated method calls from remote clients to local services are checked as well which means remote clients needs to be explicitly allowed. 1179Such a policy looks same in case for local clients except the _credentials_ tag can be skipped. 1180 1181Security configuration 1182~~~~~~~~~~~~~~~~~~~~~~ 1183The available configuration switches for the security feature are: 1184 1185// Security 1186* anchor:config-policy[]`security` (optional) 1187+ 1188If specified the credential passing mechanism is activated. However no credential or security checks are done as long as _check_credentials_ isn't set to _true_, but the routing manager client ID must be configured if security tag is specified and shall not be set to 0x6300. 1189If _check_credentials_ is set to _true_, the routing managers UID and GID needs to be specified using _routing-credentials_ tag. 1190 1191** `check_credentials` (optional) 1192+ 1193Specifies whether security checks are active or not. This includes credentials checks on connect as well as all policies checks configured in follow. 1194(valid values: _true, false_), (default is _false_). 1195 1196** `allow_remote_clients` (optional) 1197+ 1198Specifies whether incoming remote requests / subscriptions are allowed to be sent to a local proxy / client. 1199If not specified, all remote requests / subscriptions are allowed to be received by default. 1200(valid values are 'true' and 'false') 1201 1202** `policies` (array) 1203+ 1204Specifies the security policies. Each policy at least needs to specify _allow_ or _deny_. 1205 1206*** `credentials` 1207+ 1208Specifies the credentials for which a security policy will be applied. 1209If _check_credentials_ is set to _true_ the credentials of a local application needs to be specified correctly to ensure local socket authentication can succeed. 1210 1211**** `uid` 1212+ 1213Specifies the LINUX user id of the client application as decimal number. 1214As a wildcard "any" can be used. 1215 1216**** `gid` 1217+ 1218Specifies the LINUX group id of the client application as decimal number. 1219As a wildcard "any" can be used. 1220 1221**** `allow` / `deny` (optional) 1222+ 1223Specifies whether the LINUX user and group ids are allowed or denied for the policy. 1224 1225. `uid` (array) 1226+ 1227Specifies a list of LINUX user ids. These may either be specified as decimal numbers or as ranges. Ranges 1228are specified by the first and the last valid id (see example below). 1229 1230. `gid` (array) 1231+ 1232Specifies a list of LINUX group ids. These may either be specified as decimal numbers or as ranges. Ranges 1233are specified by the first and the last valid id (see example below). 1234 1235*** `allow` / `deny` 1236+ 1237This tag specifies either _allow_ or _deny_ depending on white- or blacklisting is needed. Specifing _allow_ and _deny_ entries in one policy is therefore not allowed. 1238With _allow_ a whitelisting of what is allowed can be done which means an empty _allow_ tag implies everything is denied. 1239With _deny_ a blacklisting of what is allowed can be done which means an empty _deny_ tag implies everything is allowed. 1240 1241**** `requests` (array) 1242+ 1243Specifies a set of service instance pairs which the above client application using the credentials above is allowed/denied to communicate with. 1244 1245. `service` 1246+ 1247Specifies a service for the _requests_. 1248 1249. `instance` (deprecated) 1250+ 1251Specifies a instance for the _requests_ 1252As a wildcard "any" can be used which means a range from instance ID 0x01 to 0xFFFF 1253which also implies a method ID range from 0x01 to 0xFFFF. 1254 1255. `instances` (array) 1256+ 1257Specifies a set of instance ID and method ID range pairs which are allowed/denied to communicate with. 1258If the `ids` tag below is not used to specify allowed/denied requests on method ID level one can also 1259only specify a a set of instance ID ranges which are allowed/denied to be requested analogous to the 1260allowed/denied `offers` section. 1261If no method IDs are specified, the allowed/denied methods are by default a range from 0x01 to 0xFFFF. 1262 1263.. `ids` 1264+ 1265Specifies a set of instance ID ranges which are allowed/denied to communicate with. 1266It is also possible to specify a single instance ID as array element without giving an upper / lower range bound. 1267As a wildcard "any" can be used which means a range from instance ID 0x01 to 0xFFFF. 1268+ 1269`first` - The lower bound of the instance range. 1270+ 1271`last` - The upper bound of the instance range. 1272 1273.. `methods` 1274+ 1275Specifies a set of method ID ranges which are allowed/denied to communicate with. 1276It is also possible to specify a single method ID as array element without giving an upper / lower range bound. 1277As a wildcard "any" can be used which means a range from method ID 0x01 to 0xFFFF. 1278+ 1279`first` - The lower bound of the method range. 1280+ 1281`last` - The upper bound of the method range. 1282 1283**** `offers` (array) 1284+ 1285Specifies a set of service instance pairs which are allowed/denied to be offered by the client application using the credentials above. 1286 1287. `service` 1288+ 1289Specifies a service for the _offers_. 1290 1291. `instance` (deprecated) 1292+ 1293Specifies a instance for the _offers_ 1294As a wildcard "any" can be used which means a range from instance ID 0x01 to 0xFFFF. 1295 1296. `instances` (array) 1297+ 1298Specifies a set of instance ID ranges which are allowed/denied to be offered by the client application using the credentials above. 1299It is also possible to specify a single instance ID as array element without giving an upper / lower range bound. 1300As a wildcard "any" can be used which means a range from instance ID 0x01 to 0xFFFF. 1301 1302.. `first` 1303+ 1304The lower bound of the instance range. 1305 1306.. `last` 1307+ 1308The upper bound of the instance range. 1309 1310<<< 1311 1312Security configuration example 1313~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1314[source, bash] 1315---- 1316... 1317"security" : 1318{ 1319 ... 1320 "policies" : 1321 [ 1322 { 1323 ... 1324 "credentials" : 1325 { 1326 "uid" : "44", 1327 "gid" : "any" 1328 }, 1329 "allow" : 1330 [ 1331 "requests" : 1332 [ 1333 { 1334 "service" : "0x6731", 1335 "instance" : "0x0001" 1336 } 1337 ] 1338 ] 1339 }, 1340 { 1341 "credentials" : 1342 { 1343 "deny" : 1344 [ 1345 { 1346 "uid" : [ "1000", { "first" : "1002", "last" : "max" }], 1347 "gid" : [ "0", { "first" : "100", "last" : "243" }, "300"] 1348 }, 1349 { 1350 "uid" : ["55"], 1351 "gid" : ["55"] 1352 } 1353 ] 1354 }, 1355 "allow" : 1356 [ 1357 "offers" : 1358 [ 1359 { 1360 "service" : "0x6728", 1361 "instances" : [ "0x0001", { "first" : "0x0003", "last" : "0x0007" }, "0x0009"] 1362 }, 1363 { 1364 "service" : "0x6729", 1365 "instances" : ["0x88"] 1366 }, 1367 { 1368 "service" : "0x6730", 1369 "instance" : "any" 1370 } 1371 ], 1372 "requests" : 1373 [ 1374 { 1375 "service" : "0x6732", 1376 "instances" : 1377 [ 1378 { 1379 "ids" : [ "0x0001", { "first" : "0x0003", "last" : "0x0007" }], 1380 "methods" : [ "0x0001", "0x0003", { "first" : "0x8001", "last" : "0x8006" } ] 1381 }, 1382 { 1383 "ids" : [ "0x0009" ], 1384 "methods" : "any" 1385 } 1386 ] 1387 }, 1388 { 1389 "service" : "0x6733", 1390 "instance" : "0x1" 1391 }, 1392 { 1393 "service" : "0x6733", 1394 "instances" : [ "0x0002", { "first" : "0x0003", "last" : "0x0007" }, "0x0009"] 1395 } 1396 ] 1397 ] 1398 } 1399 ] 1400} 1401---- 1402 1403The config/ folder contains some addition vsomeip configuration files to run the vsomeip 1404examples with activated security checks. 1405Additionally there's a security test in the `test/` subfolder which can be used 1406for further reference. + 1407They give a basic overview how to use the security related configuration tags described 1408in this chapter to run a simple request/response or subscribe/notify example locally or 1409remotely. 1410 1411Audit Mode 1412~~~~~~~~~~ 1413vsomeip's security implementation can be put in a so called 'Audit Mode' where 1414all security violations will be logged but allowed. This mode can be used to 1415build a security configuration. 1416 1417To activate the 'Audit Mode' the 'security' object has to be included in the 1418json file but the 'check_credentials' switch has to be set to false. For 1419example: 1420 1421[source, bash] 1422---- 1423 [...] 1424 "services" : 1425 [ 1426 [...] 1427 ], 1428 "security" : 1429 { 1430 "check_credentials" : "false" 1431 }, 1432 "routing" : "service-sample", 1433 [...] 1434---- 1435 1436Autoconfiguration 1437----------------- 1438vsomeip supports the automatic configuration of client identifiers and the routing. 1439The first application that starts using vsomeip will automatically become the 1440routing manager if it is _not_ explicitly configured. The client identifiers 1441are generated from the diagnosis address that can be specified by defining 1442DIAGNOSIS_ADDRESS when compiling vsomeip. vsomeip will use the diagnosis address 1443as the high byte and enumerate the connecting applications within the low byte 1444of the client identifier. 1445 1446Autoconfiguration of client identifiers isn't meant to be used together with vsomeip Security. 1447Every client running locally needs to have at least its own credentials configured when security is activated to ensure the credential checks can pass. 1448Practically that means if a client requests its identifier over the autoconfiguration for which no credentials are configured (at least it isn't known which client identifier is used beforehand) it is impossible for that client to establish a connection to a server endpoint. 1449However if the credentials for all clients are same it's possible to configure them for the overall (or DIAGNOSIS_ADDRESS) client identifier range to mix autoconfiguration together with activated security. 1450 1451routingmanagerd 1452--------------- 1453The routingmanagerd is a minimal vsomeip application intended to offer routing 1454manager functionality on a node where one system wide configuration file is 1455present. It can be found in the examples folder. 1456 1457Example: Starting the daemon on a system where the system wide configuration is 1458stored under `/etc/vsomeip.json`: 1459[source, bash] 1460---- 1461VSOMEIP_CONFIGURATION=/etc/vsomeip.json ./routingmanagerd 1462---- 1463 1464When using the daemon it should be ensured that: 1465 1466* In the system wide configuration file the routingmanagerd is defined as 1467 routing manager, meaning it contains the line `"routing" : "routingmanagerd"`. 1468 If the default name is overridden the entry has to be adapted accordingly. 1469 The system wide configuration file should contain the information about all 1470 other offered services on the system as well. 1471* There's no other vsomeip configuration file used on the system which contains 1472 a `"routing"` entry. As there can only be one routing manager per system. 1473 1474 1475vsomeip Hello World 1476------------------- 1477In this paragraph a Hello World program consisting out of a client and a service 1478is developed. The client sends a message containing a string to the service. 1479The service appends the received string to the string `Hello` and sends it back 1480to the client. 1481Upon receiving a response from the service the client prints the payload of the 1482response ("Hello World"). 1483This example is intended to be run on the same host. 1484 1485All files listed here are contained in the `examples\hello_world` subdirectory. 1486 1487Build instructions 1488~~~~~~~~~~~~~~~~~~ 1489The example can build with its own CMakeFile, please compile the vsomeip stack 1490before hand as described in <<Compilation>>. Then compile the example starting 1491from the repository root directory as followed: 1492[source, bash] 1493---- 1494cd examples/hello_world 1495mkdir build 1496cd build 1497cmake .. 1498make 1499---- 1500 1501Starting and expected output 1502~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1503 1504Starting and expected output of service 1505^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1506[source, bash] 1507---- 1508$ VSOMEIP_CONFIGURATION=../helloworld-local.json \ 1509 VSOMEIP_APPLICATION_NAME=hello_world_service \ 1510 ./hello_world_service 15112015-04-01 11:31:13.248437 [info] Using configuration file: ../helloworld-local.json 15122015-04-01 11:31:13.248766 [debug] Routing endpoint at /tmp/vsomeip-0 15132015-04-01 11:31:13.248913 [info] Service Discovery disabled. Using static routing information. 15142015-04-01 11:31:13.248979 [debug] Application(hello_world_service, 4444) is initialized. 15152015-04-01 11:31:22.705010 [debug] Application/Client 5555 got registered! 1516---- 1517 1518Starting and expected output of client 1519^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1520[source, bash] 1521---- 1522$ VSOMEIP_CONFIGURATION=../helloworld-local.json \ 1523 VSOMEIP_APPLICATION_NAME=hello_world_client \ 1524 ./hello_world_client 15252015-04-01 11:31:22.704166 [info] Using configuration file: ../helloworld-local.json 15262015-04-01 11:31:22.704417 [debug] Connecting to [0] at /tmp/vsomeip-0 15272015-04-01 11:31:22.704630 [debug] Listening at /tmp/vsomeip-5555 15282015-04-01 11:31:22.704680 [debug] Application(hello_world_client, 5555) is initialized. 1529Sending: World 1530Received: Hello World 1531---- 1532 1533CMakeFile 1534~~~~~~~~~ 1535 1536[source, bash] 1537---- 1538include::../examples/hello_world/CMakeLists.txt[] 1539---- 1540 1541Configuration File For Client and Service 1542~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~ 1543 1544[source, bash] 1545---- 1546include::../examples/hello_world/helloworld-local.json[] 1547---- 1548 1549Service 1550~~~~~~~ 1551 1552[source, bash] 1553---- 1554include::../examples/hello_world/hello_world_service.cpp[] 1555---- 1556 1557The service example results in the following program execution: 1558 1559:numbered!: 1560 1561[float] 1562 1563Main 1564^^^^^ 1565 1566. __main()__ 1567+ 1568First the application is initialized. After the initialization is 1569finished the application is started. 1570 1571[float] 1572Initialization 1573^^^^^^^^^^^^^^ 1574 1575[start=2] 1576. __init()__ 1577+ 1578The initialization contains the registration of a message 1579handler and an event handler. 1580+ 1581The message handler declares a callback (__on_message_cbk__) for messages that 1582are sent to the specific service (specifying the service id, the service 1583instance id and the service method id). 1584+ 1585The event handler declares a callback (__on_event_cbk__) for events that occur. 1586One event can be the successful registration of the application at the runtime. 1587 1588[float] 1589Start 1590^^^^^ 1591 1592[start=3] 1593. __start()__ 1594+ 1595The application will be started. This function only returns when the application 1596will be stopped. 1597 1598[float] 1599Callbacks 1600^^^^^^^^^ 1601 1602[start=4] 1603. __on_state_cbk()__ 1604+ 1605This function is called by the application when an state change occurred. If 1606the application was successfully registered at the runtime then the specific 1607service is offered. 1608 1609. __on_message_cbk()__ 1610+ 1611This function is called when a message/request from a client for the specified 1612service was received. 1613+ 1614First a response based upon the request is created. 1615Afterwards the string 'Hello' will be concatenated with the payload of the 1616client's request. 1617After that the payload of the response is created. The payload data is set with 1618the previously concatenated string. 1619Finally the response is sent back to the client and the application is stopped. 1620 1621[float] 1622Stop 1623^^^^ 1624 1625[start=6] 1626. __stop()__ 1627+ 1628This function stops offering the service, unregister the message and the event 1629handler and shuts down the application. 1630 1631:numbered: 1632 1633Client 1634~~~~~~ 1635[source, bash] 1636---- 1637include::../examples/hello_world/hello_world_client.cpp[] 1638---- 1639 1640The client example results in the following program execution: 1641 1642:numbered!: 1643 1644[float] 1645Main 1646^^^^^ 1647 1648. __main()__ 1649+ 1650First the application is initialized. After the initialization is finished the 1651application is started. 1652 1653[float] 1654Initialization 1655^^^^^^^^^^^^^^ 1656 1657[start=2] 1658. __init()__ 1659+ 1660The initialization contains the registration of a message handler, an event 1661handler and an availability handler. 1662+ 1663The event handler declares again a callback (__on_state_cbk__) for state changes 1664that occur. 1665+ 1666The message handler declares a callback (__on_message_cbk__) for messages that 1667are received from any service, any service instance and any method. 1668+ 1669The availability handler declares a callback (__on_availability_cbk__) which is 1670called when the specific service is available (specifying the service id and the 1671service instance id). 1672 1673[float] 1674Start 1675^^^^^ 1676 1677[start=3] 1678. __start()__ 1679+ 1680The application will be started. This function only returns when the application 1681will be stopped. 1682 1683[float] 1684Callbacks 1685^^^^^^^^^ 1686 1687[start=4] 1688. __on_state_cbk()__ 1689+ 1690 1691This function is called by the application when an state change occurred. If the 1692application was successfully registered at the runtime then the specific service 1693is requested. 1694 1695. __on_availability_cbk()__ 1696+ 1697This function is called when the requested service is available or no longer 1698available. 1699+ 1700First there is a check if the change of the availability is related to the 1701'hello world service' and the availability changed to true. 1702If the check is successful a service request is created and the appropriate 1703service information are set (service id, service instance id, service method 1704id). 1705After that the payload of the request is created. The data of the payload is 1706'World' and will be set afterwards. 1707Finally the request is sent to the service. 1708 1709. __on_message_cbk()__ 1710+ 1711This function is called when a message/response was received. 1712If the response is from the requested service, of type 'RESPONSE' and the return 1713code is 'OK' then the payload of the response is printed. Finally the 1714application is stopped. 1715 1716[float] 1717Stop 1718^^^^ 1719 1720[start=7] 1721. __stop()__ 1722+ 1723This function unregister the event and the message handler and shuts down the 1724application. 1725 1726:numbered: 1727 1728Trace Connector 1729--------------- 1730anchor:traceconnector[] 1731 1732Overview/Prerequisites 1733~~~~~~~~~~~~~~~~~~~~~~ 1734 1735The Trace Connector is used to forward the internal messages that are sent over 1736the Unix Domain Sockets to DLT. + 1737Thus, it requires that DLT is installed and the DLT module can be found in the 1738context of CMake. 1739 1740Configuration 1741~~~~~~~~~~~~~ 1742 1743Static Configuration 1744^^^^^^^^^^^^^^^^^^^^ 1745 1746The Trace Connector can be configured statically over the 1747<<config-tracing,JSON configuration file>>. + 1748 1749[float] 1750Example 1 (Minimal Configuration) 1751^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1752 1753[source, bash] 1754---- 1755{ 1756 ... 1757 1758 "tracing" : 1759 { 1760 "enable" : "true" 1761 }, 1762 1763 ... 1764---- 1765 1766This is the minimal configuration of the Trace Connector. This just enables the 1767tracing and all of the sent internal messages will be traced/forwarded to DLT. 1768 1769[float] 1770Example 2 (Using Filters) 1771^^^^^^^^^^^^^^^^^^^^^^^^^ 1772 1773[source, bash] 1774---- 1775{ 1776 ... 1777 1778 "tracing" : 1779 { 1780 "enable" : "true", 1781 "channels" : 1782 [ 1783 { 1784 "name" : "My channel", 1785 "id" : "MC" 1786 } 1787 ], 1788 "filters" : [ 1789 { 1790 "channel" : "MC", 1791 "matches" : [ { "service" : "0x1234", "instance" : "any", "method" : "0x80e8" } ], 1792 "type" : "positive" 1793 } 1794 ] 1795 }, 1796 1797 ... 1798---- 1799 1800As it is a positive filter, the example filter ensures that only messages 1801representing method '0x80e8' from instances of service '0x1234' will be 1802forwarded to the DLT. If it was specified as a negative filter, all messages 1803except messages representing method '0x80e8' from instances of service 1804'0x1234' would be forwarded to the DLT. 1805 1806The general filter rules are: 1807 1808* The default filter is a positive filter for all messages. 1809* The default filter is active on a channel as long as no other positive 1810filter is specified. 1811* Negative filters block matching messages. Negative filters overrule 1812positive filters. Thus, as soon as a messages matches a negative filter it 1813will not be forwarded. 1814* The identifier '0xffff' is a wildcard that matches any service, instance or method. 1815The keyword 'any' can be used as a replacement for '0xffff'. 1816* Wildcards must not be used within range filters. 1817 1818Dynamic Configuration 1819^^^^^^^^^^^^^^^^^^^^^ 1820 1821The Trace Connector can also be configured dynamically over its interfaces. 1822You need to include '<vsomeip/trace.hpp>' to access its public interface. 1823 1824[float] 1825Example: 1826^^^^^^^^ 1827 1828[source, bash] 1829---- 1830 // get trace connector 1831 std::shared_ptr<vsomeip::trace::connector> its_connector 1832 = vsomeip::trace::connector::get(); 1833 1834 // add channel 1835 std::shared_ptr<vsomeip::trace::channel> its_channel 1836 = its_connector->create_channel("MC", "My channel"); 1837 1838 // add filter rule 1839 vsomeip::trace::match_t its_match 1840 = std::make_tuple(0x1234, 0xffff, 0x80e8); 1841 vsomeip::trace::filter_id_t its_filter_id 1842 = its_channel->add_filter(its_match, true); 1843 1844 // init trace connector 1845 its_connector->init(); 1846 1847 // enable trace connector 1848 its_connector->set_enabled(true); 1849 1850 // remove the filter 1851 its_channel->remove_filter(its_filter_id); 1852---- 1853 1854anchor:npdu[] 1855 1856vsomeip nPDU feature 1857------------------ 1858 1859This is the add-on documentation for the nPDU feature, aka. _Zugverfahren_. 1860 1861The nPDU feature can be used to reduce network load as it enables the vsomeip 1862stack to combine multiple vsomeip messages in one single ethernet frame. 1863 1864Some general _important_ things regarding the nPDU feature first: 1865 1866* Due to its nature the nPDU feature trades lower network load for speed. 1867* As the nPDU feature requires some settings which are not transmitted 1868through the service discovery, it's *not* sufficient anymore to have an json 1869file without a "services" section on the client side. 1870* As the client- and server-endpoints of a node are managed by the routing 1871 manager (which is the application entered at "routing" in the json file) 1872 the nPDU feature settings *always* have to be defined in the json file used by 1873 the application acting as routing manager. 1874* The nPDU feature timings are defined in milliseconds. 1875* Node internal communication over UNIX domain sockets is not affected by the 1876 nPDU feature. 1877* If the debounce times configuration for a method in the json file is missing 1878 or incomplete the default values are used: 2ms debounce time and 5ms max 1879 retention time. The global default values can be overwritten via the 1880 `npdu-default-timings` json object. 1881 1882Configuration 1883~~~~~~~~~~~~~ 1884There are two parameters specific for the nPDU feature: 1885 1886* *debounce time*: minimal time between sending a message to the same method of 1887 a remote service over the same connection (src/dst address + src/dst port). 1888* *max retention time*: the maximum time which a message to the same method of a 1889 remote service over the same connection (src/dst address + src/dst port) is 1890 allowed to be buffered on sender side. 1891 1892For more information please see the corresponding requirement documents. 1893 1894 1895The nPDU feature specific settings are configured in the json file in the 1896"services" section on service level in a special _debounce-times_ section: 1897 1898[source, bash] 1899---- 1900[...] 1901"services": 1902[ 1903 { 1904 "service":"0x1000", 1905 "instance":"0x0001", 1906 "unreliable":"30509", 1907 "debounce-times": 1908 { 1909 // nPDU feature configuration for this 1910 // service here 1911 } 1912 } 1913], 1914[...] 1915---- 1916 1917Additionally nPDU default timings can be configured globally. 1918 1919The global default timings can be overwritten via the `npdu-default-timings` 1920json object. For example the following configuration snippet shows how to set 1921all default timings to zero: 1922 1923[source, bash] 1924---- 1925{ 1926 "unicast":"192.168.1.9", 1927 [...] 1928 "npdu-default-timings" : { 1929 "debounce-time-request" : "0", 1930 "debounce-time-response" : "0", 1931 "max-retention-time-request" : "0", 1932 "max-retention-time-response" : "0" 1933 }, 1934 "routing":"[...]", 1935 "service-discovery": { [...] } 1936} 1937---- 1938 1939 1940Example 1: One service with one method offered over UDP 1941^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 1942 1943* The service is hosted on IP: 192.168.1.9. 1944* The service is offered on port 30509 via UDP. 1945* The service has the ID 0x1000 1946* The method has the ID 0x0001 1947* The client accesses the service from IP: 192.168.1.77 1948 1949Service side 1950++++++++++++ 1951 1952* Debounce time for responses should have a: 1953** debounce time of 10 milliseconds 1954** maximum retention time of 100 milliseconds 1955 1956[source, bash] 1957---- 1958{ 1959 "unicast":"192.168.1.9", 1960 "logging": { [...] }, 1961 "applications": [ [...] ], 1962 "services": 1963 [ 1964 { 1965 "service":"0x1000", 1966 "instance":"0x0001", 1967 "unreliable":"30509", 1968 "debounce-times": 1969 { 1970 "responses": { 1971 "0x1001" : { 1972 "debounce-time":"10", 1973 "maximum-retention-time":"100" 1974 } 1975 } 1976 } 1977 } 1978 ], 1979 "routing":"[...]", 1980 "service-discovery": { [...] } 1981} 1982---- 1983Client side 1984++++++++++++ 1985 1986* Debounce time for requests to the service on 192.168.1.9 should have a: 1987** debounce time of 20 milliseconds 1988** maximum retention time of 200 milliseconds 1989 1990[source, bash] 1991---- 1992{ 1993 "unicast":"192.168.1.77", 1994 "logging": { [...] }, 1995 "applications": [ [...] ], 1996 "services": 1997 [ 1998 { 1999 "service":"0x1000", 2000 "instance":"0x0001", 2001 "unicast":"192.168.1.9", // required to mark service as external 2002 "unreliable":"30509", 2003 "debounce-times": 2004 { 2005 "requests": { 2006 "0x1001" : { 2007 "debounce-time":"20", 2008 "maximum-retention-time":"200" 2009 } 2010 } 2011 } 2012 } 2013 ], 2014 "routing":"[...]", 2015 "service-discovery": { [...] } 2016} 2017---- 2018 2019Example 2: One service with two methods offered over UDP 2020^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2021 2022* The service is hosted on IP: 192.168.1.9. 2023* The service is offered on port 30509 via UDP. 2024* The service has the ID 0x1000 2025* The method has the ID 0x0001 2026* The second method has the ID 0x0002 2027* The client accesses the service from IP: 192.168.1.77 2028 2029Service side 2030++++++++++++ 2031 2032* Debounce time for responses should have a: 2033** debounce time of 10 milliseconds for method 0x1001 and 20 for 0x1002 2034** maximum retention time of 100 milliseconds for method 0x1001 and 200 for 0x1002 2035 2036[source, bash] 2037---- 2038{ 2039 "unicast":"192.168.1.9", 2040 "logging": { [...] }, 2041 "applications": [ [...] ], 2042 "services": 2043 [ 2044 { 2045 "service":"0x1000", 2046 "instance":"0x0001", 2047 "unreliable":"30509", 2048 "debounce-times": 2049 { 2050 "responses": { 2051 "0x1001" : { 2052 "debounce-time":"10", 2053 "maximum-retention-time":"100" 2054 }, 2055 "0x1002" : { 2056 "debounce-time":"20", 2057 "maximum-retention-time":"200" 2058 } 2059 } 2060 } 2061 } 2062 ], 2063 "routing":"[...]", 2064 "service-discovery": { [...] } 2065} 2066---- 2067Client side 2068++++++++++++ 2069 2070* Debounce time for requests to the service on 192.168.1.9 should have a: 2071** debounce time of 20 milliseconds for method 0x1001 and 40 for 0x1002 2072** maximum retention time of 200 milliseconds for method 0x1001 and 400 for 0x1002 2073 2074[source, bash] 2075---- 2076{ 2077 "unicast":"192.168.1.77", 2078 "logging": { [...] }, 2079 "applications": [ [...] ], 2080 "services": 2081 [ 2082 { 2083 "service":"0x1000", 2084 "instance":"0x0001", 2085 "unicast":"192.168.1.9", // required to mark service as external 2086 "unreliable":"30509", 2087 "debounce-times": 2088 { 2089 "requests": { 2090 "0x1001" : { 2091 "debounce-time":"20", 2092 "maximum-retention-time":"200" 2093 }, 2094 "0x1002" : { 2095 "debounce-time":"40", 2096 "maximum-retention-time":"400" 2097 } 2098 } 2099 } 2100 } 2101 ], 2102 "routing":"[...]", 2103 "service-discovery": { [...] } 2104} 2105---- 2106 2107Example 3: One service with one method offered over UDP and TCP 2108^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ 2109 2110* The service is hosted on IP: 192.168.1.9. 2111* The service is offered on port 30509 via UDP. 2112* The service is offered on port 30510 via TCP. 2113* The service has the ID 0x1000 2114* The method has the ID 0x0001 2115* The client accesses the service from IP: 192.168.1.77 2116 2117Service side 2118++++++++++++ 2119 2120* Debounce time for responses should have a: 2121** debounce time of 10 milliseconds 2122** maximum retention time of 100 milliseconds 2123** TCP should use the same settings as UDP 2124 2125[source, bash] 2126---- 2127{ 2128 "unicast":"192.168.1.9", 2129 "logging": { [...] }, 2130 "applications": [ [...] ], 2131 "services": 2132 [ 2133 { 2134 "service":"0x1000", 2135 "instance":"0x0001", 2136 "unreliable":"30509", 2137 "reliable": 2138 { 2139 "port":"30510", 2140 "enable-magic-cookies":"false" 2141 }, 2142 "debounce-times": 2143 { 2144 "responses": { 2145 "0x1001" : { 2146 "debounce-time":"10", 2147 "maximum-retention-time":"100", 2148 } 2149 } 2150 } 2151 } 2152 ], 2153 "routing":"[...]", 2154 "service-discovery": { [...] } 2155} 2156---- 2157Client side 2158++++++++++++ 2159 2160* Debounce time for requests to the service on 192.168.1.9 should have a: 2161** debounce time of 20 milliseconds 2162** maximum retention time of 200 milliseconds 2163** TCP should use the same settings as UDP 2164 2165[source, bash] 2166---- 2167{ 2168 "unicast":"192.168.1.77", 2169 "logging": { [...] }, 2170 "applications": [ [...] ], 2171 "services": 2172 [ 2173 { 2174 "service":"0x1000", 2175 "instance":"0x0001", 2176 "unicast":"192.168.1.9", // required to mark service as external 2177 "unreliable":"30509", 2178 "reliable": 2179 { 2180 "port":"30510", 2181 "enable-magic-cookies":"false" 2182 }, 2183 "debounce-times": 2184 { 2185 "requests": { 2186 "0x1001" : { 2187 "debounce-time":"20", 2188 "maximum-retention-time":"200", 2189 } 2190 } 2191 } 2192 } 2193 ], 2194 "routing":"[...]", 2195 "service-discovery": { [...] } 2196} 2197---- 2198 2199 2200anchor:someiptp[] 2201 2202SOME/IP TP 2203---------- 2204With SOME/IP Transport Protocol (TP) it is possible to transport messages which 2205exceed the UDP payload size limit of 1400 byte. If enabled the message is 2206segmented and send in multiple UDP datagrams. 2207 2208Example configuration: 2209 2210* Service 0x1111/0x1 is hosted on 192.168.0.1 on UDP port 40000 2211* Client is running on 192.168.0.100 2212* The service has two methods with ID: 0x1 and 0x2 which require large requests 2213 and large responses. Additionally the service offers a field with ID 0x8001 2214 which requires a large payloads as well. 2215* The maximum payload size on service side should be limited to 5000 bytes. 2216 2217Configuration service side: 2218[source, bash] 2219---- 2220{ 2221 "unicast":"192.168.0.1", 2222 "logging": { [...] }, 2223 "applications": [ [...] ], 2224 "services": 2225 [ 2226 { 2227 "service":"0x1000", 2228 "instance":"0x1", 2229 "unreliable":"40000", 2230 "someip-tp": { 2231 "service-to-client": [ 2232 "0x1", "0x2", "0x8001" 2233 ] 2234 } 2235 } 2236 ], 2237 "max-payload-size-unreliable" : "5000", 2238 "routing":"[...]", 2239 "service-discovery": { [...] } 2240} 2241---- 2242 2243Configuration client side: 2244 2245[source, bash] 2246---- 2247{ 2248 "unicast":"192.168.0.100", 2249 "logging": { [...] }, 2250 "applications": [ [...] ], 2251 "services": 2252 [ 2253 { 2254 "service":"0x1000", 2255 "instance":"0x1", 2256 "unicast":"192.168.0.1", // required to mark service as external 2257 "unreliable":"40000", // required to mark service as external 2258 "someip-tp": { 2259 "client-to-service": [ 2260 "0x1", "0x2" 2261 ] 2262 } 2263 } 2264 ], 2265 "routing":"[...]", 2266 "service-discovery": { [...] } 2267} 2268---- 2269 2270Tools 2271----- 2272 2273vsomeip_ctrl 2274~~~~~~~~~~~~ 2275anchor:vsomeip_ctrl[] 2276`vsomeip_ctrl` is a small utility which can be used to send SOME/IP messages 2277from the commandline. If a response arrives within 5 seconds the response will 2278be printed. 2279 2280* It can be build via `vsomeip_ctrl` make target (`make vsomeip_ctrl`). 2281* The instance id of the target service has to be passed in hexadecimal 2282 notation. 2283* The complete message has to be passed in hexadecimal notation. 2284* See the `--help` parameter for available options. 2285* If `vsomeip_ctrl` is used to send messages to a remote service and no 2286 `routingmanagerd` is running on the local machine, make sure to pass a json 2287 configuration file where `vsomeip_ctrl` is set as routing manager via 2288 environment variable. 2289* If `vsomeip_ctrl` is used to send messages to a local service and no 2290 `routingmanagerd` is running on the local machine, make sure to use the same json 2291 configuration file as the local service. 2292 2293Example: Calling method with method id 0x80e8 on service with service id 0x1234, 2294instance id 0x5678: 2295[source, bash] 2296---- 2297./vsomeip_ctrl --instance 5678 --message 123480e800000015134300030100000000000009efbbbf576f726c6400 2298---- 2299 2300Example: Sending a message to service with service id 0x1234, instance id 23010x5678 and method id 0x0bb8 via TCP 2302[source, bash] 2303---- 2304./vsomeip_ctrl --tcp --instance 5678 --message 12340bb8000000081344000101010000 2305---- 2306