path: root/README

vsomeip
=======
// This enables a nice TOC as a sidebar
:toc2:
// Show all headings in TOC
:toclevels: 4
// Show icons if e.g. TIP: or IMPORTANT is used
:icons:
// Set the directory where the default icons can be found
:iconsdir: {asciidoc-confdir}/{iconsdir}
// number all headings
:numbered:
// this embeds images (e.g. the icons for TIP: $TEXT) into the html file
:data-uri:

Copyright
+++++++++
Copyright (C) 2015, Bayerische Motoren Werke Aktiengesellschaft (BMW AG)

License
+++++++
This Source Code Form is subject to the terms of the Mozilla Public
License, v. 2.0. If a copy of the MPL was not distributed with this
file, You can obtain one at http://mozilla.org/MPL/2.0/.

Version
+++++++
// set the version to the one we get from cmake
// or pass it via -a version=$VSOMEIP_VERSION to asciidoc
This documentation was generated for version {version} of vsomeip.

vsomeip Overview
----------------
The vsomeip stack implements the http://some-ip.com/[Scalable service-Oriented
MiddlewarE over IP (SOME/IP)] protocol. The stack consists out of:

* a shared library for SOME/IP (`libvsomeip.so`)
* a second shared library for SOME/IP's service discovery (`libvsomeip-sd.so`)
  which is loaded during runtime if the service discovery is enabled.

Build Instructions
------------------
Dependencies
~~~~~~~~~~~~
* A C++11 enabled compiler like gcc >= 4.8 is needed.
* vsomeip uses cmake as buildsystem.
* vsomeip uses Boost >= 1.54:
** Ubuntu 14.04:
*** `sudo apt-get install libboost-system1.54-dev libboost-thread1.54-dev
    libboost-log1.54-dev`
** Ubuntu 12.04: a PPA is necessary to use version 1.54 of Boost:
*** URL: https://launchpad.net/~boost-latest/+archive/ubuntu/ppa
*** `sudo add-apt-repository ppa:boost-latest/ppa`
*** `sudo apt-get install libboost-system1.54-dev libboost-thread1.54-dev
    libboost-log1.54-dev`
* For the tests Google's test framework
  https://code.google.com/p/googletest/[gtest] in version 1.7.0 is needed
** URL: https://googletest.googlecode.com/files/gtest-1.7.0.zip[direct link,
   version 1.7.0]
* To build the documentation asciidoc, source-highlight, doxygen and graphviz is needed:
** `sudo apt-get install asciidoc source-highlight doxygen graphviz`

Compilation
~~~~~~~~~~~
anchor:Compilation[]
For compilation call:
[source, bash]
----
mkdir build
cd build
cmake ..
make
----

To specify a installation directory (like `--prefix=` if you're used to
autotools) call cmake like:
[source, bash]
----
cmake -DCMAKE_INSTALL_PREFIX:PATH=$YOUR_PATH ..
make
make install
----

Compilation of examples
^^^^^^^^^^^^^^^^^^^^^^^
For compilation of the examples call:
[source, bash]
----
mkdir build
cd build
cmake ..
make examples
----

Compilation of tests
^^^^^^^^^^^^^^^^^^^^
To compile the tests, first unzip gtest to location of your desire.
Some of the tests require a second node on the same network. There are two cmake
variables which are used to automatically adapt the json files to the used
network setup:

* `TEST_IP_MASTER`: The IP address of the interface which will act as test
  master.
* `TEST_IP_SLAVE`: The IP address of the interface of the second node which will
  act as test slave.

If one of this variables isn't specified, only the tests using local
communication exclusively will be runnable.

Example, compilation of tests:
[source, bash]
----
mkdir build
cd build
export GTEST_ROOT=$PATH_TO_GTEST/gtest-1.7.0/
cmake -DTEST_IP_MASTER=10.0.3.1 -DTEST_IP_SLAVE=10.0.3.125 ..
make check
----

Additional make targets for the tests:

* Call `make build_tests` to only compile the tests
* Call `ctest` in the build directory to execute the tests without a verbose
  output
