From 39763d7bcd355fdb3d5b362980ac637e91419cde Mon Sep 17 00:00:00 2001
From: "D.R.racer" <drracer@drracer.eu>
Date: Wed, 14 Apr 2021 07:54:34 +0200
Subject: [PATCH] Create basic FW structure

- Design API's based on our discussion and block diagrams
- Set doxygen rules/preferred syntax
---
 src/hal/_rules.txt              |  4 ++++
 src/hal/adc.h                   | 12 ++++++++++++
 src/hal/eeprom.h                | 12 ++++++++++++
 src/hal/pins.h                  | 13 +++++++++++++
 src/hal/timers.h                | 14 ++++++++++++++
 src/hal/tmc2130.h               | 18 ++++++++++++++++++
 src/hal/uart.h                  | 32 ++++++++++++++++++++++++++++++++
 src/hal/watchdog.h              | 13 +++++++++++++
 src/logic/mm_control.h          |  9 +++++++++
 src/modules/buttons.h           | 32 ++++++++++++++++++++++++++++++++
 src/modules/leds.h              |  3 +++
 src/modules/motion.h            | 21 +++++++++++++++++++++
 src/modules/permanent_storage.h | 15 +++++++++++++++
 src/modules/protocol.h          | 27 +++++++++++++++++++++++++++
 14 files changed, 225 insertions(+)
 create mode 100644 src/hal/_rules.txt
 create mode 100644 src/hal/adc.h
 create mode 100644 src/hal/eeprom.h
 create mode 100644 src/hal/pins.h
 create mode 100644 src/hal/timers.h
 create mode 100644 src/hal/tmc2130.h
 create mode 100644 src/hal/uart.h
 create mode 100644 src/hal/watchdog.h
 create mode 100644 src/logic/mm_control.h
 create mode 100644 src/modules/buttons.h
 create mode 100644 src/modules/leds.h
 create mode 100644 src/modules/motion.h
 create mode 100644 src/modules/permanent_storage.h
 create mode 100644 src/modules/protocol.h

diff --git a/src/hal/_rules.txt b/src/hal/_rules.txt
new file mode 100644
index 0000000..65c89c5
--- /dev/null
+++ b/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.
diff --git a/src/hal/adc.h b/src/hal/adc.h
new file mode 100644
index 0000000..6d3d5ff
--- /dev/null
+++ b/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
diff --git a/src/hal/eeprom.h b/src/hal/eeprom.h
new file mode 100644
index 0000000..094cd37
--- /dev/null
+++ b/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
diff --git a/src/hal/pins.h b/src/hal/pins.h
new file mode 100644
index 0000000..34a30f7
--- /dev/null
+++ b/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
diff --git a/src/hal/timers.h b/src/hal/timers.h
new file mode 100644
index 0000000..f233616
--- /dev/null
+++ b/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
diff --git a/src/hal/tmc2130.h b/src/hal/tmc2130.h
new file mode 100644
index 0000000..4ac65bd
--- /dev/null
+++ b/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
diff --git a/src/hal/uart.h b/src/hal/uart.h
new file mode 100644
index 0000000..6663491
--- /dev/null
+++ b/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
diff --git a/src/hal/watchdog.h b/src/hal/watchdog.h
new file mode 100644
index 0000000..de264a2
--- /dev/null
+++ b/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
diff --git a/src/logic/mm_control.h b/src/logic/mm_control.h
new file mode 100644
index 0000000..1fd6619
--- /dev/null
+++ b/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
diff --git a/src/modules/buttons.h b/src/modules/buttons.h
new file mode 100644
index 0000000..1497d8d
--- /dev/null
+++ b/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
diff --git a/src/modules/leds.h b/src/modules/leds.h
new file mode 100644
index 0000000..54041c7
--- /dev/null
+++ b/src/modules/leds.h
@@ -0,0 +1,3 @@
+#pragma once
+
+/// @@TODO @leptun design some nice API ;)
diff --git a/src/modules/motion.h b/src/modules/motion.h
new file mode 100644
index 0000000..6e468f2
--- /dev/null
+++ b/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?
diff --git a/src/modules/permanent_storage.h b/src/modules/permanent_storage.h
new file mode 100644
index 0000000..bb1e70e
--- /dev/null
+++ b/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
diff --git a/src/modules/protocol.h b/src/modules/protocol.h
new file mode 100644
index 0000000..9a9ed6e
--- /dev/null
+++ b/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