Developer Guide

As described in Introduction, DO currently supports two types of User Applications:

  • GUI
  • testbench

and one type of Device Application available:

Depending on the needs of the user, different applications could be developed. To do this, the following tasks have to be performed:

  • write application-specific code
  • update or add a new model of the application in the Server
  • establish communication with the Server using the existing interface and if necessary, update the interface

The section explains 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.

Communication in the DO

The schematics of the communication patterns used in the Distributed Oscilloscope are presented in Fig. 13.

alternate text

Fig. 13 Schematics of communications patterns in the Distributed Oscilloscope

In the Distributed Oscilloscope, there are two messaging patterns used to communicate the nodes:

  • request/reply pattern
  • publisher/subscriber pattern

Request/reply pattern is used to implement Remote Procedure Calls (RPC), which allow controlling the behavior of other application in a reliable way. The User Applications control the behavior of the Distributed Oscilloscope, using a Server as a proxy. Therefore, the User Applications send RPC request to 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 User Applications.

There are two ways of providing 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 Fig. 13.
  • 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.

When implementing the Interfaces for new applications, the communication patterns should not be changed.

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 Interfaces.

User Application model

The User Applications model is similar to a standard oscilloscope. The functionality of the User Applications depends on the changes made in the model, that is:

  • channels selection
  • triggers selection
  • acquisition settings (e.g. length of acquisition, position of the trigger…)

There are no foreseen changes in the User Application model when adding a new User Application.

New applications should make use of the Server Interface and implement the User Application Interface.

Device Application model

The Device Application model reflects the functionalities of the particular device. In case of the ADC, the functionalities are the following:

  • channels settings
  • triggers settings
  • 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, Device Application Interface and Server Interface should be modified.

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 a new application, they should be modified.

Server Interface

Todo

Since currently the only available device is and ADC, the interface provides functions for interaction with ADCs. If in the future other types of devices will be supported, the interface should be made more general or extended.

expose.py

Exposes the functionalities of the Server to Device Applications and to User Applications. All communication with other applications is done using the Expose class. For communication with the nodes it uses ZeroMQ sockets.

class server.expose.Expose(connection_manager, port_user, port_device)[source]

Top level class.

Parameters:
  • connection_managerConnectionManager
  • port_user – port on which it listens for User Applications connections
  • port_device – port on which it listens for devices connections
add_channel(oscilloscope_channel_idx, unique_ADC_name, ADC_channel_idx, user_app_name)[source]

Called by the User Application. Adds channel in the User Application.

Parameters:
  • oscilloscope_channel_idx – index of the channel in the user application
  • unique_ADC_name – name of the Device Application (ADC)
  • ADC_channel_index – channel index of the ADC
  • user_app_name – name of the User Application
remove_channel(oscilloscope_channel_idx, user_app_name)[source]

Called by the User Application. Removes channel from the User Application.

Parameters:
  • oscilloscope_channel_idx – index of the channel in the user application
  • user_app_name – name of the User Application
add_trigger(type, unique_ADC_name, ADC_trigger_idx, user_app_name)[source]

Called by the User Application. Adds trigger in the User Application.

Parameters:
  • type – type of the trigger
  • unique_ADC_name – name of the Device Application (ADC)
  • ADC_trigger_index – trigger index of the ADC
  • user_app_name – name of the User Application
remove_trigger(user_app_name)[source]

Called by the User Application. Removes trigger from the User Application.

Parameters:user_app_name – name of the User Application
set_ADC_parameter(parameter_name, value, unique_ADC_name, idx=None)[source]

Called by the User Application. Generic function, used to modify parameters of the ADC.

Parameters:
  • parameter_name – name of the parameter to be modified
  • value – new value of the parameter
  • unique_ADC_name – name of the Device Application (ADC)
  • idx – index of the given parameter if applies
single_acquisition(user_app_name)[source]

Called by the User Application. Starts single acquisition in the given User Application.

Parameters:user_app_name – name of the User Application
run_acquisition(run, user_app_name)[source]

Called by the User Application. Starts or stops continuous acquisition in the given User Application.

Parameters:
  • run – defines if the acquisition is to be started or stopped
  • user_app_name – name of the User Application
set_pre_post_samples(presamples, postsamples, user_app_name)[source]

Called by the User Application. Defines he number of presamples and postsamples that are to be set in all ADCs used by the given User Application.

Parameters:
  • presamples – number of presamples
  • postsamples – number of postsamples
  • user_app_name – name of the User Application
get_user_app_settings(user_app_name)[source]

Called by the User Application. Retrieves the length of the acquisition and parameters of channels and trigger used by the particular User Application.

Parameters:user_app_name – name of the User Application
Returns:Dictionary with required settings
register_user_app(user_app_name, addr, port)[source]

Called by the User Application. Registers User Application in the Distributed Oscilloscope.

Parameters:
  • addr – IP address of the socket of the User Application
  • port – port of the socket of the User Application
  • user_app_name – name of the User Application
unregister_user_app(user_app_name)[source]

Called by the User Application. Unregisters User Application in the Distributed Oscilloscope.

