fix: mise à jour de la doc TMC

Author: manoukianv

doc/TMC4671.md

@@ -1,165 +1,110 @@
 # TMC4671 Class State Machine Documentation
 
-This document describes the operation of the state machine for the `TMC4671` class, which is responsible for controlling the Trinamic TMC4671 motor driver.
+This document describes the operation of the asynchronous state machine for the `TMC4671` class, responsible for controlling the Trinamic TMC4671 motor driver.
 
 ## 1. Possible States
 
-The `TMC_ControlState` enum defines all possible states of the machine:
+The `TMC_ControlState` enum defines the primary states of the machine:
 
 ```cpp
 enum class TMC_ControlState : uint32_t {
-    uninitialized,
-    waitPower,
-    Shutdown,
-    Running,
-    EncoderInit,
-    EncoderFinished,
-    HardError,
-    OverTemp,
-    IndexSearch,
-    FullCalibration,
-    ExternalEncoderInit,
-    Pidautotune,
-    CoggingCalibration,
-    SlewRateCalibration
+    uninitialized,       // Initial startup and hardware detection
+    waitPower,           // Waiting for VM (Motor Voltage) to be stable
+    Shutdown,            // Motor stopped, PWM off
+    Running,             // Main operational state (Torque/Velocity/Position)
+    EncoderInit,         // Internal encoder alignment sequence
+    EncoderFinished,     // Encoder ready, waiting for start
+    HardError,           // Fatal error, requires reset
+    OverTemp,            // Thermal protection triggered
+    IndexSearch,         // Searching for encoder index pulse
+    FullCalibration,     // Complete commissioning routine
+    ExternalEncoderInit, // External encoder setup
+    Pidautotune,         // torque PID auto-tuning
+    CoggingCalibration,  // Anti-cogging map generation
+    SlewRateCalibration, // Maximum current ramp measurement
+    NONE                 // Placeholder for recovery logic
 };
 ```
 
 ## 2. State Control Variables
 
-- `TMC_ControlState state`: Contains the current state of the machine.
-- `TMC_ControlState laststate`: Saves the previous state before a transition to a temporary state (like a calibration), allowing a return to the normal operating state.
-- `TMC_ControlState requestedState`: The desired destination state. The transition only occurs if `allowStateChange` is true.
-- `bool allowStateChange`: A lock that prevents state changes during critical operations to ensure their complete execution.
+- `TMC_ControlState state`: The current active state.
+- `TMC_ControlState laststate`: Saves the previous state to allow returning after temporary routines (e.g., calibrations).
+- `TMC_ControlState requestedState`: The next intended state, applied in the next loop tick.
+- `TMC_ControlState postPowerState`: Stores a calibration state to be resumed automatically after a power loss/recovery cycle.
+- `bool allowStateChange`: A lock that prevents external state transitions during critical internal procedures.
 
-## 3. Transition Mechanism
+## 3. Asynchronous Transition Mechanism
 
 The `changeState(TMC_ControlState newState, bool force = false)` method manages transitions:
-- **`force = true`**: The state change is immediate (`state = newState`). Used for critical or internal machine transitions.
-- **`force = false`**: The request is stored in `requestedState`. The actual transition occurs in the main `Run()` loop when `allowStateChange` is `true`.
+- **`force = true`**: Immediate state change (`state = newState`). Used for critical failures or internal state machine logic.
+- **`force = false`**: Requests a transition by setting `requestedState`. The change is applied at the beginning of the next `Run()` iteration if `allowStateChange` is `true`.
 
 ## 4. Detailed Description of States and Transitions
 
-The main logic is implemented in the `Run()` method, which is an infinite loop containing a `switch` on the current state.
+The logic is executed within the `Run()` thread loop. To maintain responsiveness and prevent stack overflows, the state machine is strictly non-blocking.
 
 ---
 
 ### **State: `uninitialized`**
-- **Role**: First state on startup.
-- **Actions**:
-    1. Attempts to communicate with the TMC4671 driver via the `pingDriver()` function.
-    2. If communication is successful, calls `initialize()` to write the basic configuration (PWM frequency, motor type, etc.).
-- **Transitions**:
-    - **➡️ `waitPower`**: If `pingDriver()` and `initialize()` succeed.
-    - **(Stays)**: If `pingDriver()` fails, remains in this state and retries after a delay.
-- **Associated Commands**: No direct user commands. This is an automatic initialization step.
+- **Role**: Hardware discovery.
+- **Actions**: Pings the driver and calls `initialize()` to set PWM frequency, motor type, and basic registers.
+- **Transition**: ➡️ `waitPower` on success.
 
 ---
 
 ### **State: `waitPower`**