* To run single tests call `ctest --verbose --tests-regex $TESTNAME` short
  form: `ctest -V -R $TESTNAME`
* To list all available tests run `ctest -N`.
* For further information about the tests please have a look at the
  `readme.txt` in the `test` subdirectory.

For development purposes two cmake variables exist which control if the
json files and test scripts are copied (default) or symlinked into the build
directory. These settings are ignored on Windows.

* `TEST_SYMLINK_CONFIG_FILES`: Controls if the json and scripts needed
  to run the tests are copied or symlinked into the build directory. (Default:
  OFF, ignored on Windows)
* `TEST_SYMLINK_CONFIG_FILES_RELATIVE`: Controls if the json and scripts needed
  to run the tests are symlinked relatively into the build directory.
  (Default: OFF, ignored on Windows)

Example cmake call:
[source, bash]
----
cmake  -DTEST_SYMLINK_CONFIG_FILES=ON -DTEST_SYMLINK_CONFIG_FILES_RELATIVE=ON ..
----

For compilation of only a subset of tests (for a quick
functionality check) the cmake variable `TESTS_BAT` has
to be set:

Example cmake call:
[source, bash]
----
cmake  -DTESTS_BAT=ON ..
----

Generating the documentation
^^^^^^^^^^^^^^^^^^^^^^^^^^^^
To generate the documentation call cmake as described in <<Compilation>> and
then call `make doc`.
This will generate:

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

Starting vsomeip Applications / Used environment variables
----------------------------------------------------------
On startup the following environment variables are read out:

* `VSOMEIP_APPLICATION_NAME`: This environment variable is used to specify the
  name of the application. This name is later used to map a client id to the
  application in the configuration file. It is independent from the
  application's binary name.
* `VSOMEIP_CONFIGURATION`: vsomeip uses the default configuration file `/etc/vsomeip.json`
   and/or the default configuration folder `/etc/vsomeip`. This can be overridden by a
   local configuration file `./vsomeip.json` and/or a local configuration folder `./vsomeip`.
   If `VSOMEIP_CONFIGURATION` is set to a valid file or directory path, this is used instead
   of the standard configuration (thus neither default nor local file/folder will be parsed).

NOTE: If the file/folder that is configured by `VSOMEIP_CONFIGURATION` does _not_ exist,
the default configuration locations will be used.

NOTE: vsomeip will parse and use the configuration from all files in a configuration folder
but will _not_ consider directories within the configuration folder.

In the following example the application `my_vsomeip_application` is started.
The settings are read from the file `my_settings.json` in the current working
directory. The client id for the application can be found under the name
`my_vsomeip_client` in the configuration file.

[source, bash]
----
#!/bin/bash
export VSOMEIP_APPLICATION_NAME=my_vsomeip_client
export VSOMEIP_CONFIGURATION=my_settings.json
./my_vsomeip_application
----

Configuration File Structure
----------------------------
The configuration files for vsomeip are http://www.json.org/[JSON]-Files and are
composed out of multiple key value pairs and arrays.

[quote, , json.org]
____
* An object is an unordered set of name/value pairs. An object begins with `{
(left brace)` and ends with `} (right brace)`. Each name is followed by `:
(colon)` and the name/value pairs are separated by `, (comma)`.

* An array is an ordered collection of values. An array begins with `[ (left
bracket)` and ends with `] (right bracket)`. Values are separated by `,
(comma)`.

* A value can be a _string_ in double quotes, or a _number_, or `true` or `false`
or `null`, or an _object_ or an _array_. These structures can be nested.
____

Configuration file element explanation:


