.. include:: ./../../macros.txt
.. include:: ./../../units.txt

.. _OPERATING_SYSTEM:

################
Operating System
################

Directory Structure
-------------------

The two available operating systems are placed in the `os` directory.
As |freertos| is the most common one, this will be described further.
|freertos| can have several addons.
They are located in the `freertos-plus` directory while the plain OS is located
in the `freertos` directory.

.. code-block::

   src
   └── os
        ├── freertos
        |       ├── freertos
        |       └── freertos-plus
        |               └── freertos-plus-tcp
        └── safertos

|freertos|
----------

Critical Sections
^^^^^^^^^^^^^^^^^

A critical section must be entered with the function ``OS_EnterTaskCritical()``
and exited with the function ``OS_ExitTaskCritical()``.

The operating system configuration can be found in the file
``FreeRTOSConfig.h``.
A detailed explanation of the parameters configured in this file is given at
https://www.freertos.org/a00110.html.
|ti-halcogen| generates the |freertos| sources on the fly during the build
process.
However, |foxbms| ships its own |freertos| source tree (in
``src/os/freertos``), and therefore the |freertos| sources generated by the
code generator are not needed and consequently removed.
Only the CPU clock frequency configured with |ti-halcogen| is extracted from
the generated |freertos| sources and written into
``config_cpu_clock_hz.h``, which is included in |foxbms|'s own
``FreeRTOSConfig.h``.

|tcp-ip-stack|
--------------

The |tcp-ip-stack| is the FreeRTOS-Plus-TCP Library configured for |foxbms|.
For the |tcp-ip| communication the |ti-tms570| uses the Ethernet Media Access
Controller (EMAC) to communicate with the ethernet Physical Layer Transceiver
(PHY).
In simplified form, the communication over the Physical and Data Link layers
flows as illustrated in :numref:`block-diagram-ethernet-communication`.

.. drawio-figure:: img/ethernet-communication.drawio
   :format: svg
   :alt: Block diagram of the ethernet communication
   :name: block-diagram-ethernet-communication
   :width: 130px

   Block diagram of the ethernet communication

In the case of foxBMS, the EMAC is embedded in the MCU and has two connections
to the PHY.
MDIO (Management Data Input/Output) is responsible for everything that is not
directly related to the data transfer such as configuring the PHY or
transmitting PHY-related errors.
The MII (Media Independent Interface) is then responsible for the actual data
transfer.
The EMAC acts in this case as DMA (Direct Memory Access) Master to
pass the data to the MCU where it is processed further.
To reference this, the |tcp-ip| communication is structured as shown in the
figure below.

.. drawio-figure:: img/os-tcp-structure.drawio
   :format: svg
   :alt: Software structure of the ethernet communication
   :name: tcp-structure
   :width: 130px

   Software structure of the ethernet communication

The related drivers are structured as in the physical structure.
The phy specific settings and configuration is made in the phy driver
``dp83869.c``.
Then in the next layer the :ref:`EMAC` driver controls the EMAC to transmit
and receive ethernet packages.
The EMAC is connected by hardware to the PHY.

The basic usage of the |tcp-ip-stack| with sending a ping signal is explained
in  :ref:`HOW_TO_TEST_TCP_IP`.

.. _OS_NETWORK_INTERFACE:

Network Interface
-----------------

The network interface connects the |tcp-ip-stack| with the hardware driver for
the |emac| and the PHY.
The detailed functionality is explained in :ref:`NETWORK_INTERFACE`.

Diagnostic
-----------------

The ``DIAG`` module is designed to report problems on the whole system.
The events that trigger the ``DIAG`` module have to be defined by the user.
The event handler ``DIAG_Handler()`` has to be called when the event is
detected.
The way the system reacts to a ``Diag`` event is defined via a callback
function or by the caller according the return value.


Data stored in the database
---------------------------

The following data is stored in the database:

  - Cell voltages
  - Cell temperatures
  - SOX (Battery state, contains e.g., State-of-Charge)
  - Balancing control
  - Balancing feedback
  - Current sensor measurements (includes pack voltages at different points)
  - Hardware information
  - Last state request made to the BMS
  - Minimum, maximum and average values for voltages and temperatures
  - Measurement from isolation monitor
  - Interface to communicate via I2C with extra functionalities on slave
    (e.g., EEPROM, port expander)
  - Result from open-wire check on slaves
  - Error state of the BMS (i.e. error flags, set to 0 or 1)
  - MSL, maximum safety limits
  - RSL, recommended safety limits
  - MOL, maximum operating limits
  - Calculated values for moving average
  - Contactor feedback
  - Interlock feedback
  - BMS state (e.g., standby, normal, charge, error)
  - Current limits calculated for State-of-Function
  - Voltages read on GPIOs of the slaves