Merge remote-tracking branch 'origin/main' into nixfmt

Author: ryleu

README.md

@@ -1,4 +1,4 @@
-# rover-Embedded-Lib
+# astra-embedded-lib
 
 Standardizing ASTRA's embedded code.
 
@@ -20,7 +20,6 @@ team-wide constants, just to name a few. Here are a few examples:
 * `parseInput(const String, std::vector<String>&)`: takes input from USB or UART and separates it into the vector, using commas as delimiters. Very useful for dealing with commands and data input from other mcu's.
 * `CAN_sendDutyCycle(uint8_t, AstraCAN&)`: Formats and sends a CAN packet to a REV motor controller with a duty cycle. All communication with REV motor controllers should reside in `AstraREVCAN.{h,cpp}`.
 * `isCalibrated(Adafruit_BNO055&)`: Attempts to check whether the BNO has been calibrated in EEPROM.
-* `COMMS_UART`: Macro for the UART interface used by each MCU.
 * `SERIAL_BAUD`: Standard baudrate for USB Serial used by all of ASTRA's mcu's.
 
 ## Usage in PlatformIO
@@ -29,16 +28,16 @@ team-wide constants, just to name a few. Here are a few examples:
 
  1. Add the following line to `lib_deps` in your `/platformio.ini`:
 
-**https://github.com/SHC-ASTRA/rover-Embedded-Lib**
+**https://github.com/SHC-ASTRA/astra-embedded-lib**
 
- 2. Add the include statement for your project. E.g., `#include "project/CITADEL.h"`
- 3. Make sure to grab the correct dependencies for `/platformio.ini` from the project headers.
+ 2. Add the dependencies you need from `include/`. E.g., `#include "AstraVicCAN.h"`
+ 3. Make sure to grab the correct dependencies for `/platformio.ini` from the library headers.
 
 ### Starting a new PlatformIO project
 
- 1. Copy the example file from `/.pio/libdeps/[board]/rover-Embedded-Lib/examples/Template/`
- 2. Grab the correct project header from `include/project/` or create one
- from `TEMPLATE.h`
+ 1. Copy the example file from `/.pio/libdeps/[board]/astra-Embedded-Lib/examples/Template/`
+ 2. Grab whatever headers you need from `include/`
+ 3. Get writing!
 
 ### Updating your libraries
 
@@ -55,12 +54,10 @@ PlatformIO provides a button which will check for updates in all of your depende
 
 * **Library files** - Depending on context, either the files generally contained in the library,
 or the main functional C++ files containing functions and classes.
-* **Project header** - A header file that corresponds to one PlatformIO project, residing in `include/project/`.
 
 ### File names
 
 * **Library files** - Camel case with the first letter of all words, including the first, capitalized. Ex: `AstraArm.cpp`
-* **Project headers** - All caps. Ex: `CITADEL.h`
 
 ## Files
 
@@ -69,6 +66,7 @@ or the main functional C++ files containing functions and classes.
 * `AstraArm.h/.cpp` - Arm
 * `AstraMotors.h/.cpp` - REV motor
 * `AstraNP.h/.cpp` - Status indicator using NeoPixel
+* `AstraVicCAN.h` - Serial/CAN-analogous communication standard
 
 ### Library
 
@@ -81,17 +79,6 @@ or the main functional C++ files containing functions and classes.
 * `AstraSensors.h/.cpp` - functions for sensors
 * `AstraMisc.h/.cpp` - functions, consts, etc. useful to all ASTRA projects.
 
-### Project Headers
-
-* One per project.
-* All caps file name, aside from `.h`
-* Found in `include/project/`
-* Includes pinouts (all pinouts important for code, optionally ones not needed for code)
-* Includes constants relating to hardware
-* DOES NOT include constants only relevant to the code
-* The goal is too put less work on the embedded programmer, abstracting away electronics
-* The embedded programmer SHOULD NOT have to edit their project's library. When in doubt, it goes in `main.cpp`.
-
 ## Theory
 
 * `main.cpp` includes all the library headers it needs
@@ -100,19 +87,6 @@ included in `main.cpp`, then no include errors, but if it is, then you will get
 * `.cpp` files enable themselves when all of its required external libraries are found. External libraries
 are 90% of the reason the `.cpp` files need the option to be disabled.
 