* 'unicast'
+
The IP address of the host system.
+
* 'netmask'
+
The netmask to specify the subnet of the host system.
+
//Logging
* 'logging'
+
** 'level'
+
Specifies the log level (valid values: _trace_, _debug_, _info_, _warning_,
_error_, _fatal_).
+
** 'console'
+
Specifies whether logging via console is enabled (valid values: _true, false_).
+
** 'file'
+
*** 'enable'
+
Specifies whether a log file should be created (valid values: _true, false_).
+
*** 'path'
+
The absolute path of the log file.
+
** 'dlt'
+
Specifies whether Diagnostic Log and Trace (DLT) is enabled (valid values:
_true, false_).
+
//Applications
* 'applications (array)'
+
Contains the applications of the host system that use this config file.
+
** 'name'
+
The name of the application.
+
** 'id'
+
The id of the application.
+
** 'num_dispatchers'
+
The number of threads that shall be used to execute the callbacks to the application.
If 'num_dispatchers' is set to '0', the callbacks will be executed within the 
application thread. If an application wants/must do time consuming work directly
within event, availability or message callbacks, 'num_dispatchers' should be set
to '2' or higher.
+
** `services` (array)
+
Contains the services of the service provider.

*** `service`
+
The id of the service.

*** `instance`
+
The id of the service instance.

*** `protocol` (optional)
+
The protocol that is used to implement the service instance. The default setting
is _someip_. If a different setting is provided, vsomeip does not open the specified
port (server side) or does not connect to the specified port (client side). Thus,
this option can be used to let the service discovery announce a service that is
externally implemented. 

*** `unicast` (optional)
+
The unicast that hosts the service instance.
+
NOTE: The unicast address is needed if external service instances shall be used,
but service discovery is disabled. In this case, the provided unicast address
is used to access the service instance. 

*** `reliable`
+
Specifies that the communication with the service is reliable respectively the
TCP protocol is used for communication.

**** `port`
+
The port of the TCP endpoint.

**** `enable-magic-cookies`
+
Specifies whether magic cookies are enabled (valid values: _true_, _false_).

*** `unreliable`
+
Specifies that the communication with the service is unreliable respectively the
UDP protocol is used for communication (valid values: the _port_ of the UDP
endpoint).

*** `multicast`
+
A service can be offered to a specific group of clients via multicast.

**** `address`
+
The specific multicast address.

**** `port`
+
The specific port.

*** `events` (array)
+
Contains the events of the service.

**** `event`
+
The id of the event.

***** `is_field`
+
Specifies whether the event is of type field.
+
NOTE: A field is a combination of getter, setter and notification event. It
contains at least a getter, a setter, or a notifier. The notifier sends an event
message that transports the current value of a field on change.

***** `is_reliable`
+
Specifies whether the communication is reliable respectively whether the event
is sent with the TCP protocol (valid values: _true_,_false_).
+
If the value is _false_ the UDP protocol will be used.

*** `eventgroups` (array)
+
Events can be grouped together into on event group. For a client it is thus
possible to subscribe for an event group and to receive the appropriate events
within the group.

**** `eventgroup`
+
The id of the event group.

**** `events` (array)
+
Contains the ids of the appropriate events.

**** `is_multicast`
+
Specifies whether the events should be sent via multicast (valid values:
_true_,_false_).

**** `multicast`
+
The multicast address which the events are sent to.

* `payload-sizes` (array)
+
Array to specify the maximum allowed payload sizes per IP and port. If not
specified, or a smaller value than the default values is specified, the default
values are used. The settings in this array only affect communication over TCP
and local communication over UNIX domain sockets.

** `unicast`
+
On client side: the IP of the remote service to which the oversized messages
should be sent.
On service side: the IP of the offered service which should receive the
oversized messages and is allowed to respond with oversized messages.
If client and service only communicate locally, any IP can be entered here as
for local communication only the maximum specified payload size is relevant.

** `ports` (array)
+
Array which holds pairs of port and payload-size statements.

*** `port`
+
On client side: the port of the remote service to which the oversized messages
should be sent.
On service side: the port of the offered service which should receive the
oversized messages and is allowed to respond with oversized messages.
If client and service only communicate locally, any port number can be entered.

*** `max-payload-size`
+
On client side: the maximum payload size in bytes of a message sent to the
remote service hosted on beforehand specified IP and port.
On service side: the maximum payload size in bytes of messages received by the
service offered on previously specified IP and port. If multiple services are
hosted on the same port all of them are allowed to receive oversized messages
and send oversized responses.

* `routing`
+
The name of the application that is responsible for the routing.

* `service-discovery`
+
Contains settings related to the Service Discovery of the host application.

