Commit ceff46d6 authored by Milosz Malczak's avatar Milosz Malczak

docs: cleanup

parent cd105d8e
......@@ -21,7 +21,7 @@ In order to do this, the following tasks have to be performed:
* establish communication with the Server using the existing interface and if
necessary, update the interface
The section expalins breifly the communication patterns, existing interfaces
The section expalins briefly the communication patterns, existing interfaces
and models of applications as well as the changes that have to be done to be
able to add a new application.
......@@ -57,15 +57,15 @@ the Server and the Server sends the RPC requests to the Device Application.
Publisher/subscriber pattern is used for sending acquisition data and
notifications about the availability of nodes. Device Applications send the
notifications and acquisition data to the Server, which propagates them to the
notifications and acquisition data to the Server, which propagates them to
User Applications.
There are two ways of sending the notifications about the presence of the
There are two ways of providing the information about the presence of the
Device Application to the Server:
* if the IP address of the server is provided during the startup of the
Device Application, the notification is sent over the standard communication
channel the most bottom one in :numref:`fig_do_communication`.
channel -- the most bottom one in :numref:`fig_do_communication`.
* using Zeroconf, which automatically discovers the IP address of the Server.
However, the Zeroconf Listener in the Server also uses
the publisher/subscriber pattern for internal communication.
......@@ -79,6 +79,8 @@ Applications Models
=======================
The Server contains models of User Applications and Device Applications.
Interaction with the applications is done through interaction with the models,
using provided :ref:`interfaces`.
User Application model
-----------------------
......@@ -92,7 +94,9 @@ model, that is:
* acquisition settings (e.g. length of acquisition, position of the trigger...)
There are no forseen changes in the User Application model when adding a new
User Application. The new application should make use of the
User Application.
New applications should make use of the
:ref:`server_interface` and implement the
:ref:`user_application_interface`.
......@@ -107,8 +111,10 @@ device. In case of the ADC, the functionalities are the following:
* acquisition settings
The main reason for adding a new Device Application is adding a new type of
device. In that case, the model of the application as well as the
:ref:`device_application_interface` should be modified or added.
device. In that case, the model of the application,
:ref:`device_application_interface` and
:ref:`server_interface`
should be modified.
.. _interfaces:
......@@ -119,7 +125,7 @@ Interfaces
The Server provides interfaces for User Applications and Devices Applications.
Each new application should use these interfaces. If the interfaces don't
meet the requirements for the new application, they should be modified.
meet the requirements for new application, they should be modified.
.. _server_interface:
......
......@@ -41,10 +41,14 @@ The structure of the DO is presented in :numref:`fig_DO_basic_schematics`.
Structure of the DO
The DO Server is a proxy between Devices and Users Applications. In a single network, there could be one server, multiple users and multiple devices. The applications typically are run on different machines, but it is not a restriction.
The DO Server is a proxy between Devices and Users Applications. In a
single network, there could be one server, multiple users and multiple devices.
The applications typically are run on different machines, but it is not a
restriction.
.. _user_application_intro:
=====================
`User Applications`_
......@@ -53,44 +57,64 @@ The DO Server is a proxy between Devices and Users Applications. In a single net
There are currently two User Applications available:
* GUI --- it is designed to resemble standard oscilloscope.
* testbench --- it is used to test the DO Server and the Device Applications as well as to perform statistical measurements of data acquisition speed and of the precision of the synchronization.
* testbench --- it is used to test the DO Server and the Device Applications
as well as to perform statistical measurements of data acquisition speed and
of the precision of the synchronization.
The User Applications serve the following purposes:
User Applications serve the following purposes:
* Sending the configuration settings
* Collecting and processing the acquisition data
The Device Applications never communicate with the devices directly, always through the DO Server. This allows to hide all the implementation details and to provide a common interface for various types of applications.
The details on how to write User Applications are described in section :ref:`developer_guide`
Device Applications never communicate with the devices directly, always through
the DO Server. This allows to hide all the implementation details and to
provide a common interface for various types of applications.
The details on how to write User Applications are described in
section :ref:`developer_guide`
.. _do_server_intro:
================
`DO Server`_
================
The DO Server is a central unit responsible for managing all the connections, preprocessing the data and providing a common interface for connected applications.
The DO Server is a central unit responsible for managing all the connections,
preprocessing the data and providing a common interface for connected
applications.
.. _device_application_intro:
======================
`Device Application`_
======================
Device applications provide direct access to hardware resources. At the moment the only available devices are ADCs supported by the `adc-lib <https://ohwr.org/project/adc-lib/wikis/home>`_.
Device applications provide direct access to hardware resources. At the moment
the only available devices are ADCs supported by
the `adc-lib <https://ohwr.org/project/adc-lib/wikis/home>`_.
Hardware setup
================
The minimum hardware requirements necessary to demonstrate features of the DO are the following:
The minimum hardware requirements necessary to demonstrate features of the DO
are the following:
* computer with minimum 2 PCIe slots and CentOS 7.6.1810
.. note::
The DO is designed to run each application on a different machine. However, it is possible to run them on the same machine. To make the DO really distributed, the ADC cards should be installed in different locations in different machines. The described hardware setup should serve only as a demonstrator.
The DO is designed to run each application on a different machine. However,
it is possible to run them on the same machine. To make the DO really
distributed, the ADC cards should be installed in different locations in
different machines. The described hardware setup should serve only as a
demonstrator.
.. note::
CentOS 7.6.1810 guaranties that all the drivers will function properly. However, it is possible to use the DO with different OS. In case of machines where the Server and the GUI are run, the Linux version does not matter.
CentOS 7.6.1810 guaranties that all the drivers will function properly.
However, it is possible to use the DO with different OS. In case of
machines where the Server and the GUI are run, the Linux version does not
matter.
* `White Rabbit Switch <https://www.ohwr.org/projects/white-rabbit/wiki/switch>`_
......@@ -98,7 +122,9 @@ The minimum hardware requirements necessary to demonstrate features of the DO ar
.. important::
The DO will work only with SPEC 150T version. Be careful not to purchase standard SPEC 45T version.
The DO will work only with SPEC 150T version. Be careful not to
purchase standard SPEC 45T version.
* 2 `FMC ADC 100M 14b 4cha <https://www.ohwr.org/project/fmc-adc-100m14b4cha/wikis/home>`_ boards
* 2 fibers
* 4 SFP cages
......@@ -117,5 +143,8 @@ The minimum hardware setup of the DO is presented in :numref:`fig_hardware_setup
The SPEC boards together with ADC cards should be installed in PCIe slots of the computer and connected to any of White Rabbit switch channels using the SFP cages and fibers. To be able to demonstrate the synchronization accuracy, the same signal from the generator should be provided to both ADCs, with cables of the same length or precisely known lengths.
The SPEC boards together with ADC cards should be installed in PCIe slots of
the computer and connected to any of the White Rabbit switch channels using
the SFP cages and fibers. To be able to demonstrate the synchronization
accuracy, the same signal from the generator should be provided to both ADCs,
with cables of the same length or precisely known lengths.
......@@ -4,12 +4,17 @@
Starting Applications
======================
The GUI and the Server can be run on any Linux machine with python3.6. Before starting the ADC application, all the dependencies, described in section :ref:`dependencies`, have to be installed.
The GUI (:ref:`user_application_intro`) and the :ref:`do_server_intro` can be
run on any Linux machine with python3.6. Before starting the
ADC application (:ref:`device_application_intro`), all the dependencies,
described in section :ref:`dependencies`, have to be installed.
The first application that has to be run is the Server. When the Server is already started, GUIs and ADC nodes can be run in any order.
The first application that has to be run is the Server. When the Server is
already started, GUIs and ADC nodes can be run in any order.
Before starting any of the applications, start the virtual environment and install the Distributed Oscilloscope, as described in section :ref:`inst_app`.
Before starting any of the applications, start the virtual environment and
install the Distributed Oscilloscope, as described in section :ref:`inst_app`.
.. _server_application:
......@@ -32,7 +37,8 @@ Optional arguments:
GUI:
----------------
Before starting the GUI applications, find out what is the IP address of the Server: SERVER_IP_ADDRESS. You can check it using the command:
Before starting the GUI applications, find out what is the IP address of the
Server: SERVER_IP_ADDRESS. You can check it using the command:
.. code-block:: console
......@@ -52,19 +58,25 @@ Required arguments:
Optional arguments:
* port -- port used on the current machine to listen for notifications and acquisition data, default value -- 8001
* port_server -- port used on the Server to listen for the requests from the GUI, default value -- 8003
* port -- port used on the current machine to listen for notifications and
acquisition data, default value -- 8001
* port_server -- port used on the Server to listen for the requests from
the GUI, default value -- 8003
.. _adc_application:
ADC application:
------------------
If the Server and the ADC device are in different local networks, before staring the ADC applications, find out what is the IP address of the Server: SERVER_IP_ADDRESS. If the IP address of the Server is not provided, Zeroconf will be used to automatically find out this information.
If the Server and the ADC device are in different local networks, before
staring the ADC applications, find out what is the IP address of the Server:
SERVER_IP_ADDRESS. If the IP address of the Server is not provided, Zeroconf
will be used to automatically find out this information.
.. important::
The Zeroconf will only work if the Server and the ADC are in the same local networks. Otherwise, the IP of the Server has to be provided manually.
The Zeroconf will only work if the Server and the ADC are in the same local
networks. Otherwise, the IP of the Server has to be provided manually.
To start the GUI, run in terminal:
......@@ -76,14 +88,18 @@ To start the GUI, run in terminal:
Optional arguments:
* ip_server -- IP address of the server
* port_server -- port of the server used to listen for notifications and acquisition data, default value -- 8023
* port -- port used on the current machine to listen for the requests from the Server, default value -- 8000
* port_server -- port of the server used to listen for notifications and
acquisition data, default value -- 8023
* port -- port used on the current machine to listen for the requests from the
Server, default value -- 8000
* pci_addr -- PCI address of the desired board, default value -- 0x01
Examples configuration:
-------------------------
Supposing that the IP address of the Server is 128.141.79.22, the ADCs are installed in the same machine and the PCI slots where the ADCs are installed are 01 and 02, the applications have to be started with following parameters:
Supposing that the IP address of the Server is 128.141.79.22, the ADCs are
installed in the same machine and the PCI slots where the ADCs are installed
are 01 and 02, the applications have to be started with following parameters:
.. code-block:: console
......
......@@ -19,7 +19,9 @@ The GUI application is presented in :numref:`fig_gui`.
Channels selection
------------------
Just like in standard oscilloscope, there is a possibility of observing up to 4 channels. Any channel of any available ADC can be connected to the particular channel of the GUI.
Just like in standard oscilloscope, there is a possibility of observing up to
4 channels. Any channel of any available ADC can be connected to the particular
channel of the GUI.
.. figure:: graphics/GUI_channels_selection.png
:name: fig_gui_chann_sel
......@@ -34,7 +36,8 @@ Just like in standard oscilloscope, there is a possibility of observing up to 4
Triggers selection
------------------
The ADCs could be triggered either by external trigger pulse or when the signal of the observed channel crosses the threshold value.
The ADCs could be triggered either by external trigger pulse or when the signal
of the observed channel crosses the threshold value (internal trigger).
.. figure:: graphics/GUI_triggers_selection.png
:name: fig_gui_trigg_sel
......@@ -49,7 +52,8 @@ The ADCs could be triggered either by external trigger pulse or when the signal
Internal trigger
^^^^^^^^^^^^^^^^
If the internal trigger is selected, the GUI could be triggered on any channel to which a signal is connected.
If the internal trigger is selected, the GUI could be triggered on any channel
to which a signal is connected.
.. figure:: graphics/GUI_internal_trigger.png
:name: fig_gui_int_trigg
......@@ -64,7 +68,8 @@ If the internal trigger is selected, the GUI could be triggered on any channel t
External trigger
^^^^^^^^^^^^^^^^
If the external trigger is selected, the GUI could be triggered by the external trigger input of any connected ADC.
If the external trigger is selected, the GUI could be triggered by the external
trigger input of any connected ADC.
.. figure:: graphics/GUI_external_trigger.png
:name: fig_gui_ext_trigg
......@@ -135,7 +140,8 @@ There are two available modes:
Acquisition settings
--------------------
Acquisition settings allow modifying the acquisition time and position of the trigger. Position of the trigger is given in percentage of the acquisition time.
Acquisition settings allow modifying the acquisition time and position of the
trigger. Position of the trigger is given in percentage of the acquisition time.
.. figure:: graphics/GUI_acquisition_settings.png
:name: fig_gui_acq_set
......
......@@ -123,8 +123,8 @@ class GUI_Class:
def update_data(self, data, pre_post_samples, offsets):
"""
It is used to send the acquisition data from the Server to the User
Application and depeneding on requirements of the Application, process
it or display. In case of GUI, the data is just displayed.
Application and, depeneding on requirements of the Application, process
or display the data. In case of the GUI, the data is displayed.
:param data: dictionary with GUI channels indexes as keys, containing
acquisition data
......
......@@ -67,7 +67,7 @@ class DevicesAccess():
ADC_trigger_idx=None):
"""
Defines if particular device works as master or slave. The master
distributed the triggers, the slave receives the triggers.
distributes the triggers, the slave receives the triggers.
Master mode:
......@@ -87,8 +87,8 @@ class DevicesAccess():
works as slave
:param trigger_type: in master mode defines the type of the trigger to\
enable
:param ADC_trigger_idx: in master mode dfines the index of the trigger\
to enable
:param ADC_trigger_idx: in master mode defines the index of the\
trigger to enable
"""
for count in range(4):
self.__ADC.set_internal_trigger_enable(0, count)
......@@ -130,7 +130,7 @@ class DevicesAccess():
:param function_name: the name of the function, which modifies\
particular ADC parameter
:param *args: arguments passed to the function -- the type of\
:param args: arguments passed to the function -- the type of\
arguments depends on the selected function
"""
if(function_name == 'set_presamples' and self.__WRTD_master is False):
......
......@@ -24,7 +24,7 @@ class ServerExpose():
def __getattr__(self, function_name):
"""
If he required function is not defined here, look for it in the
If the required function is not defined here, look for it in the
devices_access object
"""
return getattr(self.__devices_access, function_name)
......
......@@ -145,8 +145,8 @@ class Expose():
def get_user_app_settings(self, user_app_name):
"""
Called by the User Application.
Retrieves the parameters of channels and trigger used by the
particular User Application as well as length of the acquisition.
Retrieves the length of the acquisition and parameters of channels and
trigger used by the particular User Application.
:param user_app_name: name of the User Application
......@@ -235,10 +235,10 @@ class Expose():
def run(self):
"""
Called when the object of the class is created.
It listens in the loop for messages from
It listens for messages from
Device Applications (socket_ADC_listener),
User Applications (socket_user_listener)
and from Zeroconf (zeroconf_listener).
and from Zeroconf (zeroconf_listener) in the loop.
The monitor socket is used to monitor the state of ZeroMQ connection.
The message contains the name of the method to call. Since communication
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment