Merge branch 'idf5-arduino3' of https://github.com/fablab-bergamo/fab…

…-o-matic into idf5-arduino3

.github/workflows/docs.yml

@@ -18,7 +18,8 @@ jobs:
     steps:
     # Checks-out your repository under $GITHUB_WORKSPACE, so your job can access it
     - uses: actions/checkout@v4
-
+    - name: Use secrets.hpp.example as base for the build
+      run: cp conf/secrets.hpp.example conf/secrets.hpp
     - name: Doxygen Action
       uses: mattnotmitt/[email protected]
       with:

conf/pins.hpp

@@ -7,7 +7,7 @@
 
 namespace fabomatic
 {
-  /// @brief Returns configuration for an ESP32 dev board used in revision 0.1
+  /// @brief Returns configuration for an ESP32 dev board used in HW revision 0.1
   /// @return pins_config
   constexpr auto configure_pins_esp32() -> const pins_config
   {

conf/secrets.hpp.example

@@ -9,39 +9,57 @@
 #include "conf.hpp"
 #include "FabUser.hpp"
 
+/**
+ * Whitelisted RFID cards
+ */
 namespace fabomatic::secrets::cards
 {
-  static constexpr uint8_t LEN = 10U; /* Number of whitelisted cards */
+  /**
+   * Number of whitelisted card in the array below
+   */
+  static constexpr uint8_t LEN = 10U;
 
   using WhiteListEntry = std::tuple<card::uid_t, FabUser::UserLevel, std::string_view>;
   using WhiteList = std::array<WhiteListEntry, LEN>;
 
-  static constexpr WhiteList whitelist /* List of RFID tags whitelisted, regardless of connection */
-      {
-          std::make_tuple(0xAABBCCD1, FabUser::UserLevel::FabAdmin, "ABCDEFG"),
-          std::make_tuple(0xAABBCCD2, FabUser::UserLevel::FabAdmin, "PIPPO"),
-          std::make_tuple(0xAABBCCD3, FabUser::UserLevel::NormalUser, "USER1"),
-          std::make_tuple(0xAABBCCD4, FabUser::UserLevel::NormalUser, "USER2"),
-          std::make_tuple(0xAABBCCD5, FabUser::UserLevel::NormalUser, "USER3"),
-          std::make_tuple(0xAABBCCD6, FabUser::UserLevel::NormalUser, "USER4"),
-          std::make_tuple(0xAABBCCD7, FabUser::UserLevel::NormalUser, "USER5"),
-          std::make_tuple(0xAABBCCD8, FabUser::UserLevel::NormalUser, "USER6"),
-          std::make_tuple(0xAABBCCD9, FabUser::UserLevel::FabStaff, "USER7"),
-          std::make_tuple(0xAABBCCDA, FabUser::UserLevel::FabStaff, "USER8")};
+  /**
+   * Static list of whitelisted RFID cards. If the network is down, these cards will be
+   * authorized. If network is up, backend prevails.
+   */
+  static constexpr WhiteList whitelist{
+      std::make_tuple(0xAABBCCD1, FabUser::UserLevel::FabAdmin, "ABCDEFG"),
+      std::make_tuple(0xAABBCCD2, FabUser::UserLevel::FabAdmin, "PIPPO"),
+      std::make_tuple(0xAABBCCD3, FabUser::UserLevel::NormalUser, "USER1"),
+      std::make_tuple(0xAABBCCD4, FabUser::UserLevel::NormalUser, "USER2"),
+      std::make_tuple(0xAABBCCD5, FabUser::UserLevel::NormalUser, "USER3"),
+      std::make_tuple(0xAABBCCD6, FabUser::UserLevel::NormalUser, "USER4"),
+      std::make_tuple(0xAABBCCD7, FabUser::UserLevel::NormalUser, "USER5"),
+      std::make_tuple(0xAABBCCD8, FabUser::UserLevel::NormalUser, "USER6"),
+      std::make_tuple(0xAABBCCD9, FabUser::UserLevel::FabStaff, "USER7"),
+      std::make_tuple(0xAABBCCDA, FabUser::UserLevel::FabStaff, "USER8")};
 } // namespace fabomatic::secrets::cards
 
+/**
+ * WiFi and MQTT credentials
+ */
 namespace fabomatic::secrets::credentials
 {
 
 #if (PINS_WOKWI)
   static constexpr std::string_view ssid = "Wokwi-GUEST"; /* WOKWI SSID */
   static constexpr std::string_view password = "";        /* WOKWI password */
 #else
-  static constexpr std::string_view ssid = "MYSSID";      /* Default SSID */
-  static constexpr std::string_view password = "MYPWD";   /* Default password */
+  static constexpr std::string_view ssid = "MYSSID";    /* Default SSID */
+  static constexpr std::string_view password = "MYPWD"; /* Default password */
 #endif
 
+  /**
+   * Username for MQTT broker auth.
+   */
   static constexpr std::string_view mqtt_user = "user";
+  /**
+   * Username for MQTT broker auth.
+   */
   static constexpr std::string_view mqtt_password = "password";
 
   // Checks

include/AuthProvider.hpp

@@ -14,6 +14,9 @@
 
 namespace fabomatic
 {
+  /**
+   * This class manages authentication of a RFID tag through cache, whitelist or network request.
+   */
   class AuthProvider
   {
   private:

include/BoardInfo.hpp

@@ -5,6 +5,9 @@
 
 namespace fabomatic
 {
+  /**
+   * Helper struct representing the display state
+   */
   struct BoardInfo
   {
     bool server_connected;

include/BufferedMsg.hpp

@@ -12,6 +12,9 @@
 
 namespace fabomatic
 {
+  /**
+   * Message that can be saved in Flash for future replay
+   */
   struct BufferedMsg
   {
     std::string mqtt_message;
@@ -23,6 +26,9 @@ namespace fabomatic
     BufferedMsg(BufferedMsg &source) = default;
   };
 
+  /**
+   * Class containing the buffered messages for future replay
+   */
   class Buffer
   {
   private:
@@ -43,6 +49,9 @@ namespace fabomatic
     static constexpr auto MAX_MESSAGES = 40;
   };
 
+  /**
+   * Query to be replayed
+   */
   class BufferedQuery final : public ServerMQTT::Query
   {
   private:

include/Buzzer.hpp

@@ -5,6 +5,9 @@
 
 namespace fabomatic
 {
+  /**
+   * Represents the buzzer for BoardLogic
+   */
   class Buzzer
   {
   private:

include/CachedCards.hpp

@@ -10,14 +10,21 @@
 
 namespace fabomatic
 {
+  /**
+   * A Cached card contains only RFID tag ID + access level. Name is intentionally not saved.
+   */
   struct CachedCard
   {
     card::uid_t uid;
     FabUser::UserLevel level;
-    constexpr CachedCard() : uid(card::INVALID), level(FabUser::UserLevel::Unknown){};
-    constexpr CachedCard(card::uid_t uid, FabUser::UserLevel level) : uid(uid), level(level){};
+    constexpr CachedCard() : uid(card::INVALID), level(FabUser::UserLevel::Unknown) {};
+    constexpr CachedCard(card::uid_t uid, FabUser::UserLevel level) : uid(uid), level(level) {};
   };
 
+  /**
+   * This struct contains CACHE_LEN RFID tags with their authentication by the backend.
+   * It is used to provide some resiliency in case of network failure.
+   */
   struct CachedCards
   {
     std::array<card::uid_t, conf::rfid_tags::CACHE_LEN> cards;

include/Espressif.hpp

@@ -4,6 +4,9 @@
 #include <chrono>
 #include <string_view>
 
+/**
+ * Contains all espressif32 features not masked by Arduino IDE
+ */
 namespace fabomatic::esp32
 {
   [[nodiscard]] auto setupWatchdog(std::chrono::milliseconds timeout) -> bool;

include/FabBackend.hpp

@@ -18,6 +18,9 @@
 
 namespace fabomatic
 {
+  /**
+   * This class is used to exchange messages with the MQTT broker and the backend
+   */
   class FabBackend
   {
   private:

include/FabUser.hpp

@@ -11,6 +11,9 @@
 
 namespace fabomatic
 {
+  /**
+   * Represents a user with access level, name, RFID tag, and auth result.
+   */
   struct FabUser
   {
     enum class UserLevel : uint8_t
@@ -21,10 +24,10 @@ namespace fabomatic
       FabAdmin,
     };
 
-    card::uid_t card_uid {card::INVALID};
+    card::uid_t card_uid{card::INVALID};
     std::string holder_name{""};
-    bool authenticated {false};
-    UserLevel user_level {UserLevel::Unknown};
+    bool authenticated{false};
+    UserLevel user_level{UserLevel::Unknown};
 
     FabUser() = default;
 

include/LCDWrapper.hpp

@@ -10,6 +10,9 @@
 
 namespace fabomatic
 {
+  /**
+   * LCD display wrapper
+   */
   class LCDWrapper
   {
   public:

include/Led.hpp

@@ -9,6 +9,9 @@
 
 namespace fabomatic
 {
+  /**
+   * RGB/LED/NeoPixel class
+   */
   class Led
   {
   public:

include/Machine.hpp

@@ -12,6 +12,9 @@ namespace fabomatic
 {
   class FabBackend;
 
+  /**
+   * Represents the FabLab machine connected to the board
+   */
   class Machine
   {
   public:

include/MachineConfig.hpp

@@ -11,6 +11,10 @@
 
 namespace fabomatic
 {
+  /**
+   * Represents the configuration settings for the machine.
+   * It is a mix of saved settings on Flash and backend settings.
+   */
   struct MachineConfig
   {
     MachineID machine_id{0};

include/MachineID.hpp

@@ -13,6 +13,9 @@ enum class MachineType : uint8_t
   Other = 5
 };
 
+/**
+ * The unique machine identifier for the backend
+ */
 struct MachineID
 {
   uint16_t id;

include/Mrfc522Driver.hpp

@@ -14,6 +14,9 @@
 
 namespace fabomatic
 {
+  /**
+   * The real Mrfc522Driver around the Arduino library.
+   */
   class Mrfc522Driver
   {
   private:

include/RFIDWrapper.hpp

@@ -12,6 +12,10 @@
 
 namespace fabomatic
 {
+  /**
+   * This class can be instanciated with a real or mock RFID driver.
+   * Users of this class use the BaseRFIDWrapper interface
+   */
   template <typename Driver>
   class RFIDWrapper final : public BaseRFIDWrapper
   {
@@ -51,7 +55,7 @@ namespace fabomatic
     RFIDWrapper &operator=(const RFIDWrapper &x) = delete; // copy assignment
     RFIDWrapper(RFIDWrapper &&) = delete;                  // move constructor
     RFIDWrapper &operator=(RFIDWrapper &&) = delete;       // move assignment
-    ~RFIDWrapper() override{};                             // Default destructor
+    ~RFIDWrapper() override {};                            // Default destructor
   };
 } // namespace fabomatic
 

include/SavedConfig.hpp

@@ -16,6 +16,9 @@
 
 namespace fabomatic
 {
+  /**
+   * Persisted settings and facilities to load/save settings from Flash
+   */
   class SavedConfig
   {
   private:

include/Tasks.hpp

@@ -19,7 +19,9 @@ namespace fabomatic::Tasks
 
   class Scheduler;
 
-  // A task is a function that is executed periodically
+  /**
+   * A task class which represents a function to be called at requested intervals
+   */
   class Task
   {
   public:
@@ -110,6 +112,9 @@ namespace fabomatic::Tasks
     unsigned long run_counter;
   };
 
+  /**
+   * The schedule is in charge of running tasks in the right order based on their requested intervals.
+   */
   class Scheduler
   {
   public:

include/mock/MockMQTTBroker.hpp

@@ -11,6 +11,9 @@
 
 namespace fabomatic
 {
+  /**
+   * This class implements an MQTT broker with predefined responses to FabBackend requests.
+   */
   class MockMQTTBroker final : public sMQTTBroker
   {
   public:

include/mock/MockMrfc522.hpp

@@ -14,6 +14,9 @@
 
 namespace fabomatic
 {
+  /**
+   * This class implements a Mrfc522 with settable tag ID in order to allow simulation
+   */
   class MockMrfc522
   {
   private:
@@ -29,7 +32,7 @@ namespace fabomatic
       byte sak{0}; // The SAK (Select acknowledge) byte returned from the PICC after successful selection.
     };
 
-    constexpr MockMrfc522(){};
+    constexpr MockMrfc522() {};
 
     auto PICC_IsNewCardPresent() -> bool;
     auto PICC_ReadCardSerial() -> bool;