.. _comm_protoc_gener:
.. include:: <isonum.txt>

======================
Communication protocol
======================

The server and its clients use a certain protocol for their communication.

Network
=======
The communication is handled with *ZeroMQ* (*zmq*, `https://zeromq.org <https://zeromq.org/>`_) via port ``11657`` (TCP).

Message format
==============

Multipart message with 4 frames: ``[ID, empty, action, data]``.
All components are of type ``string``.

The last component ``data`` needs to be formatted as a JSON string with specified entries.

General entries in ``data``
---------------------------
**Client** |rarr| **Server:**

* Empty data can be specified by ``"{}"``.

**Server** |rarr| **Client:**

* The entry ``success`` is always required, and if ``success == False``, only an entry ``error`` needs to be present.
* The entry ``busy`` might be set to ``True`` if the server is busy at the moment.
  In this case, no other entries are available in the data (except ``success``).
  The client should retry the request after waiting a while.
  If the server is not busy, it sends the data described in the table below back to the client.

Actions
-------
For specific ``action``\ s, please see the developer documentation of the corresponding applications.