docs/6_Component_Documentation/3_waltham-receiver_waltham-transmitter.md

   1 ---
   2 title: Waltham receiver/transmitter
   3 ---
   4
   5 # Waltham
   6
   7 [Waltham protocol](https://github.com/waltham/waltham) is a IPC library similar
   8 to [Wayland](https://wayland.freedesktop.org), developed with networking in
   9 mind. It operates over TCP sockets, while the wayland protocol only works
  10 locally over a UNIX socket. It retains wayland-esque paradigm, making use of
  11 XMLs to describe the protocol, and it follows an object-oriented design with an
  12 asynchronous architecture.
  13
  14 ## Differences from Wayland to Waltham
  15
  16 Some of the differences between Wayland and Waltham are:
  17
  18 * Waltham uses TCP sockets for communication
  19 * Waltham cannot send file descriptors
  20 * Waltham API is minimal and symmetric between server and client sides
  21 * Waltham does not provide an event loop implementation
  22 * The registry implementation is left out of the library, only the interface is
  23   provided
  24 * No multi-threading support for sharing objects between threads
  25
  26 ## Waltham-transmitter and remoting plugin
  27
  28 Surface sharing is not part of Waltham protocol, each system needs to implement
  29 the most efficient way of passing by the buffers from one side to another.  On
  30 AGL, make use of remoting-plugin to enable surface sharing which uses GStreamer
  31 as encoder/decoder. It uses libweston DRM virtual API to grab the buffers, and
  32 then to stream them over the network. The gstreamer pipeline uses UDP while the
  33 input events are communicated with Waltham protocol. The input part is handled
  34 by *waltham-transmitter* plugin which provides an API to create remote
  35 connections and push surfaces over the network and handles remote input. The
  36 act of pushing surface is a misnomer, kept from the older, previous
  37 implementation, and acts a notification mechanism from the transmitter side to
  38 the remote side.
  39
  40 ## The receiver client
  41
  42 waltham-receiver application is a wayland demo implementation  which should be
  43 running at the remote side. It is using Waltham protocol to obtain and process
  44 remote input events which handled the transmitter side by the waltham-transmitter
  45 plugin. It creates a similar gstreamer pipeline to process the incoming buffers
  46 and draw and displaying them into a subsurface created by waylandsink.
  47
  48 Contrary to expectations, the waltham receiver is the one that implements the
  49 server side of the Waltham protocol and is capable of displaying the incoming
  50 buffers but also process input events locally and forward them with the help of
  51 the Waltham protocol back at the transmitter side, which in turn will update
  52 the image contents and stream to the receiver, showing the changes caused by
  53 that input.
  54
  55
  56      ECU 1                                                               ECU 2
  57      +---------------------------------------------+                    +--------------------------------------+
  58      |        +-----------------+                  |                    |                                      |
  59      |        |     Application |                  |                    |       +-----------+-----------+      |
  60      |        +-----------------+                  |                    |       | Gstreamer |           |      |
  61      |                 ^                           |    Buffer   ---------------> (Decode)  |           |      |
  62      |        wayland  |                    +-------------------/       |       +-----------+           |      |
  63      |                 v                    |      |    (Ethernet)      |       |     Waltham-receiver  |      |
  64      |   +----+---------------------+       |      |        -------------------->                       |      |
  65      |   |    |  Transmitter plugin |<---------------------/            |       +-----------------------+      |
  66      |   |    |                     |       |      |  Waltham-Protocol  |                     ^                |
  67      |   |    |---------------------|       |      |                    |             wayland |                |
  68      |   |    |  Remoting plugin    |-------+      |                    |                     v                |
  69      |   |    |                     |              |                    |         +---------------------+      |
  70      |   |    +---------------------+              |                    |         |                     |      |
  71      |   |                          |              |                    |         |       compositor    |      |
  72      |   |         compositor       |              |                    |         |                     |      |
  73      |   +------+-------------------+              |                    |         +----------------+----+      |
  74      |          |                                  |                    |                          |           |
  75      |          v                                  |                    |                          v           |
  76      |   +------------+                            |                    |                    +----------+      |
  77      |   |  Display   |                            |                    |                    |  Display |      |
  78      |   |            |                            |                    |                    |          |      |
  79      |   +------------+                            |                    |                    +----------+      |
  80      +---------------------------------------------+                    +--------------------------------------+
  81
  82 ## Migrating/Placing applications on other outputs
  83
  84 In order to start or place an application on the remoting-ouput output, we can
  85 use `agl-shell-app-id` ini entry for that particular output.
  86
  87         [transmitter-output]
  88     name=transmitter-1
  89     mode=640x720@30
  90     host=192.168.20.99
  91     port=5005
  92     agl-shell-app-id=<APP_ID>
  93
  94 Alternatively, and programmatically, one can use the
  95 [agl-shell-desktop](1_agl-compositor.md#private-extensions) protocol and inform
  96 the compositor that it should migrate it to other, remote outputs.