Add error handling and reporting documentation

and fix links from the main.dox page

src/hal/adc.h

@@ -1,9 +1,9 @@
 #pragma once
 #include <stdint.h>
 
-/// Hardware Abstraction Layer for the ADC's
-
 namespace hal {
+
+/// Hardware Abstraction Layer for the ADC's
 namespace adc {
 
 /// ADC access routines

src/hal/cpu.h

@@ -1,8 +1,8 @@
 #pragma once
 
-/// Hardware Abstraction Layer for the CPU
-
 namespace hal {
+
+/// Hardware Abstraction Layer for the CPU
 namespace cpu {
 
 #ifndef F_CPU

src/hal/eeprom.h

@@ -2,9 +2,10 @@
 #include <stdint.h>
 
 namespace hal {
-namespace eeprom {
 
 /// EEPROM interface
+namespace eeprom {
+
 class EEPROM {
 public:
     using addr_t = uint16_t;

src/hal/gpio.h

@@ -6,6 +6,8 @@
 #endif
 
 namespace hal {
+
+/// GPIO interface
 namespace gpio {
 
 struct GPIO_TypeDef {

src/hal/shr16.h

@@ -3,7 +3,6 @@
 #include <stdint.h>
 
 namespace hal {
-namespace shr16 {
 
 /// 16bit shift register (2x74595) interface
 ///
@@ -36,6 +35,8 @@ namespace shr16 {
 ///
 /// SHR16_DIR_MSK = (SHR16_DIR_0 + SHR16_DIR_1 + SHR16_DIR_2)
 /// SHR16_ENA_MSK = (SHR16_ENA_0 + SHR16_ENA_1 + SHR16_ENA_2)
+namespace shr16 {
+
 class SHR16 {
 
 public:

src/hal/spi.h

@@ -2,10 +2,11 @@
 #include <inttypes.h>
 #include "gpio.h"
 
-/// SPI interface
-
 namespace hal {
+
+/// SPI interface
 namespace spi {
+
 struct SPI_TypeDef {
     volatile uint8_t SPCRx;
     volatile uint8_t SPSRx;

src/hal/timers.h

@@ -1,11 +1,10 @@
 #pragma once
 
-/// Hardware Abstraction Layer for the CPU's features and peripherals
-
 namespace hal {
+
+/// Hardware Abstraction Layer for the CPU's internal timers
 namespace timers {
 
-/// timers
 void ConfigureTimer(uint8_t timer /* some config struct */);
 void StartTimer(uint8_t timer);
 void StopTimer(uint8_t timer);

src/hal/usart.h

@@ -4,11 +4,11 @@
 #include "gpio.h"
 #include "circular_buffer.h"
 
+namespace hal {
+
 /// USART interface
 /// @@TODO decide, if this class will behave like a singleton, or there will be multiple classes
 /// for >1 USART interfaces
-
-namespace hal {
 namespace usart {
 
 constexpr uint16_t UART_BAUD_SELECT(uint32_t baudRate, uint32_t xtalCpu) {

src/hal/watchdog.h

@@ -1,8 +1,8 @@
 #pragma once
 
-/// Hardware Abstraction Layer for the CPU's features and peripherals
-
 namespace hal {
+
+/// Hardware Abstraction Layer for the CPU's internal watchdog
 namespace watchdog {
 
 /// watchdog interface

src/main.dox

@@ -39,37 +39,37 @@
 ///digraph architecture {
 ///    node [shape=record, fontname=Helvetica, fontsize=10];
 ///    subgraph cluster_main { label="main"
-///         main [ URL="\ref main"];
+///         main [ URL="main.cpp"];
 ///     }
 ///    subgraph cluster_logic { label="logic"
 ///         logic [ URL="\ref logic"];
 ///     }
 ///
 ///    subgraph cluster_modules { label="modules"
-///         buttons [ URL="\ref buttons"];
-///         debouncer [ URL="\ref debouncer"];
-///         finda [ URL="\ref finda"];
-///         fsensor [ URL="\ref fsensor"];
-///         globals [ URL="\ref globals"];
-///         idler [ URL="\ref idler"];
-///         leds [ URL="\ref leds"];
-///         selector [ URL="\ref selector"];
-///         motion [ URL="\ref motion"];
-///         permanent_storage [ URL="\ref permanent_storage"];
-///         protocol [ URL="\ref protocol"];
-///         timebase [ URL="\ref timebase"];
+///         buttons [ URL="\ref modules::buttons"];
+///         debouncer [ URL="\ref modules::debounce"];
+///         finda [ URL="\ref modules::finda"];
+///         fsensor [ URL="\ref modules::fsensor"];
+///         globals [ URL="\ref modules::globals"];
+///         idler [ URL="\ref modules::idler"];
+///         leds [ URL="\ref modules::leds"];
+///         selector [ URL="\ref modules::selector"];
+///         motion [ URL="\ref modules::motion"];
+///         permanent_storage [ URL="\ref modules::permanent_storage"];
+///         protocol [ URL="\ref modules::protocol"];
+///         timebase [ URL="\ref modules::time"];
 ///     }
 ///    subgraph cluster_hal { label="hal"
-///         adc [ URL="\ref adc"];
-///         cpu [ URL="\ref cpu"];
-///         eeprom [ URL="\ref eeprom"];
-///         gpio [ URL="\ref gpio"];
-///         shr16 [ URL="\ref shr16"];
-///         spi [ URL="\ref spi"];
-///         timers [ URL="\ref timers"];
-///         tmc2130 [ URL="\ref tmc2130"];
-///         usart [ URL="\ref usart"];
-///         watchdog [ URL="\ref watchdog"];
+///         adc [ URL="\ref hal::adc"];
+///         cpu [ URL="\ref hal::cpu"];
+///         eeprom [ URL="\ref hal::eeprom"];
+///         gpio [ URL="\ref hal::gpio"];
+///         shr16 [ URL="\ref hal::shr16"];
+///         spi [ URL="\ref hal::spi"];
+///         timers [ URL="\ref hal::timers"];
+///         tmc2130 [ URL="\ref hal::tmc2130"];
+///         usart [ URL="\ref hal::usart"];
+///         watchdog [ URL="\ref hal::watchdog"];
 ///     }
 ///    main -> logic [ arrowhead="open" ];
 ///
@@ -112,6 +112,53 @@
 /// The good news is that the Slicer's MMU code is fully backwards compatible.
 ///
 ///
+///@section errors_sec Error sources and handling
+///
+/// There are several different types/sources of errors in the MMU:
+/// - runtime sensors
+/// - algorithmic errors
+/// - hardware component failures
+///
+/// For a list of currently supported error states please see error_codes.h .
+///
+///@subsection runtime_ssec Runtime sensors
+///
+/// Errors like this are abnormal operational states resulting from the fact, that some of the sensors didn't report an expected state.
+/// E.g. FINDA didn't trigger or the printer didn't send a trigger command from its filament sensor.
+/// These failures cannot be predicted and can be only resolved partially by the MMU.
+///
+/// The logic layer state machines check for these failures and act upon:
+/// - Cut filament: detects FINDA_DIDNT_SWITCH_OFF, FINDA_DIDNT_SWITCH_ON
+/// - Eject filament: detects FINDA_DIDNT_SWITCH_OFF, FINDA_DIDNT_SWITCH_ON
+/// - Load filament: detects FINDA_DIDNT_SWITCH_ON, FSENSOR_DIDNT_SWITCH_ON
+/// - Tool change: detects FINDA_DIDNT_SWITCH_OFF/FINDA_DIDNT_SWITCH_ON, FSENSOR_DIDNT_SWITCH_OFF/FSENSOR_DIDNT_SWITCH_ON
+/// - Load filament: detects FINDA_DIDNT_SWITCH_OFF, FSENSOR_DIDNT_SWITCH_OFF
+///
+///@subsection algorithmic_ssec Algorithmic errors
+///
+/// This kind of errors represents unhandled states of state machines - which should not happen ;)
+/// or at least the ocurrance can be mitigated by careful testing of the firmware code base.
+/// Logic layer state machines check their internal state and if they by chance get into an unhandled state,
+/// they switch into an error state INTERNAL.
+///
+///@subsection hardware_ssec Hardware failures
+///
+/// This kind of errors is extremely hard to tackle in full scale.
+/// Basically any HW component can fail (including the HW chips on the mainboard) and we only have limited knowledge about such situations.
+/// So under hardware failures we consider only stuff which can be detected by any means
+/// - mostly CPU peripherals, especially the TMC2130 drivers, which are capable of some degree of error reporting.
+///
+///@subsection errorrep_ssec Error reporting
+///
+/// There are basically 2 ways of reporting an error to the user
+/// - via USART communication with the printer - implies the communication works - the preferred way
+/// - LEDs blinking - implies the shift registers work and the LEDs work as well - backup way
+///
+/// The USART communication can report errors of the currently running command (see response to Q0).
+///
+/// LEDs' blinking is to be defined yet, the previous firmware used elaborate blinking schemes to report all kinds of errors which most users were unable to decipher/act upon.
+///
+///
 ///@section tests_sec Tests and quality assurance
 ///
 ///@subsection unit_sec Unit tests