.. _dev_software:

Software
========

The REDAC's software stack drives a distributed and heterogenous system of computers.
Figure :numref:`fig-software-redac-schema` shows a high level overview of this
system.

.. _fig-software-redac-schema:
.. figure:: drawings/redac-software-block-diagram.png
   :alt: schema drawing

   Abstract software diagram of REDAC.
   
The purpose of this section is to give a quick overview about the particular parts
and to refer to their respective documentation.
The following sections will go top down.

Client Computers
----------------

On the customers or client computer, a small code is running, called the
*REST API client*. REDAC has an *OpenAPI* defined frontend which makes it
easy to explore the interaction methods programmatically and to generate client codes.

A reference implementation of this client is currently available in Python on the
official python package index at `anabrid-redac-client <https://pypi.org/project/anabrid-redac-client/>`_.
Getting this code started is part of the :ref:`first_steps` section in the users
guide. This code is supposed to be open sourced at Github. Further clients shall
be generated in more programming languages in order to make it easy to operate with
REDAC from various settings.

Software on the SuperController
-------------------------------

The *SuperController* is mastering the internal network (see also section :ref:`opnetwork`
in the operators guide). The name *SuperController* refers both to the physical server
as well as to a major software component which manages the embedded hybrid controllers.
See also section :ref:`opservices` in the operators manual for a description how to
manage this software from a devops perspective.

.. _redaccess:

Redaccess (Middleware)
......................

At the interface between the SC and the REDAC public access is a lot of middleware
codes which are not meant to be released as open source.  Most notable is the
*Redaccess* code. It orchestrates a dockerized infrastructure containing parts
such as the `Redis <https://redis.io/>`_ and `PostgreSQL <https://www.postgresql.org/>`_
databases or the `RabbitMQ <https://www.rabbitmq.com/>`_ broker. Furthermore, part
of the software stack is an OpenID provider (`Keycloak <https://www.keycloak.org/>`_),
all running on standard server hardware and software, see the operator's manual
on :ref:`opnetwork` for details.


..
   Two codes are notable:
   * The *Redaccess* code https://anabrid.dev/docs/private/redaccess/
   * The *Redacc* compiler https://anabrid.dev/docs/private/redacc/

REDAC is equipped with a number of supplementary software for monitoring or enhancing
user experience, such as a little landing website or a `JupyterHub <https://jupyter.org/hub>`_
instance. However, none of these services are part of the core functionality and
not neccessarily run on hardware directly related to REDAC.

.. _pybrid:

Pybrid Proxy
............

The REDAC-internal ethernet/IP network with its hunderds of microcontrollers is
centrally managed by the *Pybrid Proxy* software. The tasks of this software are
the following:

* Application level proxy which provides a single entrypoint at TCP port ``5732``
  speaking the firmware JSONL-protocol, effectively resembling a "big virtual
  hybrid controller". This means it has to distribute incoming queries to the
  relevant microcontrollers and collect their replies again.
* Doing all the bookkeeping and resolving logical device addresses (encoding their
  positiong in the connectivity graph) to physical devices (encoding their actual
  addressing in the digital network, i.e. by MAC and IP address).
* Zookeping: Monitoring and scanning available mREDACs or their microcontrollers,
  respectively. Ensuring the relevant firmware is available and updating it when
  needed. Steering the power and turning off parts of the system which are not
  needded. Monitoring their health for instance by polling the temperature sensors
  available in the system.
* Organization of *run groups* by means of steering a system wide digital bus which
  is currently USB-connected to the server.

Pybrid is written in asynchronous python and documented at
https://anabrid.dev/docs/pybrid/. The code forms the *digital frontend* 
to all analog circuitery. In regular use, this code should be the only software
which communicates with the embedded controllers directly.

.. _firmware:

Firmware on Microcontrollers
----------------------------

REDAC has a hierarchical design where on the lowest level (:ref:`mredac_architecture`)
there are microcontrollers (MCU) with similiar firmware images. The following diagram
:numref:`fig-firmware-redac-schema`
provides an overview of the firmware architecture, with a focus on the communication.

.. _fig-firmware-redac-schema:
.. figure:: drawings/modes-of-communication4.png
   :alt: schema drawing

   REDAC embedded hybrid controller firmware architecture

It is important to note that end users **never** directly communicate with the embedded
controllers. Even the direct contact to the SuperController is prohibited by the
intermediate software.
  
Despite the MCUs are actually interchangable, REDAC is equipped with 600Mhz 32bit ARM
Cortex-M7 single core 
`Teensy 4.1 development boards <https://www.pjrc.com/teensy/>`_. The firmware is
developed as a `PlatformIO <https://platformio.org/>`_ project and is huge: It contains
more then 20,000 lines of code in dozens of folders. The firmware has been
open sourced in the past at https://github.com/anabrid/lucidac-firmware/ and 
is intensively documented at https://anabrid.dev/docs/lucidac-firmware/sphinx/dirhtml/.