-## Updating this Repository
-
-When making any update to this repository, before updating `main`, make sure to increment the version number in `library.json`, line 3.
-Without making this change, projects using this library will not update automatically. Instead, they will have to delete the library
-locally and let PlatformIO re-download it. (Not sure if this is true.......)
-
-When making commits, it would be amazing if you use [Conventional Commits](https://www.conventionalcommits.org/en/v1.0.0/#summary).
-
-### Creating a new project header
-
- 1. Copy `TEMPLATE.h` in `rover-Embedded-Lib/include/project/`.
- 2. Choose a project macro and add it to `ASTRA.h`.
-
 ### Creating a new header file
 
  1. Place the header file in `include/` and its implementation `.cpp` in `src/`.

include/AstraCAN.h

@@ -41,12 +41,9 @@ void printCANframe(CanFrame& frame);
 
 #        include <FlexCAN_T4.h>  // https://github.com/tonton81/FlexCAN_T4
 
-// Core and FAERIE use CAN1, Arm uses CAN3
-#        ifdef ARM
-typedef FlexCAN_T4<CAN3, RX_SIZE_256, TX_SIZE_16> AstraCAN;
-#        else
+// NOTE: you may need to change the CAN bus number (e.g., CAN1 -> CAN3) depending on
+// which pins you are using for your CAN transceiver.
 typedef FlexCAN_T4<CAN1, RX_SIZE_256, TX_SIZE_16> AstraCAN;
-#        endif
 
 
 #    endif  // End microcontroller check

include/AstraMotors.h

@@ -120,6 +120,8 @@ class AstraMotors {
     //  Controlling physical motor
     //---------------------------------------------//
 
+    void setSlowStatusPeriods();  // Set status frame periods to 100 ms for motor on main
+
     // Send the identify command to the SparkMax; makes it flash its LED purple and white
     inline void identify() {
         CAN_identifySparkMax(motorID);

include/AstraREVCAN.h

@@ -69,6 +69,25 @@ void CAN_setParameter(uint8_t deviceId, sparkMax_ConfigParameter parameterID, sp
  */
 void CAN_reqParameter(uint8_t deviceId, sparkMax_ConfigParameter parameterID);
 
+/**
+ * @brief Set the period of a periodic status frame on the specified SparkMax device
+ *
+ * These are the default periods, in ms:
+ * Status0 - 10
+ * Status1 - 20
+ * Status2 - 20
+ * Status3 - 50
+ * Status4 - 20
+ * Status5 - 200
+ * Status6 - 200
+ * Status7 - 250
+ *
+ * @param deviceId REV ID
+ * @param frameId The ID of the periodic status frame to set the period of
+ * @param periodMs The period to set for the specified periodic status frame, in milliseconds
+ */
+void CAN_setStatusPeriod(uint8_t deviceId, sparkMax_PeriodicFrame frameId, int periodMs);
+
 
 //-------------------------------------//
 //  Backwards Compatibility Functions  //

include/AstraREVTypes.h

@@ -8,6 +8,7 @@
 #include <Arduino.h>
 
 
+// https://docs.revrobotics.com/brushless/spark-max/operating-modes#brake-coast-mode-idle-behavior
 enum class sparkMax_IdleMode {
     kCoast = 0,
     kBrake = 1
@@ -43,6 +44,21 @@ enum class sparkMax_ctrlType {
     kSmartMotion = 0x52
 };
 
+// https://docs.revrobotics.com/brushless/spark-max/control-interfaces#periodic-status-frames
+enum class sparkMax_PeriodicFrame {
+    kStatus0 = 0,
+    kStatus1 = 1,
+    kStatus2 = 2,
+    kStatus3 = 3,
+    kStatus4 = 4,
+    kStatus5 = 5,
+    kStatus6 = 6,
+    kStatus7 = 7
+};
+
+constexpr int sparkMax_statusFrame_baseId =
+    0x60;  // Base ID for status frames; actual ID is base + frame number
+
 struct motorStatus0 {
     double appliedOutput;
     uint16_t faults;
@@ -81,6 +97,7 @@ enum class sparkMax_ParameterType : uint8_t {
     kBool = 0x3,
 };
 
+// https://docs.revrobotics.com/brushless/spark-max/parameters
 enum class sparkMax_ConfigParameter : int32_t {
     kCanID = 0x0,
     kInputMode = 0x1,

include/AstraVicCAN.h

@@ -43,8 +43,8 @@ using namespace unilib;
 #    define SUBMODULE_CAN_ID CanMcuId::MCU_ARM
 #elif defined(DIGIT)
 #    define SUBMODULE_CAN_ID CanMcuId::MCU_DIGIT
-#elif defined(FAERIE)
-#    define SUBMODULE_CAN_ID CanMcuId::MCU_FAERIE
+#elif defined(LANCE)
+#    define SUBMODULE_CAN_ID CanMcuId::MCU_LANCE
 #elif defined(CITADEL)
 #    define SUBMODULE_CAN_ID CanMcuId::MCU_CITADEL
 #else  // Default - no macro in platformio.ini; will only respond to broadcast messages
@@ -74,8 +74,8 @@ bool mcuIdFromString(String str, CanMcuId* mcuID) {
         *mcuID = CanMcuId::MCU_ARM;
     else if (str == "digit")
         *mcuID = CanMcuId::MCU_DIGIT;
-    else if (str == "faerie")
-        *mcuID = CanMcuId::MCU_FAERIE;
+    else if (str == "lance")
+        *mcuID = CanMcuId::MCU_LANCE;
     else if (str == "citadel")
         *mcuID = CanMcuId::MCU_CITADEL;
     else
@@ -99,8 +99,8 @@ String mcuIdToString(const CanMcuId mcuID) {
         return "arm";
     else if (mcuID == CanMcuId::MCU_DIGIT)
         return "digit";
-    else if (mcuID == CanMcuId::MCU_FAERIE)
-        return "faerie";
+    else if (mcuID == CanMcuId::MCU_LANCE)
+        return "lance";
     else if (mcuID == CanMcuId::MCU_CITADEL)
         return "citadel";
     else  // Should never run unless an MCU is added and not included in this function
@@ -264,12 +264,13 @@ class VicCanFrame {
      * @return true if a frame is successfully read;
      * @return false if no frame is received.
      */
-    bool readCan() {
+    bool readCan(CanFrame* rawFrame) {
         static CanFrame inFrame;
         if (!ESP32Can.readFrame(inFrame, 0))
             return false;  // No CAN frame received
 
         parseCanFrame(inFrame);
+        *rawFrame = inFrame;
         return true;
     }
 #endif
@@ -356,10 +357,29 @@ class VicCanController {
      * @brief Extends readCanFrame() to check destination of CAN Frame, relays stray CAN frames
      * to Serial if relayMode is on, and checks for a queued frame from relayFromSerial().
      *
+     * (Non-REVCAN compatible variant)
+     *
+     * @return true upon reading a CAN frame for this MCU;
+     * @return false upon not finding a CAN frame or only reading one for a different MCU
+     */
+    inline bool readCan() {
+        bool isREV;
+        CanFrame rawFrame;
+        return readCan(&isREV, &rawFrame);
+    }
+
+    /**
+     * @brief Extends readCanFrame() to check destination of CAN Frame, relays stray CAN frames
+     * to Serial if relayMode is on, and checks for a queued frame from relayFromSerial().
+     *
+     * @param isREV [out] whether the frame read is a REV CAN frame
+     * @param outFrame [out] the raw CAN frame read, for use with REV CAN frames that need to be parsed by
+     * loop()
+     *
      * @return true upon reading a CAN frame for this MCU;
      * @return false upon not finding a CAN frame or only reading one for a different MCU
      */
-    bool readCan() {
+    bool readCan(bool* isREV, CanFrame* outFrame) {
         // Check for queued frame from relayFromSerial()
         if (relayFrameWaiting) {
             relayFrameWaiting = false;
@@ -369,7 +389,7 @@ class VicCanController {
             return true;  // Use inVicCanFrame already set by relayFromSerial()
         }
 
-#ifdef CAN_AVAILABLE
+        // #ifdef CAN_AVAILABLE
         // Run through up to 5 messages on the CAN network.
         // If one is found to act on, break and return true.
         // If a read fails, there are no more messages to read; return false.
@@ -380,31 +400,38 @@ class VicCanController {
         int count = 0;
         while (count++, count < 5) {
             // Check CAN network for a frame
-            if (!inVicCanFrame.readCan())
+            if (!inVicCanFrame.readCan(outFrame)) {
+                *isREV = false;
                 return false;  // No CAN frame received
+            }
 
-#    ifdef VICCAN_DEBUG
+#ifdef VICCAN_DEBUG
             Serial.println("Received CAN frame: ");
             Serial.println(inVicCanFrame.toStr());
-#    endif
+#endif
 
             // Relay stray CAN frames to Serial if relayMode is on
             // Broadcast messages are specifically not relayed.
-            if (!inVicCanFrame.isForMe()) {
+            if (!outFrame->extd && !inVicCanFrame.isForMe()) {
                 if (relayMode) {
-#    ifdef VICCAN_DEBUG
+#ifdef VICCAN_DEBUG
                     Serial.println("Relaying from CAN to Serial:");
                     Serial.println(inVicCanFrame.toStr());
-#    endif
+#endif
                     relayToSerial(inVicCanFrame);
                 }
                 continue;  // Not for us; try to process the next message
+            } else if (outFrame->extd) {
+                // REV CAN Frame; don't do anything, let loop() parse it with *outFrame
+                *isREV = true;
+                return false;
             }
 
             // We have a CAN command that we should act on.
+            *isREV = false;
             return true;
         }
-#endif
+        // #endif
         return false;
     }