=====================
Software Architecture
=====================

Our autonomous system operates on Ubuntu 20.04 with ROS2 Foxy. Our pipeline uses a distributed node-based approach where individual components communicate through the ROS2 middleware, enabling scalable and maintainable system design.

System Overview
---------------

.. image:: ../images/data-flow.png
  :alt: Data Flow Graph
  :width: 650px

Node Architecture
-----------------

Our software follows the standard ROS2 publisher-subscriber communication pattern:

**Publishers**

* Sensor nodes publish raw data to specific topics
* Processing nodes publish filtered/processed data
* Control nodes publish command messages

**Subscribers**

* Processing nodes subscribe to sensor data topics
* Decision-making nodes subscribe to processed data

This decoupled architecture allows nodes to be developed, tested, and deployed independently while maintaining system-wide coordination.

Startup Procedure
-----------------

The system launches automatically when the vehicle's low voltage (LV) system powers the compute unit:

1. **Power-On**: LV system activates, powering the compute
2. **Boot Sequence**: Ubuntu 20.04 loads and initializes
3. **Cron Launch**: System startup triggers cron job on @reboot
4. **Tmux Session**: Main software pipeline launches in a tmux session
5. **Node Initialization**: All ROS2 nodes start in predetermined order
6. **System Ready**: Heartbeat monitoring begins once all nodes are active

The cron job ensures the system launches reliably without manual intervention, while tmux provides session persistence and easy debugging access.

Heartbeat System
----------------

Since any node failure during autonomous driving is run-ending, our heartbeat architecture focuses solely on ensuring reliable system state prior to ready-to-drive (RTD):

**Monitoring Cycle**

* Heartbeat pulses every 5 seconds
* Checks for node presence in ROS2 graph
* Verifies active publishing on expected topics
* Restarts failed nodes automatically

**Pseudocode Reference**

.. code-block:: text

  HEARTBEAT MONITOR:
  
  REPEAT every 5 seconds:
      FOR each critical node:
          IF node does not exist in ROS2 graph:
              Log error message
              Restart the node
              Continue to next node
          
          FOR each expected topic from this node:
              IF topic is not publishing data:
                  Log error message
                  Restart the node
                  Break out of topic loop
      
      Log "All nodes healthy" message
  
  
  RESTART NODE PROCEDURE:
      Log restart message
      Kill the node process
      Wait 2 seconds for cleanup
      Launch the node again
  
  
  CHECK NODE EXISTS:
      Get list of all active nodes
      Return true if node name is in the list
  
  
  CHECK TOPIC PUBLISHING:
      Echo topic to see if it has received messages recently
      Return true if message rate is greater than 0

This monitoring system ensures a reliable boot prior to RTD, allowing for safe and reliable remote startup.

===================
More CMR Driverless
===================

.. _CMR Driverless Landing page: https://cmr.red/driverless-docs

Back to `CMR Driverless Landing page`_.

.. _Perceptions Pipeline: https://cmr.red/perceptions-docs

Learn more about the `Perceptions Pipeline`_.

.. _Path Planning Pipeline: https://cmr.red/planning-docs

Learn more about the `Path Planning Pipeline`_.

.. _Controls Pipeline: https://cmr.red/controls-docs

Learn more about the `Controls Pipeline`_.

.. _DV Mechanical Pipeline: https://cmr.red/mech-docs

Learn more about the `DV Mechanical Pipeline`_.

.. _DV Electrical Pipeline: https://cmr.red/elec-docs

Learn more about the `DV Electrical Pipeline`_.