Simple FOC Driver and Support Library

I2CCommander implements the SimpleFOC Commander protocol over an I2C communication bus. It uses a client-server (Controller-Target) model:

• Target Device (the "Muscle"): The motor driver acting as the I2C target. It hosts one or more motors and an instance of I2CCommander.
• Controller Device (the "Brain"): The MCU coordinating one or more motor drivers using an instance of I2CCommanderMaster.

Communication follows a register paradigm. The controller sends I2C messages to read from or write to specific registers on the target. Because a single target device can manage multiple motors, most registers operate on a "currently selected motor" defined by a specific register. Some registers, like REG_ENABLE_ALL or REG_STATUS, operate globally across all motors on that target.

A CalibratedSensor is a wrapper for a standard SimpleFOC sensor that compensates for eccentricity error.

Eccentricity error occurs when there is a misalignment between the center of rotation of the motor and the center of the sensor (e.g., a magnetic sensor). This misalignment causes the sensor output to be non-linear relative to the rotor position, creating disturbances in the control loop and affecting torque accuracy.

CalibratedSensor uses a Lookup Table (LUT) to compensate for these non-linearities in a feed-forward fashion, improving motor performance and control stability.

The TrapezoidalPlanner class generates trapezoidal velocity profiles for a motor. It is designed to be used in conjunction with MotionControlType::velocity to ensure smooth acceleration and deceleration when changing target positions.

When the acceleration or deceleration limits are low enough that the maximum velocity is never reached, the planner produces a triangular velocity profile instead of a trapezoidal one. The planner handles both forward and backward motion (negative velocity) automatically based on the target angle.

TrapezoidalPlanner trapezoidal = TrapezoidalPlanner(max_velocity, acceleration, deceleration, min_velocity);

The library uses a SimpleFOCRegisters abstraction to map SimpleFOC parameters to virtual "Registers". This allows for a unified way to:

1. Monitor and Control: Use PacketCommander or Telemetry classes to get or set motor values via Serial or I2C.
2. Save/Load Settings: Use the Settings drivers to store calibration and configuration data to persistent storage (like EEPROM or Flash), allowing you to skip the calibration phase during subsequent power cycles.
3. Telemetry: Log motor values using SimpleTelemetry (for Arduino Serial Plotter) or TeleplotTelemetry (for VSCode Teleplot extension).

The SmoothingSensor is a wrapper class designed to improve the quality of angle readings from sensors that are either low resolution or slow to communicate.

How it works: It uses the timestamp of the last angle reading from the sensor combined with the low-pass filtered velocity from the motor to predict (extrapolate) what the angle should be at the current time.

When to use it:

• Use it when: You have a sensor that is low resolution or has slow communication latency.
• Do NOT use it when: You already have a high-resolution sensor that updates quickly, as it provides no improvement in those cases.

Telemetry is a high-level abstraction used to monitor SimpleFOC parameters and state. It can access any value exposed via the Registers system. Telemetry data can be output through the serial port in two formats:

• ASCII: Human-readable text format.
• Binary: Compact, machine-readable format for higher efficiency.

For detailed implementation, refer to the Telemetry and Streams Comms documentation.

The STM32LowPowerEncoder driver utilizes the hardware encoder mode of STM32 MCU LPTIM (Low Power Timer) timers (typically LPTIM1 or LPTIM2).

Key Characteristics:

• Zero MCU Overhead: The hardware handles all encoder counting automatically.
• No Interrupts: This driver does not use interrupt handlers, reducing CPU load.
• Rotation Tracking Requirement: While the hardware counts pulses, you must call encoder.update() frequently (at least 2x per revolution) to ensure the driver correctly tracks full rotations.
• Sleep Mode Limitation: Although LPTIM timers can theoretically continue counting during MCU sleep, tracking full rotations in practice is difficult and not recommended.

// Example of the required update loop logic
void loop() {
    encoder.update(); // Must be called at least 2x per revolution
    motor.loopFOC();
}

The SimpleFOCRegisters.h file defines the list of registers known to SimpleFOC. This abstraction is the foundation for most communication features in the library, including:

• PacketCommander and Telemetry (Packet-based IO)
• I2CCommander (I2C-based IO)
• SettingsStorage
• PySimpleFOC (Python API)

All these components share the same register names and IDs. If you are implementing a custom communication protocol, it is highly recommended to base it on this Register abstraction to leverage existing serialization/deserialization code and maintain compatibility with the ecosystem.