Added Documentation

doc/architecture/SENSORFUSION.md

@@ -0,0 +1,72 @@
+# Radon Ulzer - SENSORFUSION <!-- omit in toc -->
+
+* [General](#general)
+  * [SerialMuxProt Channels](#serialmuxprot-channels)
+    * [Tx channel "LINE\_SENS"](#tx-channel-sensor_data)
+* [SW Architecture](#sw-architecture)
+  * [Logical View](#logical-view)
+    * [Application](#application)
+* [Abbreviations](#abbreviations)
+* [Issues, Ideas And Bugs](#issues-ideas-and-bugs)
+* [License](#license)
+* [Contribution](#contribution)
+
+# General
+
+The robot sends sensor data (Odometry data and IMU data) via SerialMuxProt. 
+
+On target the physical communication uses the serial.
+
+On simulation the physical communication uses a socket connection.
+
+## SerialMuxProt Channels
+
+
+### Tx channel "SENSOR_DATA"
+This channel is used to send raw sensor data used for Sensor Fusion on the ZumoComSystem.
+
+* The dataypes int16_t is used.
+* Order:
+  * Acceleration in X
+  * Acceleration in Y
+  * turnRateZ around Z
+  * Magnetometer value in X 
+  * Magnetometer value in Y 
+  * Angle calculated by Odometry
+  * Position in X calculated by Odometry
+  * Position in Y calculated by Odometry
+* Endianess: Big endian
+
+# SW Architecture
+The following part contains the specific details of the SensorFusion application.
+
+## Logical View
+
+### Application
+The application uses the same [State Machine](https://github.com/BlueAndi/RadonUlzer/blob/main/doc/architecture/LINEFOLLOWER.md) as the Line Follower Application.
+
+### HAL
+Some changes have been made to the HAL.
+![HALSensorFusion](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/BlueAndi/RadonUlzer/SensorFusion/doc/architecture/uml/LogicalView/SensorFusion/HAL_SensorFusion.puml)
+
+ButtonB, ButtonC, the ProximitySensor and the Buzzer have been removed. 
+An IMU has been added:
+![HALIMU](http://www.plantuml.com/plantuml/proxy?cache=no&src=https://raw.githubusercontent.com/BlueAndi/RadonUlzer/SensorFusion/doc/architecture/uml/LogicalView/SensorFusion/HAL_IMU.puml)
+
+# Abbreviations
+
+| Abbreviation | Description |
+| - | - |
+| HAL | Hardware Abstraction Layer |
+| IMU | Inertial Measurement Unit |
+
+# Issues, Ideas And Bugs
+If you have further ideas or you found some bugs, great! Create a [issue](https://github.com/BlueAndi/RadonUlzer/issues) or if you are able and willing to fix it by yourself, clone the repository and create a pull request.
+
+# License
+The whole source code is published under the [MIT license](http://choosealicense.com/licenses/mit/).
+Consider the different licenses of the used third party libraries too!
+
+# Contribution
+Unless you explicitly state otherwise, any contribution intentionally submitted for inclusion in the work by you, shall be licensed as above, without any
+additional terms or conditions.

doc/architecture/uml/LogicalView/SensorFusion/HAL_IMU.puml

@@ -0,0 +1,139 @@
+@startuml HAL IMU
+
+title Hardware Abstraction Layer - IMU
+
+package "HAL" as hal {
+
+    package "HAL Interfaces" as halInterfaces {
+        interface "IBoard" as iBoard {
+            + {abstract} getIMU() : IIMU&
+            + init() : void
+        }
+        interface "IIMU" as iIMU {
+            + {abstract} init() : bool
+            + {abstract} readAcc() : void
+            + {abstract} readGyro() : void
+            + {abstract} readMag() : void
+            + {abstract} accDataReady() : bool
+            + {abstract} gyroDataReady() : bool
+            + {abstract} magDataReady() : bool
+            + {abstract} getAccelerationValues(int16_t* accelerationValues) : void
+            + {abstract} getTurnRates(int16_t* turnRates) : void
+            + {abstract} getMagnetometerValues(int16_t* magnetometerValues) : void
+
+        }
+    }
+
+    package "HAL Simulation" as simulation {
+        class "IMU" as ImuSim {
+            -  m_accelerationValues[3] : int16_t
+            -  m_gyroValues[3] : int16_t
+            -  m_magnetometerValues[3] : int16_t
+            +  init() : bool
+            +  readAcc() : void
+            +  readGyro() : void
+            +  readMag() : void
+            +  accDataReady() : bool
+            +  gyroDataReady() : bool
+            +  magDataReady() : bool
+            +  getAccelerationValues(int16_t* accelerationValues) : void
+            +  getTurnRates(int16_t* turnRates) : void
+            +  getMagnetometerValues(int16_t* magnetometerValues) : void
+        }
+        class "Board" as BoardSim {
+            - m_imu : IMU
+            + getIMU() : IMU&
+            + init() : void
+        }
+    }
+
+    package "HAL Target" as target {
+        class "IMU" as ImuTarget {
+            -  m_accelerationValues[3] : vector<int16_t> 
+            -  m_gyroValues[3] : vector<int16_t> 
+            -  m_magnetometerValues[3] : vector<int16_t> 
+            +  init() : bool
+            +  readAcc() : void
+            +  readGyro() : void
+            +  readMag() : void
+            +  accDataReady() : bool
+            +  gyroDataReady() : bool
+            +  magDataReady() : bool
+            +  getAccelerationValues(int16_t* accelerationValues) : void
+            +  getTurnRates(int16_t* turnRates) : void
+            +  getMagnetometerValues(int16_t* magnetometerValues) : void
+        }
+        class "Board" as BoardTarget{
+            - m_imu : IMU
+            + getIMU() : IMU&
+            + init() : void
+        }
+    }
+    }
+    iIMU <|... ImuSim: <<realize>>
+    iBoard <|... BoardSim: <<realize>>
+    iBoard *-- iIMU
+
+    iIMU <|... ImuTarget: <<realize>>
+    iBoard <|... BoardTarget: <<realize>>
+
+
+package "Webots library"  as webotsLib {
+    class Accelerometer {
+        + getValues() : double *
+        + enable(int samplingPeriod) : void
+    }
+    class Gyro {
+        + getValues() : double *
+        + enable(int samplingPeriod) : void
+    }
+    class Compass {
+        + getValues() : double *
+        + enable(int samplingPeriod) : void
+    }
+}
+
+package "Zumo32U4 library"  as zumo32u4Lib {
+
+    class Zumo32U4IMU {
+        -  a[3] : vector<int16_t> 
+        -  g[3] : vector<int16_t> 
+        -  m[3] : vector<int16_t> 
+        +  init() : bool
+        +  readAcc() : void
+        +  readGyro() : void
+        +  readMag() : void
+        +  accDataReady() : bool
+        +  gyroDataReady() : bool
+        +  magDataReady() : bool
+    }
+}
+
+note bottom of zumo32u4Lib
+    Provided by Pololu.
+    https://pololu.github.io/zumo-32u4-arduino-library/index.html
+end note
+
+note bottom of webotsLib
+    Provided by Cyberbotics.
+    https://cyberbotics.com/doc/reference/thanks?version=R2023b
+end note
+
+ImuTarget *--> Zumo32U4IMU
+
+ImuSim *--> Accelerometer
+ImuSim *--> Gyro
+ImuSim *--> Compass
+
+note left of iIMU
+    IMU stands for Inertial Measurement Unit.
+end note
+
+note left of hal
+    This diagram shows the added IMU component.
+    Classes like the LineSensors or Motors
+    are missing.
+end note
+
+
+@enduml

doc/architecture/uml/LogicalView/SensorFusion/HAL_SensorFusion.puml

@@ -0,0 +1,161 @@
+@startuml HAL SensorFusion
+
+title Hardware Abstraction Layer - SensorFusion App
+
+package "HAL" as hal {
+
+    package "Interfaces" as halInterfaces {
+
+        interface "IButton" as iButton {
+            + {abstract} isPressed() : bool
+            + {abstract} waitForRelease() : void
+        }
+
+        interface "IEncoders" as iEncoders {
+            + {abstract} getCountsLeft() : int16_t
+            + {abstract} getCountsRight() : int16_t
+            + {abstract} getCountsAndResetLeft() : int16_t
+            + {abstract} getCountsAndResetRight() : int16_t
+            + {abstract} getResolution() const : uint16_t
+        }
+
+        interface "IDisplay" as iDisplay {
+            + {abstract} clear() : void
+            + {abstract} gotoXY(xCoord : uint8_t, yCoord : uint8_t) : void
+            + {abstract} print(str : const String&) : size_t
+            + {abstract} print(str : const char[]) : size_t
+            + {abstract} print(value : uint8_t) : size_t
+            + {abstract} print(value : uint16_t) : size_t
+            + {abstract} print(value : uint32_t) : size_t
+            + {abstract} print(value : int8_t) : size_t
+            + {abstract} print(value : int16_t) : size_t
+            + {abstract} print(value : int32_t) : size_t
+        }
+
+        interface "ILed" as iLed {
+            + {abstract} enable(enableIt : bool) : void
+        }
+
+        interface "ILineSensors" as iLineSensors {
+            + {abstract} init() : void
+            + {abstract} calibrate() : void
+            + {abstract} readLine() : int16_t
+            + {abstract} getSensorValues() : const uint16_t*
+            + {abstract} isCalibrationSuccessful() : bool
+            + {abstract} getCalibErrorInfo() const : uint8_t
+            + {abstract} getNumLineSensors() const : uint8_t
+            + {abstract} getSensorValueMax() const : uint16_t
+        }
+
+        interface "IMotors" as iMotors {
+            + {abstract} setSpeeds(leftSpeed : int16_t, rightSpeed : int16_t) : void
+            + {abstract} getMaxSpeed() const : int16_t
+        }
+
+        interface "IIMU" as iIMU {            
+            + {abstract} init() : bool
+            + {abstract} readAcc() : void
+            + {abstract} readGyro() : void
+            + {abstract} readMag() : void
+            + {abstract} accDataReady() : bool
+            + {abstract} gyroDataReady() : bool
+            + {abstract} magDataReady() : bool
+            + {abstract} getAccelerationValues(int16_t* accelerationValues) : void
+            + {abstract} getTurnRates(int16_t* turnRates) : void
+            + {abstract} getMagnetometerValues(int16_t* magnetometerValues) : void
+
+        }
+    }
+
+    class Board << namespace >> {
+        + getButtonA() : IButton&
+        + getDisplay() : IDisplay&
+        + getEncoders() : IEncoders&
+        + getLedRed() : ILed&
+        + getLedYellow() : ILed&
+        + getLedGreen() : iLed&
+        + getLineSensors() : ILineSensors&
+        + getMotors() : IMotors&
+        + getIMU() : IIMU&
+    }
+
+    class RobotConstants {
+        + GEAR_RATIO : uint32_t
+        + ENCODER_RESOLUTION : uint16_t
+        + WHEEL_DIAMETER : uint32_t
+        + WHEEL_CIRCUMFERENCE : uint32_t
+        + ENCODER_STEPS_PER_MM : uint32_t
+    }
+
+    note top of Board
+        Defines the physical board with all actor
+        and sensor instances. The application retrieves
+        every driver via the board.
+    end note
+
+    note top of RobotConstants
+        Provides robot specific constants, e.g. given by
+        mechanic parts.
+    end note
+
+    note top of iIMU
+        IMU stands for Inertial Measurement Unit.
+    end note
+
+    package "Target" as target {
+        class LineSensors
+        class ButtonA
+        class Motors
+        class Display
+        class Encoders
+        class LedRed
+        class LedYellow
+        class LedGreen
+        class IMU
+    }
+
+    iLineSensors <|... LineSensors: <<realize>>
+    iButton <|... ButtonA: <<realize>>
+    iMotors <|... Motors: <<realize>>
+    iDisplay <|... Display: <<realize>>
+    iEncoders <|... Encoders: <<realize>>
+    iLed <|... LedRed: <<realize>>
+    iLed <|... LedYellow: <<realize>>
+    iLed <|... LedGreen: <<realize>>
+    iIMU <|... IMU: <<realize>>
+}
+
+package "Zumo32U4 library"  as zumo32u4Lib {
+    class Zumo32U4LineSensors
+    class Zumo32U4ButtonA
+    class Zumo32U4Motors
+    class Zumo32U4LCD
+    class Zumo32U4Encoders
+    class Zumo32U4IMU
+    class Zumo32U4 <<Functions>>
+}
+
+note bottom of zumo32u4Lib
+    Provided by Pololu.
+    https://pololu.github.io/zumo-32u4-arduino-library/index.html
+end note
+
+halInterfaces -[hidden]-- hal
+hal -[hidden]-- zumo32u4Lib
+
+LineSensors *--> Zumo32U4LineSensors
+ButtonA *--> Zumo32U4ButtonA
+Motors *--> Zumo32U4Motors
+Display *--> Zumo32U4LCD
+Encoders *--> Zumo32U4Encoders
+IMU *--> Zumo32U4IMU
+LedRed ..> Zumo32U4: <<use>>
+LedYellow ..> Zumo32U4: <<use>>
+LedGreen ..> Zumo32U4: <<use>>
+
+note bottom of hal
+    The hardware abstraction layer contains
+    all drivers, provided by the Pololu Library.
+end note
+
+@enduml