-- **Role**: Wait for the motor power supply to be stable and sufficient.
-- **Actions**:
-    1. Periodically checks the supply voltage via `hasPower()`.
-    2. Once the voltage is stable, calls `initializeWithPower()`, which performs ADC calibration.
-- **Transitions**:
-    - **➡️ `EncoderInit`** or **`ExternalEncoderInit`**: If the power is stable but the encoder is not yet aligned (`!encoderAligned`).
-    - **➡️ `requestedState`** (usually `Running` or `Shutdown`): If the power is stable and the encoder is already aligned.
-    - **(Stays)**: As long as `hasPower()` returns `false`.
-- **Special Logic**: If a voltage loss is detected in another state (e.g., `Running`), the machine immediately switches to `waitPower` to ensure a clean recovery when the voltage returns.
-
----
-
-### **State: `Shutdown`**
-- **Role**: A safe resting state where the motor is stopped.
+- **Role**: Monitors supply voltage (VM).
 - **Actions**:
-    1. Ensures that PWM is disabled (`setPwm(TMC_PwmMode::off)`).
-    2. The motor is freewheeling or braked, depending on the hardware configuration.
-- **Transitions**:
-    - **➡️ `Running`**: Triggered by a call to `startMotor()`.
-- **Associated Commands**: `stopMotor()` leads to this state.
+    1. Checks `hasPower()`.
+    2. Once stable (5 consecutive successful checks), calls `initializeWithPower()` for ADC calibration.
+- **Post-Power Recovery**: If `postPowerState` is not `NONE`, the machine automatically transitions to that state (e.g., resuming a Cogging calibration that was interrupted by a power cut).
 
 ---
 
 ### **State: `Running`**
-- **Role**: The main operational state where the motor is active and controlled.
-- **Actions**:
-    1. Applies the requested torque, velocity, or position.
-    2. Continuously monitors the driver status (`statusCheck()`), temperature (`getTemp()`), and the hardware emergency stop status.
-    3. Applies torque compensation (anti-cogging) if enabled.
-- **Transitions**:
-    - **➡️ `waitPower`**: If an undervoltage is detected.
-    - **➡️ `OverTemp`**: If the temperature exceeds the configured limit.
-    - **➡️ `Shutdown`**: Triggered by a call to `stopMotor()`.
-- **Associated Commands**: `turn()`, `setTargetPos()`, `setTargetVelocity()`.
+- **Role**: Main control loop.
+- **Actions**: Applies real-time torque, velocity, or position. Monitors temperature and driver status flags.
+- **Anti-Cogging**: Applies real-time torque compensation from the Flash-stored map at ~1kHz.
 
 ---
 
-### **Encoder Initialization States: `EncoderInit` & `ExternalEncoderInit`**
-- **Role**: Manage the complex sequence of aligning the encoder with the motor.
-- **Actions**:
-    - This is a "super-state" that executes a sequence of sub-steps:
-        1. `estimateABNparams()` / `calibrateAenc()`: Estimates encoder parameters.
-        2. `findEncoderIndex()`: Searches for the encoder's index pulse (if configured).
-        3. `bangInitEnc()`: Forces an angle on the motor with high current to determine the offset between the electrical position and the encoder position.
-        4. `checkEncoder()`: Verifies that the encoder correctly follows the motor's movement.
-- **Transitions**:
-    - **➡️ `EncoderFinished`**: If all steps succeed.
-    - **➡️ `HardError`**: If a step fails repeatedly.
-- **Special Logic**: This state is critical and cannot be interrupted (`allowStateChange = false`).
+### **Calibration Sub-State Machines**
 
----
+To avoid blocking the 1KB TMC thread, long calibrations use internal sub-states:
 
-### **State: `EncoderFinished`**
-- **Role**: A transient state marking the end of encoder initialization.
-- **Actions**:
-    1. Sets the `encoderAligned` flag to `true`.
-- **Transitions**:
-    - **➡️ `Running`**: If a motor start was requested (`motorEnabledRequested`).
-    - **➡️ `Shutdown`**: Otherwise, waits in a safe mode.
-
----
+#### **Cogging Calibration (`CoggingState`)**
+- **Mechanism**: Iterates through `ForwardWait`, `ForwardMeasure`, `BackwardWait`, `BackwardMeasure`, and `Compute`.
+- **Memory Management**: Large calibration arrays (~34KB) are allocated on the **heap** using `std::make_unique<CoggingCalibData>()` only when the calibration starts, and are freed immediately after completion to prevent stack overflow.
 
