.. _utilities_prbs_reading:

=====================
Receiving PRBS Frames
=====================

PRBS receive paths verify stream data integrity and collect error counters
after a transport or processing chain.

When receive state should be visible to operators, GUIs, or remote clients
through the tree, PyRogue provides ``pyrogue.utilities.prbs.PrbsRx``. It wraps
the underlying ``rogue.utilities.Prbs`` checker and exposes the receive
counters as ``Variables``.

The direct ``rogue.utilities.Prbs`` form remains the smaller fit for scripts
and standalone graphs that only need a checker endpoint.

PRBS receive paths commonly check streams generated by FPGA firmware/VHDL
implementations.

Common Controls
===============

Most receive setups are shaped by:

- ``rxEnable``
  Enable or disable checking.
- ``checkPayload``
  Control whether payload contents are verified.
- ``width`` and ``taps``
  Match the generator or firmware PRBS settings.
- ``PrbsPair``
  Use this when one node should own both the transmit and receive wrappers for
  a loopback or paired-end validation setup.

The direct Rogue endpoint provides the lower-level receive-side methods such as
``getRxCount()``, ``getRxErrors()``, ``getRxBytes()``, ``setWidth(width)``, and
``setTaps(taps)``.

Using ``PrbsRx`` In A Tree
==========================

``pyrogue.utilities.prbs.PrbsRx`` is the tree-managed form of the PRBS
checker.

Use it when receive counters, payload-check settings, and link-health state
should be visible in the PyRogue tree. For loopback tests where both sides
should live under one node, ``pyrogue.utilities.prbs.PrbsPair`` packages the
same transmit and receive wrappers together.

Python Direct-Utility Example
=============================

.. code-block:: python

   import rogue.utilities as ru
   import rogue.utilities.fileio as ruf

   # Replay captured frames from file.
   fread = ruf.StreamReader()

   # Create PRBS checker endpoint.
   prbs = ru.Prbs()

   # Feed replayed stream into checker.
   prbs << fread

   # Replay full split-file sequence and wait for completion.
   fread.open("myFile.dat.1")
   fread.closeWait()

   # Summarize checker statistics.
   print(f"Received {prbs.getRxCount()} frames")
   print(f"Received {prbs.getRxErrors()} errors")

Python Tree-Managed Example
===========================

.. code-block:: python

   import pyrogue.utilities.fileio as puf
   import pyrogue.utilities.prbs as pup

   # Add tree-managed replay source and PRBS receiver.
   fread = puf.StreamReader()
   root.add(fread)

   prbs = pup.PrbsRx()
   root.add(prbs)

   # Route replayed stream into tree-managed PRBS checker.
   fread >> prbs

C++ PRBS Receiver Example
=========================

.. code-block:: cpp

   #include <rogue/utilities/fileio/StreamReader.h>
   #include <rogue/utilities/Prbs.h>

   namespace ru  = rogue::utilities;
   namespace ruf = rogue::utilities::fileio;

   // Create replay source and PRBS checker.
   auto fread = ruf::StreamReader::create();
   auto prbs  = ru::Prbs::create();

   // Feed replayed stream into checker.
   *prbs << fread;

   // Replay full split-file sequence and wait for completion.
   fread->open("myFile.dat.1");
   fread->closeWait();

   // Summarize checker statistics.
   printf("Received %u frames\n", prbs->getRxCount());
   printf("Received %u errors\n", prbs->getRxErrors());

Related Topics
==============

- :doc:`index`
- :doc:`writing`

API Reference
=============

- Python:

  - :doc:`/api/python/rogue/utilities/prbs/prbs`
  - :doc:`/api/python/pyrogue/utilities/prbs/prbsrx`
  - :doc:`/api/python/pyrogue/utilities/prbs/prbspair`

- C++:

  - :doc:`/api/cpp/utilities/prbs/prbs`