[Docs] [WIP] BLDC Arch documentation

README.md

@@ -23,6 +23,9 @@ The following commands are intended to be run on an Ubuntu 22.04 machine (and wh
 4. Run `bash scripts/format.sh` to format the source code.
 5. Run `bash scripts/linter.sh` to run the linter.
 
+### API Documentation
+API documentation is available [here](https://sahil-kale.github.io/basilisk-actuator-control-lib/)
+
 ### PR Submissions
 Submit PR's against `main`. PR's that modify the source code's functionality without a unit test will not be accepted unless determined that the functionality does not require one. CI will check test, lint, and format upon check-in.
 

control_loop/bldc/brushless_foc_control_loop.cpp

@@ -35,17 +35,18 @@ void BrushlessFOCControlLoop::init(BrushlessFOCControlLoop::BrushlessFOCControlL
 
 BrushlessFOCControlLoop::BrushlessFOCControlLoopState BrushlessFOCControlLoop::get_desired_state(
     float i_q_reference, const BrushlessFOCControlLoopState current_state) {
-    BrushlessFOCControlLoop::BrushlessFOCControlLoopState desired_state = current_state;
+    BrushlessFOCControlLoopState desired_state = current_state;
+    const bool i_q_reference_is_zero = math::float_equals(i_q_reference, 0.0f);
     switch (current_state) {
-        case BrushlessFOCControlLoop::BrushlessFOCControlLoopState::STOP: {
+        case BrushlessFOCControlLoopState::STOP: {
             // if the estimator reports that it is valid, then we should start the motor
-            if ((i_q_reference != 0)) {
-                desired_state = BrushlessFOCControlLoop::BrushlessFOCControlLoopState::RUN;
+            if (i_q_reference_is_zero == false) {
+                desired_state = BrushlessFOCControlLoopState::RUN;
             }
         } break;
-        case BrushlessFOCControlLoop::BrushlessFOCControlLoopState::RUN: {
-            if (i_q_reference == 0.0f) {
-                desired_state = BrushlessFOCControlLoop::BrushlessFOCControlLoopState::STOP;
+        case BrushlessFOCControlLoopState::RUN: {
+            if (i_q_reference_is_zero) {
+                desired_state = BrushlessFOCControlLoopState::STOP;
             }
         } break;
         default:

control_loop/bldc/brushless_foc_control_loop.hpp

@@ -150,9 +150,9 @@ class BrushlessFOCControlLoop : public ControlLoop {
      * @brief Construct a new BrushlessFOCControlLoop object
      * @param motor The bridge on which a singular BLDC/PMSM motor is connected
      * @param clock The clock to use for the control loop
-     * @param rotor_position_estimators A pointer array to rotor position estimators to use in C-style array
+     * @param rotor_position_estimators A pointer array to rotor position estimators to use in C-style array. The angle estimate
+     * used by the controller is the lowest-indexed valid rotor position estimator in the array
      * @param num_rotor_position_estimators The number of rotor position estimators
-     * @note The secondary rotor position estimator is used when the primary rotor position estimator is not valid
      */
     BrushlessFOCControlLoop(hwbridge::Bridge3Phase& motor, basilisk_hal::HAL_CLOCK& clock,
                             bldc_rotor_estimator::ElectricalRotorPosEstimator* rotor_position_estimators[],

control_loop/bldc/readme.md

@@ -0,0 +1,36 @@
+# Brushless Control Loop
+## Overview
+The brushless control loops are intended to enable FOC and trapezoidal control of Permenant-Magnet Synchronous and Brushless DC motors (PMSM and BLDC). A note that while the terminology of 'BLDC' is adopted throughout the codebase, the field oriented control technique can generally be employed on both PMSM and BLDC motors by assuming the back-emf waveform of the latter to be generally sinusoidal. 
+
+Two control loops are defined:
+`BrushlessFOCControlLoop`, which enables field oriented control of a BLDC motor.
+`Brushless6StepControlLoop`, which enables trapezoidal control of a BLDC motor.
+
+The specific API for both of these control loops can be found [here](https://sahil-kale.github.io/basilisk-actuator-control-lib/annotated.html).
+
+Background info: TBC 
+
+## 6 Step Control Loop
+
+## FOC Control Loop
+The FOC control loop is capable of controlling a 3-phase motor by applying a desired current vector induced by the stator. A typical FOC control loop is shown below and generally follows what is implemented by this library:
+![Typical Sensored FOC](https://github.com/sahil-kale/basilisk-actuator-control-lib/blob/main/assets/typicalfoc.png)
+
+Note that this control loop is capable of using multiple rotor position estimators, enabling sensorless fallback operation if desired (in addition to fully sensorless capability). See the API for further information, alongside the unit tests.
+
+### State Machine
+A visual diagram of the state transition and associated conditions for the FOC control loop is shown below:
+
+![State Machine](https://github.com/sahil-kale/basilisk-actuator-control-lib/blob/main/assets/BrushlessFOCStateMachine.png)
+
+### Control Flow
+A high-level control flow diagram of the top-level control loop is shown below, alongside the control flow for the FOC current controller flow diagram.
+![High level control flow diagra,](https://github.com/sahil-kale/basilisk-actuator-control-lib/blob/main/assets/BrushlessFOCHighLevelControlFlow.png)
+![FOC Current Control Flow](https://github.com/sahil-kale/basilisk-actuator-control-lib/blob/main/assets/BrushlessFOC_FOCControlFlow_.png)
+
+## Rotor Estimator
+### Sensorless FOC
+A rotor flux observer is currently implemented for sensorless FOC. Further information about the implementation can be found in `docs/sensorless_foc.md` 
+
+### Phase Estimation Control Law
+TBC and linked.