-### **Calibration States: `FullCalibration`, `Pidautotune`, `CoggingCalibration`, `SlewRateCalibration`**
-- **Role**: Execute specific calibration routines initiated by the user.
-- **Actions**:
-    - Each state executes a specific calibration algorithm (e.g., `calibrateCogging()` measures the motor's detent torque).
-- **Transitions**:
-    - **➡️ `laststate`**: After the calibration is finished, the machine returns to the previous state (usually `Running` or `Shutdown`).
-- **Associated Commands**: `calibrate`, `pidautotune`, `calibrateCogging`.
-- **Special Logic**: These states are blocking (`allowStateChange = false`).
-- **Prerequisites**: For the calibrations to work correctly, the motor must be in a fully initialized state (encoder aligned, etc.) and powered. The state machine checks for power (`hasPower()`) before launching the routine.
+#### **PID Auto-Tune (`PidTuneState`)**
+- **Mechanism**: Iterates through `RampFluxP`, `TuneFluxI_Pulse`, and `TuneFluxI_Measure`.
+- **Asynchronicity**: Replaces `while` loops with tick-based measurements. If power is lost during tuning, it resets to `waitPower` and marks `postPowerState` for resumption.
 
 ---
 
-### **Error States: `HardError` & `OverTemp`**
-- **Role**: Handle critical error conditions.
-- **`OverTemp`**:
-    - **Cause**: Driver temperature is too high.
-    - **Action**: Immediately stops the motor.
-    - **Transition**: **➡️ `HardError`**.
-- **`HardError`**:
-    - **Cause**: Unrecoverable error (ADC calibration failure, repeated encoder alignment failure, overheating).
-    - **Action**: Blocks the state machine. The driver is completely disabled.
-    - **Transition**: None. A hardware reset is required to exit this state.
-
-## 5. Notable Points and Potential "Illogisms"
-
-1.  **Complex Transition Management**: The `requestedState` and `allowStateChange` system is powerful but can make debugging difficult. A user command may not have an immediate effect if the machine is in a critical state that has locked transitions.
-2.  **Recovery after Power Loss**: The systematic transition to `waitPower` in case of undervoltage is a good design practice, as it ensures the system will not attempt to operate under unstable conditions and will re-initialize correctly (re-calibrating ADCs, etc.) when power is restored.
-3.  **`HardError` is a Final State**: Once in the `HardError` state, the system is blocked. This is a safety measure, but it means that no software recovery attempt is possible without a restart.
-4.  **Encoder Initialization Sequence**: The `encoderInit()` function is the core of the motor's commissioning. It is long and complex, with multiple steps that must succeed. A failure at any stage can lead to an error state, which makes it robust but potentially difficult to diagnose without detailed logs.
-5.  **Use of `laststate`**: Storing `laststate` is essential for calibration routines. It allows the user to launch a calibration from the `Running` state and then automatically return to it without manual intervention.
+## 5. Memory and Stack Vigilance
+
+- **Stack Limit**: The TMC thread stack is limited (`TMC_THREAD_MEM = 256` words / 1KB).
+- **Heap Allocation**: Any large data structure (like the `CoggingCalibData` struct) **must** be allocated on the heap.
+- **Safety**: Always initialize local variables (e.g., when reading from Flash) to prevent erratic behavior from uninitialized memory.
 
 ---
 
-## 6. Interaction with User Commands and Safety
+## 6. FreeRTOS Safety and Critical Sections
+
+There is a strict orchestration requirement for hardware initialization to avoid FreeRTOS crashes:
 
-When a user command triggers a long action like a calibration (`calibrateCogging`, `pidautotune`, etc.), the `CommandHandler` calls `changeState()` to request a transition to the corresponding calibration state (e.g., `TMC_ControlState::CoggingCalibration`).
+1.  **No Blocking in Critical Sections**: Calls like `xSemaphoreTake` (used in SPI transfers), `vTaskDelay`, or `Task Creation` must **never** occur inside a `cpp_freertos::CriticalSection`.
+2.  **Driver Instantiation Pattern**: In `Axis::setDrvType`, the `TMC4671` object is instantiated **outside** the critical section. This allows its constructor to safely use SPI/Semaphores to read Flash and configure registers.
+3.  **The Swap**: The critical section is used only for the micro-second duration required to swap the `std::unique_ptr` driver pointers and update the slew rate values.
+4.  **Deferred Cleanup**: Old driver objects are deleted **after** exiting the critical section to ensure their destructors do not block while interrupts are disabled.
 
-The safety of these operations is guaranteed by the following mechanism:
+---
 
-1.  **State Locking**: At the beginning of each calibration state, the `allowStateChange` variable is set to `false`. This "locks" the state machine, preventing any new command or event (like a power loss) from causing an unexpected state change while the calibration routine is in progress.
-2.  **Blocking Execution**: The calibration function (`calibrateCogging()`, `measureMaxSlewRate()`, etc.) is called and runs to completion.
-3.  **Unlocking and Return**: Once the calibration is finished, `allowStateChange` is set back to `true`, and a call to `changeState(laststate, false)` is made. This requests the machine to return cleanly to the state it was in before the calibration began (usually `Running` or `Shutdown`).
+## 7. Interaction with User Commands
 
-This model ensures that a calibration cannot be interrupted and that the system cannot end up in an inconsistent state following a user command.
+User commands (`calibrate`, `cogging`, `pidautotune`) trigger a `changeState()` request. 
+1.  The command sets `allowStateChange = false` to lock the machine.
+2.  The `Run()` loop processes the calibration sub-states tick-by-tick.
+3.  Upon completion (Success or Fail), `allowStateChange` is set to `true`, and the machine returns to `laststate` (usually `Running` or `Shutdown`).