** `enable`
+
Specifies whether the Service Discovery is enabled (valid values: _true_,
_false_). The default value is _true_.

** `multicast`
+
The multicast address which the messages of the Service Discovery will be sent
to. The default value is "224.0.0.1".

** `port`
+
The port of the Service Discovery. The default setting is 30490.

** `protocol`
+
The protocol that is used for sending the Service Discovery messages (valid
values: _tcp_, _udp_). The default setting is _udp_.

** `initial_delay_min`
+
Minimum delay before first offer message.

** `initial_delay_max`
+
Maximum delay before first offer message.

** `repetitions_base_delay`
+
Base delay sending offer messages within the repetition phase.
 
** `repetitions_max`
+
Maximum number of repetitions for provided services within the 
repetition phase.
 
** `ttl`
+
Lifetime of entries for provided services as well as consumed services and eventgroups.

** `cyclic_offer_delay`
+
Cycle of the OfferService messages in the main phase.

** `request_response_delay`
+
Minimum delay of a unicast message to a multicast message for
provided services and eventgroups.

Autoconfiguration
-----------------
vsomeip supports the automatic configuration of client identifiers and the routing.
The first application that starts using vsomeip will automatically become the
routing manager if it is _not_ explicitly configured. The client identifiers
are generated from the diagnosis address that can be specified by defining
DIAGNOSIS_ADDRESS when compiling vsomeip. vsomeip will use the diagnosis address
as the high byte and enumerate the connecting applications within the low byte
of the client identifier.

vsomeipd
--------
The vsomeipd is a minimal vsomeip application intended to offer routing manager
functionality on a node where one system wide configuration file is present.

The vsomeipd uses the application name `vsomeipd` by default. This name can be
overridden by specifying `-DROUTING=$DESIRED_NAME` during the cmake call.

Example: Starting the daemon on a system where the system wide configuration is
stored under `/etc/vsomeip.json`:
[source, bash]
----
VSOMEIP_CONFIGURATION=/etc/vsomeip.json ./vsomeipd
----

When using the daemon it should be ensured that:

* In the system wide configuration file the vsomeipd is defined as
  routing manager, meaning it contains the line `"routing" : "vsomeipd"`.
  If the default name is overridden the entry has to be adapted accordingly.
  The system wide configuration file should contain the information about all
  other offered services on the system as well.
* There's no other vsomeip configuration file used on the system which contains
  a `"routing"` entry. As there can only be one routing manager per system.


vsomeip Hello World
-------------------
In this paragraph a Hello World program consisting out of a client and a service
is developed. The client sends a message containing a string to the service.
The service appends the received string to the string `Hello` and sends it back
to the client.
Upon receiving a response from the service the client prints the payload of the
response ("Hello World").
This example is intended to be run on the same host.

All files listed here are contained in the `examples\hello_world` subdirectory.

Build instructions
~~~~~~~~~~~~~~~~~~
The example can build with its own CMakeFile, please compile the vsomeip stack
before hand as described in <<Compilation>>. Then compile the example starting
from the repository root directory as followed:
[source, bash]
----
cd examples/hello_world
mkdir build
cd build
cmake ..
make
----

Starting and expected output
~~~~~~~~~~~~~~~~~~~~~~~~~~~

Starting and expected output of service
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[source, bash]
----
$ VSOMEIP_CONFIGURATION=../helloworld-local.json \
  VSOMEIP_APPLICATION_NAME=hello_world_service \
  ./hello_world_service
2015-04-01 11:31:13.248437 [info] Using configuration file: ../helloworld-local.json
2015-04-01 11:31:13.248766 [debug] Routing endpoint at /tmp/vsomeip-0
2015-04-01 11:31:13.248913 [info] Service Discovery disabled. Using static routing information.
2015-04-01 11:31:13.248979 [debug] Application(hello_world_service, 4444) is initialized.
2015-04-01 11:31:22.705010 [debug] Application/Client 5555 got registered!
----

Starting and expected output of client
^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
[source, bash]
----
$ VSOMEIP_CONFIGURATION=../helloworld-local.json \
  VSOMEIP_APPLICATION_NAME=hello_world_client \
  ./hello_world_client