Parameters:user_app_name – name of the User Application
update_data(timestamp, pre_post, data, unique_ADC_name)[source]

Called by the Device Application.

Adds the acquisition data to the acquisition data queue in the ADC. Every time the new data arrives, the ADC notifies the User Application class, which checks if all rrequired data has arrived and is properly aligned. If yes, it sends the data to the actuall User Application.

Parameters:
  • timestamp – timestamp with the information about the time of the trigger
  • pre_post – number of acquired presamples and postsamples
  • data – dictionary with ADC channels indexes as keys, containing acquisition data
  • unique_ADC_name – name of the Device Application (ADC)
register_ADC(unique_ADC_name, addr, port)[source]

Called by the Device Application. Registers Device Application (ADC) in the Distributed Oscilloscope.

Parameters:
  • unique_ADC_name – name of the Device Application (ADC)
  • addr – IP address of the socket of the Device Application (ADC)
  • port – port of the socket of the Device Application (ADC)
unregister_ADC(unique_ADC_name)[source]

Called by the Device Application. Unregisters ADC in the Distributed Oscilloscope.

Parameters:unique_ADC_name – name of the Device Application (ADC)
run()[source]

Called when the object of the class is created. It listens for messages from Device Applications (socket_ADC_listener), User Applications (socket_user_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 with the User Applications is synchronous, the socket_user_listener sends back the data returned by the called funciton. In case of socket_ADC_listener and zeroconf_listener the communication is asynchronous

User Application Interface

The following methods are used to receive information about the availability of the devices and the data.

class applications.pyqt_app.GUI.GUI_Class(ui, zmq_rpc, GUI_name)[source]
register_ADC(unique_ADC_name, number_of_channels)[source]

Registers a new ADC.

Parameters:
  • unique_ADC_name – name of the Device Application (ADC)
  • number_of_channels – number of channels in the ADC
unregister_ADC(unique_ADC_name)[source]

Unregisters an ADC.

Parameters:unique_ADC_name – name of the Device Application (ADC)
set_ADC_available(unique_ADC_name)[source]

Makes the ADC available when other Application stops using this ADC.

Parameters:unique_ADC_name – name of the Device Application (ADC)
set_ADC_unavailable(unique_ADC_name)[source]

Makes the ADC unavailable when other Application uses this ADC.

Parameters:unique_ADC_name – name of the Device Application (ADC)
update_data(data, pre_post_samples, offsets)[source]

It is used to send the acquisition data from the Server to the User Application and, depeneding on requirements of the Application, process or display the data. In case of the GUI, the data is displayed.

Parameters:
  • data – dictionary with GUI channels indexes as keys, containing acquisition data
  • pre_post_samples – number of acquired presamples and postsamples
  • offsets – difference betwenn the timestamps of the channels, with respect to the first channel – this information is used to realign the data if for any reason the value of the timestamp is not the same

Device Application Interface

class nodes.adc_lib_node.server_expose.ServerExpose(port, port_server, pci_addr, trtl, unique_ADC_name)[source]
__getattr__(function_name)[source]

If the required function is not defined here, look for it in the devices_access object

set_server_address(addr)[source]

If address of the Server is provided by the user, this function is called from main. If address of the Server is discovered by zeroconf, this function is called by RPC call from the Server. It creates the Publisher object used for sending the notifications and acquisition data to the Server.

Parameters:addr – address of the Server
class nodes.adc_lib_node.devices_access.DevicesAccess(pci_addr, trtl, unique_ADC_name)[source]
set_user_app_name(user_app_name)[source]

Sets the name of the User Application – this name is used to distinguish WRTD rules.

Parameters:user_app_name – Name of the User Application
set_WRTD_master(WRTD_master, trigger_type=None, ADC_trigger_idx=None)[source]

Defines if particular device works as master or slave. The master distributes the triggers, the slave receives the triggers.

Master mode:

  • enables the selected trigger
  • adds WRTD rule to distribute timestamps
  • modifies the number of presmaples and postsamples to align data from various ADCs

Slave mode:

  • disables all triggers
  • adds WRTD rule to receive timestamps
  • modifies the number of presmaples and postsamples to align data from various ADCs
Parameters:
  • WRTD_master – if True device works as master, if False device works as slave
  • trigger_type – in master mode defines the type of the trigger to enable
  • ADC_trigger_idx – in master mode defines the index of the trigger to enable
configure_adc_parameter(function_name, *args)[source]

Generic function to modify the ADC parameters.

Parameters:
  • function_name – the name of the function, which modifies particular ADC parameter
  • args – arguments passed to the function – the type of arguments depends on the selected function
get_current_adc_conf()[source]

Retrieves the configuration of the ADC.

Returns:Dictionary with ADC configurations
configure_acquisition(channels)[source]

Configures single acquisition.

Parameters:channels – list of channels indexes from which the data should be retrieved
run_acquisition(run, channels=None)[source]

Starts or stops continuous acquisition.

Parameters:
  • run – if True start acquisition, if False stop acquisition
  • channels – list of channels indexes from which the data should be retrieved