Metadata-Version: 2.1
Name: trbnet
Version: 1.0.4
Summary: Interface to TrbNet (wrapping libtrbnet.so with ctypes)
Home-page: https://github.com/pklaus/pytrbnet
Author: Philipp Klaus
Author-email: klaus@physik.uni-frankfurt.de
License: GPL
Keywords: TrbNet PyTrbNet FPGA Low-latency network wrapper
Platform: Linux
Classifier: Development Status :: 4 - Beta
Classifier: Operating System :: OS Independent
Classifier: License :: OSI Approved :: GNU General Public License v3 or later (GPLv3+)
Classifier: Programming Language :: Python
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Scientific/Engineering :: Physics
Classifier: Topic :: Scientific/Engineering :: Interface Engine/Protocol Translator
Classifier: Topic :: System :: Hardware :: Hardware Drivers
Requires-Dist: lxml
Requires-Dist: click
Requires-Dist: enum34 ; python_version < "3.4"

PyTrbNet
========

This is a Python package wrapping libtrbnet.so. It allows accessing
trbnet registers from Python.

The package comes with two additional features:

-  XmlDb support. Allows to query registers by their name as specified
   in the corresponding xml file.
-  PCASpy-based EPICS IOC providing TrbNet register status information
   to the EPICS detector control system.

Installation
~~~~~~~~~~~~

This package can be installed from the Python Package Index via:

::

   pip install trbnet

Configuration / Setup
~~~~~~~~~~~~~~~~~~~~~

As this Python package depends on the shared library libtrbnet.so for
the communication with TrbNet, its location needs to be provided. This
can be done by setting the environment variable ``LIBTRBNET``.

libtrbnet.so in turn requires the environment variables ``DAQOPSERVER``
(if talking to TrbNet via a trbnetd daemon) or the IP of a TRB Board:
``TRB3_SERVER`` (if talking to TrbNet directly).

A fourth environment variable ``XMLDB`` comes into play, if the xmldb
capabilities of this Python package are to be used. It should point to
the location of the xml-db for your system.

Those environment variables can also be set from within Python with
their lowercase variants ``libtrbnet``, ``daqopserver``, and
``trb3_server`` upon instantiating the TrbNet() class.

Here’s an example using environment variables in the shell:

.. code:: sh

   # Setting the relevant environment variables
   export LIBTRBNET=/local/gitrepos/trbnettools/trbnetd/libtrbnet.so
   export DAQOPSERVER=jspc55.x-matter.uni-frankfurt.de:1
   export XMLDB=~/phd/workrepos/daqtools/xml-db/database

   # example call to get the value in the compile time
   # register for all reachable TRBs:
   trbcmd.py xmlget 0xffff TrbNet CompileTime

   # With the environment variables set, you could also
   # run Python and nstantiate TrbNet(). It would
   # pick up the settings from the exported variables.

or by setting the variables from within Python:

.. code:: python

   import os
   from trbnet import TrbNet

   lib = '/local/gitrepos/trbnettools/trbnetd/libtrbnet.so'
   host = 'trbnetd_host:8888'
   t = TrbNet(libtrbnet=lib, daqopserver=host)
   # 0x40 is the register address of CompileTime
   t.register_read(0xffff, 0x40)

Usage with Python
~~~~~~~~~~~~~~~~~

To read the content of the register address 0x0 for all connected TrbNet
boards (broadcast address 0xffff), do:

.. code:: python

   import os
   from trbnet import TrbNet

   t = TrbNet()

   response = t.register_read(0xffff, 0x0)
   for endpoint in response:
       print("endpoint 0x{:08X} responded with: 0x{:08X}".format(endpoint, response[endpoint]))

The TrbNet() class has the following methods:

-  ``register_read(trb_address, reg_address)``
-  ``register_write(trb_address, reg_address, value)``
-  ``register_read_mem(trb_address, reg_address, option, size)``
-  ``read_uid(trb_address)``
-  ``trb_set_address(uid, endpoint, trb_address)``
-  and some more less frequently used methods (found in the source code
   of `trbnet/core/lowlevel.py <trbnet/core/lowlevel.py>`__).

Usage of the Terminal Utility trbcmd.py
~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~~

The package comes with a simple command line utility called
``trbcmd.py``. It is a Python counterpart for the trbcmd utility
provided by trbnettools.

What it can do:

**read register values**

::

   trbcmd.py r 0xffff 0x0

**read memory (subsequent register addresses)**

Read three registers starting at 0x8005 from all boards:

::

   trbcmd.py rm 0xffff 0x8005 0x3 0x0

**xml-db queries**

Ask all TrbNet nodes (broadcast 0xffff) for the register value of
CompileTime as set in TrbNet.xml:

::

   trbcmd.py xmlget 0xffff TrbNet       CompileTime

Resources
~~~~~~~~~

-  `The TRB Website <http://trb.gsi.de>`__
-  `TrbNet
   Manual <http://jspc29.x-matter.uni-frankfurt.de/docu/trbnetdocu.pdf>`__