2015-04-01 11:31:22.704166 [info] Using configuration file: ../helloworld-local.json
2015-04-01 11:31:22.704417 [debug] Connecting to [0] at /tmp/vsomeip-0
2015-04-01 11:31:22.704630 [debug] Listening at /tmp/vsomeip-5555
2015-04-01 11:31:22.704680 [debug] Application(hello_world_client, 5555) is initialized.
Sending: World
Received: Hello World
----

CMakeFile
~~~~~~~~~

[source, bash]
----
include::examples/hello_world/CMakeLists.txt[]
----

Configuration File For Client and Service
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

[source, bash]
----
include::examples/hello_world/helloworld-local.json[]
----

Service
~~~~~~~

[source, bash]
----
include::examples/hello_world/hello_world_service.cpp[]
----

The service example results in the following program execution:

:numbered!:

[float]

Main
^^^^^

. __main()__
+
First the application is initialized. After the initialization is
finished the application is started.

[float]
Initialization
^^^^^^^^^^^^^^

[start=2]
. __init()__
+
The initialization contains the registration of a message
handler and an event handler.
+
The message handler declares a callback (__on_message_cbk__) for messages that
are sent to the specific service (specifying the service id, the service
instance id and the service method id).
+
The event handler declares a callback (__on_event_cbk__) for events that occur.
One event can be the successful registration of the application at the runtime.

[float]
Start
^^^^^

[start=3]
. __start()__
+
The application will be started. This function only returns when the application
will be stopped.

[float]
Callbacks
^^^^^^^^^

[start=4]
. __on_state_cbk()__
+
This function is called by the application when an state change occurred. If
the application was successfully registered at the runtime then the specific
service is offered.

. __on_message_cbk()__
+
This function is called when a message/request from a client for the specified
service was received.
+
First a response based upon the request is created.
Afterwards the string 'Hello' will be concatenated with the payload of the
client's request.
After that the payload of the response is created. The payload data is set with
the previously concatenated string.
Finally the response is sent back to the client and the application is stopped.

[float]
Stop
^^^^

[start=6]
. __stop()__
+
This function stops offering the service, unregister the message and the event
handler and shuts down the application.

:numbered:

Client
~~~~~~
[source, bash]
----
include::examples/hello_world/hello_world_client.cpp[]
----

The client example results in the following program execution:

:numbered!:

[float]
Main
^^^^^

. __main()__
+
First the application is initialized. After the initialization is finished the
application is started.

[float]
Initialization
^^^^^^^^^^^^^^

[start=2]
. __init()__
+
The initialization contains the registration of a message handler, an event
handler and an availability handler.
+
The event handler declares again a callback (__on_state_cbk__) for state changes
that occur.
+
The message handler declares a callback (__on_message_cbk__) for messages that
are received from any service, any service instance and any method.
+
The availability handler declares a callback (__on_availability_cbk__) which is
called when the specific service is available (specifying the service id and the
service instance id).

[float]
Start
^^^^^

[start=3]
. __start()__
+
The application will be started. This function only returns when the application
will be stopped.

[float]
Callbacks
^^^^^^^^^

[start=4]
. __on_state_cbk()__
+

This function is called by the application when an state change occurred. If the
application was successfully registered at the runtime then the specific service
is requested.

. __on_availability_cbk()__
+
This function is called when the requested service is available or no longer
available.
+
First there is a check if the change of the availability is related to the
'hello world service' and the availability changed to true.
If the check is successful a service request is created and the appropriate
service information are set (service id, service instance id, service method
id).
After that the payload of the request is created. The data of the payload is
'World' and will be set afterwards.
Finally the request is sent to the service.

. __on_message_cbk()__
+
This function is called when a message/response was received.
If the response is from the requested service, of type 'RESPONSE' and the return
code is 'OK' then the payload of the response is printed. Finally the
application is stopped.

[float]
Stop
^^^^

[start=7]
. __stop()__
+
This function unregister the event and the message handler and shuts down the
application.

:numbered: