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