Create basic FW structure

- Design API's based on our discussion and block diagrams
- Set doxygen rules/preferred syntax

src/hal/_rules.txt

@@ -0,0 +1,4 @@
+Use a class whenever you need to store some context data along with the functions manipulating the HW peripherals.
+A typical scenario is the UART which uses some RX and TX buffers.
+
+Use a simple C-style otherwise, but it is advised to wrap the interface into a namespace as proposed in existing header files.

src/hal/adc.h

@@ -0,0 +1,12 @@
+#pragma once
+
+/// Hardware Abstraction Layer for the ADC's
+
+namespace hal {
+namespace ADC {
+
+    /// ADC access routines
+    uint16_t ReadADC(uint8_t adc);
+
+} // namespace ADC
+} // namespace hal

src/hal/eeprom.h

@@ -0,0 +1,12 @@
+#pragma once
+
+namespace hal {
+namespace EEPROM {
+
+    /// EEPROM interface
+    void WriteByte(uint16_t addr, uint8_t value);
+    void UpdateByte(uint16_t addr, uint8_t value);
+    uint8_t ReadByte(uint16_t addr);
+
+} // namespace EEPROM
+} // namespace hal

src/hal/pins.h

@@ -0,0 +1,13 @@
+#pragma once
+
+/// Hardware Abstraction Layer for the CPU's features and peripherals
+
+namespace hal {
+namespace pins {
+
+    /// pin access routines
+    void WritePin(uint8_t pin, uint8_t value);
+    uint8_t ReadPin(uint8_t pin);
+
+} // namespace pins
+} // namespace hal

src/hal/timers.h

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

src/hal/tmc2130.h

@@ -0,0 +1,18 @@
+#pragma once
+
+/// TMC2130 interface
+/// There are multiple TMC2130 on our board, so there will be multiple instances of this class
+/// @@TODO @leptun - design some lightweight TMC2130 interface
+
+namespace hal {
+
+class TMC2130 {
+
+public:
+    /// constructor - do some one-time init stuff here
+    TMC2130(uint8_t id);
+    /// (re)initialization of the chip
+    void Init();
+};
+
+} // namespace hal

src/hal/uart.h

@@ -0,0 +1,32 @@
+#pragma once
+
+/// UART interface
+/// @@TODO decide, if this class will behave like a singleton, or there will be multiple classes
+/// for >1 UART interfaces
+
+namespace hal {
+class UART {
+
+public:
+    /// @returns current character from the UART without extracting it from the read buffer
+    uint8_t Peek() const;
+    /// @returns true if there are no bytes to be read
+    bool ReadEmpty() const;
+    /// @returns current character from the UART and extracts it from the read buffer
+    uint8_t Read();
+
+    /// @param c character to be pushed into the TX buffer (to be sent)
+    void Write(uint8_t c);
+    /// @returns true if there is at least one byte free in the TX buffer (i.e. some space to add a character to be sent)
+    bool CanWrite() const;
+    /// blocks until the TX buffer was successfully transmitted
+    void Flush();
+
+private:
+    /// implementation of the receive ISR's body
+    void ISR_RX();
+    /// implementation of the transmit ISR's body
+    void ISR_TX();
+};
+
+} // namespace hal

src/hal/watchdog.h

@@ -0,0 +1,13 @@
+#pragma once
+
+/// Hardware Abstraction Layer for the CPU's features and peripherals
+
+namespace hal {
+namespace watchdog {
+
+    /// watchdog interface
+    void ConfigureWatchDog(uint16_t period);
+    void ResetWatchDog();
+
+} // namespace watchdog
+} // namespace hal

src/logic/mm_control.h

@@ -0,0 +1,9 @@
+#pragma once
+
+/// @@TODO @3d-gussner
+/// Extract the current state machines of high-level operations (load fillament, unload fillament etc.) here
+/// Design some nice non-blocking API for these operations
+
+namespace logic {
+
+} // namespace logic

src/modules/buttons.h

@@ -0,0 +1,32 @@
+#pragma once
+
+#include "../hal/adc.h"
+
+/// Buttons are built on top of the raw ADC API
+/// This layer should contain debouncing of buttons and their logical interpretation
+
+namespace modules {
+
+struct Button {
+    /// @returns true if button is currently considered as pressed
+    bool Pressed() const;
+
+private:
+    uint8_t lastState;
+    uint16_t timeElapsedLastChange;
+};
+
+class Buttons {
+public:
+    /// State machine step - reads the ADC, processes debouncing, updates states of individual buttons
+    void Step();
+
+    /// @return true if button at index is pressed
+    /// @@TODO add range checking if necessary
+    inline bool ButtonPressed(uint8_t index) const { return buttons[index].Pressed(); }
+
+private:
+    Button buttons[3]; ///< @@TODO parametrize/generalize?
+};
+
+} // namespace modules

src/modules/leds.h

@@ -0,0 +1,3 @@
+#pragma once
+
+/// @@TODO @leptun design some nice API ;)

src/modules/motion.h

@@ -0,0 +1,21 @@
+#pragma once
+
+/// @@TODO
+/// Logic of motor handling
+/// Ideally enable stepping of motors under ISR (all timers have higher priority than serial)
+
+/// input:
+/// motor, direction, speed (step rate), may be acceleration if necessary (not sure)
+/// enable/disable motor current
+/// stealth/normal
+
+/// Motors:
+/// idler
+/// selector
+/// pulley
+
+/// Operations:
+/// setDir();
+/// rotate(speed)
+/// rotate(speed, angle/steps)
+/// home?

src/modules/permanent_storage.h

@@ -0,0 +1,15 @@
+#pragma once
+
+#include "../hal/eeprom.h"
+
+/// Permanent storage implementation
+/// This is the logic/wear levelling/data structure on top of the raw EEPROM API
+
+namespace modules {
+
+class PermanentStorage {
+
+    /// @@TODO extract from the current MMU implementation and wrap it into this structure
+};
+
+} // namespace modules

src/modules/protocol.h

@@ -0,0 +1,27 @@
+#pragma once
+
+/// MMU protocol implementation
+/// See description of the new protocol in the MMU 2021 doc
+/// @@TODO possibly add some checksum to verify the correctness of messages
+
+namespace modules {
+
+/// @@TODO define/improve this simple message structure that fits our domain
+struct Msg {
+    uint8_t code;
+    uint8_t value;
+};
+
+/// Protocol class is responsible for creating/decoding messages in Rx/Tx buffer
+class Protocol {
+
+public:
+    /// Decodes message in rxbuff
+    /// @returns decoded message structure
+    Msg Decode(const uint8_t *rxbuff);
+    /// Encodes message msg into txbuff memory
+    /// It is expected the txbuff is large enough to fit the message
+    void Encode(uint8_t *txbuff, const Msg &msg);
+};
+
+} // namespace modules