**Table of Content**

1. TOC
{:toc}

## Context

In today's world, the information for a driver is becoming excessive. For 
example, the safety information to let a driver notice the obstacles on the road,
the telematics information about a car accident or a traffic jam, the media
information from connected phones etc. In the future world, it is expected that
more displays will be available in the car and show more information. 
The cluster will have more information other than engine speed or fuel meter, 
In-Vehicle-Infortainment discplay will show you a map with very rich contents not
only gudigin the route. Head Up Display on a windshield will bring the driver to
the new world. Therefore We will need to show the information on the appropriate 
display, so that a driver will not be confuesed due to the information overload.
In order to achieve this, we need something which can transfer the information 
from the device where it's produced to the display which makes it visible.
Waltham is developed to be this something. It transfers the rendering metadata
from one device to the other.

## Waltham

Waltham resembles [Wayland](https://wayland.freedesktop.org).
Wayland is a communication protocol with C libraries that implement (Wayland)
protocol. Compositors and clients use those libraries to talk to each other. 
(libwayland-server and libwayland-client). 
Waltham is also a protocol, which is described in XML. As a result of parsing that
mark-up language, it's a C library. The keyword here about Waltham is the *network* 
IPC library. libwayland-server and libwayland-client are both IPC libraries. 
Waltham on the other hand, works over the network. 
Waltham is developped by Collabora along with ADIT, a joint venture company owned
by Robert Bosch Car Multimedia GmbH and DENSO corporation.

Please refer [Waltham documentation](https://waltham.github.io/waltham/) for
more details.

### Major differences from Wayland to Waltham
- Waltham uses TCP sockets for reliable communication
- Waltham cannot send file descriptors
- Waltham API is minimal and symmetric between server and client side
- Waltham does not provide an event loop implementation
- The registry implementation is left out of the library, only the interface is
provided
- No multi-threading support for sharing objects between threads

![image](./images/Diffrence_between_Wayland_and_Waltham.jpg)

### Requirements in automotive industry
In order to use Waltham in automotive industry, the automotive specific
requirements must be covered.

The below shows very high level requirements. You can find the further
requirements at [**Waltham Requirements**](https://confluence.automotivelinux.org/displa
y/UIGRA/Waltham+backend+requirements).

1. Shall be able to support fast/reliable remoting among multiple ECUs
2. Shall be able to support input handling
3. Shall be able to share dedicated application
4. Shall be able to share complete display output depending on additional
communication

* Surface sharing is not part of Waltham protocol, Each system needs to
implement the most efficient way for surface sharing.
On AGL, we implemented [Waltham client and Receiver](1-waltham-client-and-receiv
er.md) to enable surface sharing along with GStreamer encoder/decoder.
Gstreamer transfers the buffers via UDP, which is faster than TCP. 
Input events are supported by Waltham protocol.

### Links
* [Announcement of Waltham](https://lists.freedesktop.org/archives/wayland-devel
/2016-October/031413.html)
* [Bi-weekly meeting minutes](https://wiki.automotivelinux.org/eg-ui-graphics)
* [UI and Graphics wiki](https://confluence.automotivelinux.org/display/UIGRA/UI
+and+Graphics+Home)
* [Waltham source codes](https://gerrit.automotivelinux.org/gerrit/gitweb?p=src/
weston-ivi-plugins.git;a=tree;h=refs/heads/master;hb=refs/heads/master)