.. pyqcc documentation master file, created by
   sphinx-quickstart on Fri May  3 09:36:03 2024.
   You can adapt this file completely to your liking, but it should at least
   contain the root `toctree` directive.

pyqcc's documentation!
======================

.. toctree::
   :maxdepth: 2
   :caption: Contents:



Indices and tables
==================

* :ref:`genindex`
* :ref:`Device class reference`
* :ref:`Usage examples`
* :ref:`Command Line Interface`
* :ref:`search`

.. _Device class reference:

Device class reference
====================================

.. autoclass:: pyqcc.cmdctrl.device
   :members:
   :show-inheritance:

.. _Usage examples:

Usage examples
==============

In the examples we are using a serial device on COM3, initialized as ``qccdev`` and used in the following examples.

Initialize the device
---------------------
.. code-block:: python

   import pyqcc

   qccdev = pyqcc.cmdctrl.device("serial","COM3")


Read device info
----------------
.. code-block:: python

   info = qccdev.get_info()
   if(info):
      print("Device info read successful")
      print(" Core version: {}.{}".format(info['core_version'] >> 16, info['core_version'] & 0xffff) )
      print(" SW version: {}.{}".format(info['sw_version'] >> 16, info['sw_version'] & 0xffff) )
      print(" Serial: {}".format(info['serial'].decode("utf-8")))
      print(" HW info: {}".format(info['hw_info'].decode("utf-8")))
   else:
      print("Error reading info")


Read device status
------------------
.. code-block:: python

   status = qccdev.get_status()
   if(status):
      print("Device status read successful")
      print(" started: {}".format(status['started']) )
      print(" startup_test_in_progress: {}".format(status['startup_test_in_progress']) )
      print(" voltage_low: {}".format(status['voltage_low']) )
      print(" voltage_high: {}".format(status['voltage_high']) )
      print(" voltage_undefined: {}".format(status['voltage_undefined']) )
      print(" bitcount: {}".format(status['bitcount']) )
      print(" repetition_count: {}".format(status['repetition_count']) )
      print(" adaptive_proportion: {}".format(status['adaptive_proportion']) )
      print(" Ready bytes: {}".format(status['ready_bytes']) )
   else:
      print("Error reading status")


Read random bytes in one shot mode
----------------------------------
.. code-block:: python

   # Read 64 bytes
   rnd_bytes = qccdev.start_one_shot(64)
   if(rnd_bytes):
      #Print random bytes in hexadecimal format
      print(rnd_bytes.hex())
   else:
      print("Error reading random bytes")


Read random bytes in continuous mode
------------------------------------
.. code-block:: python

   if(qccdev.start_continuous()):
      print("Continuous mode started!")
      # Read 1MB random data
      rnd_bytes = qccdev.read_continuous(1000000)
      if(rnd_bytes):
         #print first and last random bytes
         print("Continuous read success! {:02X}..{:02X}".format(rnd_bytes[0], rnd_bytes[-1]))
      else:
         print("Error continuous read")
      # Stop continuous mode
      if(qccdev.stop()):
         print("Continuous mode Stopped!")
      else:
         print("Stop error!")
   else:
      print("Error starting continuous mode")


.. _Command Line Interface:

Command Line Interface
======================
``pyqcc-cli`` is the command line tool (installed with the package) that allows the user to utilise the QRNG device in a simple and intuitive way. 
See below for the detailed help of the command: ::

   usage: pyqcc-cli [-h] [-i {serial,udp,tcp,tcpudp}] [-d DEVICE] [-s] [-g] [-t] [-r READ_SIZE] [-R SIGNED_READ_SIZE] [-o OUTPUT_FILE] [-a] [--start]
                  [--read-block-size READ_BLOCK_SIZE] [--stop] [--info] [--update UPDATE_FILE] [-v]

   QRNG Command and Control protocol host utility

   optional arguments:
   -h, --help            show this help message and exit
   -i {serial,udp,tcp,tcpudp}, --interface {serial,udp,tcp,tcpudp}
                           Communication interface (default: serial
   -d DEVICE, --device DEVICE
                           Device interface name or IP (default: /dev/ttyACM0)
   -s, --get-status      Get current QRNG configuration
   -g, --get-config      Get current QRNG configuration
   -t, --get-statistics  Get QRNG statistics
   -r READ_SIZE, --read READ_SIZE
                           One shot read
   -R SIGNED_READ_SIZE, --signed-read SIGNED_READ_SIZE
                           Signed read
   -o OUTPUT_FILE, --output-file OUTPUT_FILE
                           Output file (used with -r, --read)
   -a, --append          Append to output file (used with -o, --output-file)
   --start               Start continuous mode, if -r is used: read in continuous mode
   --read-block-size READ_BLOCK_SIZE
                           Read block size, how many bytes read for every cycle (continuous mode only)
   --stop                Stop continuous mode
   --info                Get device information
   --update UPDATE_FILE  FW update, image file
   -v, --verbose         Print debug information