added STM32SpeedDirCommander

Author: Richard Unger

README.md

@@ -10,17 +10,11 @@ The intent is to keep the core of SimpleFOC clean, and thus easy to maintain, un
 
 ## New Release
 
-v1.0.3 - Released March 2023, for Simple FOC 2.3.0
-
-What's changed since 1.0.2?
-- New Sensor: MT6835
-- Fixed bugs
-
-What's changed since 1.0.1?
-- Calibrated sensor by @MarethyuPrefect
-- New Sensors: MT6701, MA330, MT6816
-- Fixed bugs
+v1.0.4 - Released May 2023, for Simple FOC 2.3.0
 
+What's changed since 1.0.3?
+- New Input: STM32SpeedDirCommander
+- Fixed MT6835 driver bugs
 
 ## What is included
 
@@ -49,6 +43,11 @@ What is here? See the sections below. Each driver or function should come with i
 ### Communications
 
  - [I2CCommander I2C driver](src/comms/i2c/) - I2C communications protocol and drivers for both controller and target devices. 
+ - [STM32 SpeedDir Input](src/comms/stm32speeddir/) - Control target velocity with PWM speed and direction inputs
+
+### Utilities
+
+ - [STM32 PWM Input driver](src/utilities/stm32pwm/) - PWM Input driver for STM32 MCUs. Accurately measure PWM inputs with zero MCU overhead.
 
 
 ## How to use
@@ -74,3 +73,14 @@ If you do so, please be sure to adhere to and include the [LICENSE](https://gith
 ## Further Documentation
 
 Find out more information about the Arduino SimpleFOC project on the [docs website](https://docs.simplefoc.com/) 
+
+## Release History
+
+What's changed since 1.0.2?
+- New Sensor: MT6835
+- Fixed bugs
+
+What's changed since 1.0.1?
+- Calibrated sensor by @MarethyuPrefect
+- New Sensors: MT6701, MA330, MT6816
+- Fixed bugs

src/comms/stm32speeddir/README.md

@@ -0,0 +1,58 @@
+
+# STM32SpeedDirInput
+
+Control SimpleFOC using PWM speed and direction inputs.
+
+Based on STM32 timer PWM-Input capabilities, which means this can only be used on STM32 MCUs. It can cover a wide range of PWM frequencies, and runs without MCU overhead in the timer hardware.
+
+
+
+## Setup
+
+The PWM speed input should be connected to either channel 1 or channel 2 of a general purpose or advanced control timer on your STM32 MCU. Suitable timers are:
+- Advanced control timers: TIM1, TIM8
+- General purpose timers (32 bit): TIM2, TIM5
+- General purpose timers (16 bit): TIM3, TIM4, TIM9, TIM12
+If in doubt, check in STM32CubeIDE and see if the PWM-Input mode can be enabled (under "Combined Channels") for the timer.
+
+The optional direction input can be connected to any GPIO pin. By default a high level direction input is associated with a positive velocity value, while a low level direction input results in a negative velocity value. To reverse this, set the option `dir_positive_high = false`
+
+The direction input is optional - if not provided, you can control the direction from software using the `direction` field.
+
+The velocity values returned are in the range `min_speed` to `max_speed`, while the input PWM duty cycle should lie within the range `min_pwm` to `max_pwm`. Actual input values smaller than `min_pwm` will be treated as `min_pwm`, values larger than `max_pwm` will be treated as `max_pwm`. The behaviour for 100% or 0% duty cycles is undefined, and they should be avoided.
+
+## Usage
+
+Use it like this:
+
+```c++
+#include "comms/stm32speeddir/STM32SpeedDirInput.h"
+
+// some example pins - the speed pin has to be on channel 1 or 2 of a timer
+#define PIN_SPEED PC6
+#define PIN_DIRECTION PB8
+
+STM32SpeedDirInput speed_dir = STM32SpeedDirInput(PIN_SPEED, PIN_DIRECTION);
+
+float target = 0.0f;
+
+void setup(){
+    ...
+
+    speed_dir.min_speed = 10.0f;    // 10rad/s min speed
+    speed_dir.max_speed = 100.0f;   // 100rad/s max speed
+    speed_dir.min_pwm = 5.0f;       // 5% min duty cycle
+    speed_dir.max_pwm = 95.0f;      // 95% max duty cycle
+    speed_dir.init();
+
+    ...
+}
+
+
+void loop(){
+    target = speed_dir.getTargetVelocity();
+    motor.move(target);
+    motor.loopFOC();
+}
+
+```

src/comms/stm32speeddir/STM32SpeedDirInput.cpp

@@ -0,0 +1,29 @@
+
+#include "./STM32SpeedDirInput.h"
+
+#if defined(_STM32_DEF_)
+
+STM32SpeedDirInput::STM32SpeedDirInput(int pin_speed, int pin_dir) : STM32PWMInput(pin_speed) {
+    _pin_speed = pin_speed;
+    _pin_dir = pin_dir;
+};
+
+STM32SpeedDirInput::~STM32SpeedDirInput(){};
+
+int STM32SpeedDirInput::init(){
+    pinMode(_pin_dir, INPUT);
+    return STM32PWMInput::init();
+};
+
+
+float STM32SpeedDirInput::getTargetVelocity(){
+    if (_pin_dir != NOT_SET)
+        direction = digitalRead(_pin_dir);
+    float speed = getDutyCyclePercent();
+    speed = constrain(speed, min_pwm, max_pwm);
+    speed = (speed - min_pwm)/(max_pwm - min_pwm) * (max_speed - min_speed) + min_speed;
+    return (direction == dir_positive_high) ? speed : -speed;
+};
+
+
+#endif

src/comms/stm32speeddir/STM32SpeedDirInput.h

@@ -0,0 +1,31 @@
+
+#pragma once
+
+#include "Arduino.h"
+
+#if defined(_STM32_DEF_)
+
+#include "common/foc_utils.h"
+#include "utilities/stm32pwm/STM32PWMInput.h"
+
+class STM32SpeedDirInput : public STM32PWMInput {
+    public:
+        STM32SpeedDirInput(int pin_speed, int pin_dir = NOT_SET);
+        ~STM32SpeedDirInput();
+
+        int init();
+        float getTargetVelocity();
+
+        float min_speed = 0;            // min speed in rad/s
+        float max_speed = 100;          // max speed in rad/s
+        float min_pwm = 5.0;            // min duty cycle in %
+        float max_pwm = 95.0;           // max duty cycle in %
+        bool dir_positive_high = true;  // true if the direction pin is high when the motor is spinning in the positive direction
+        bool direction = true;          // direction of rotation, default positive
+    protected:
+        int _pin_speed;
+        int _pin_dir;
+};
+
+
+#endif

src/utilities/stm32pwm/README.md

@@ -0,0 +1,73 @@
+
+# STM32 Utilities - PWM Input
+
+Using the `STM32PWMInput` class you can precisely read a PWM input signal on STM32 MCUs by using their timer's PWM-Input mode. This happens entirely in the timer hardware with zero MCU overhead, and is very precise.
+
+## Setup
+
+Connect the PWM input to either channel 1 or channel 2 of a general purpose or advanced control timer supporting PWM-Input mode.
+
+This should include the following timers:
+
+- Advanced control timers: TIM1, TIM8
+- General purpose timers (32 bit): TIM2, TIM5
+- General purpose timers (16 bit): TIM3, TIM4, TIM9, TIM12
+
+The best to use are the 32 bit general purpose timers, although TIM1 may also be interesting because on some MCUs it can be clocked at a higher rate than the other timers.
+
+## Usage
+
+```
+  STM32PWMInput pwmInput = STM32PWMInput(PA15);
+  pwmInput.init();
+
+  uint32_t periodTicks = pwmInput.getPeriodTicks();
+  uint32_t dutyTicks = pwmInput.getDutyCycleTicks();
+  float dutyPercent = pwmInput.getDutyCyclePercent();
+```
+
+## Input signal
+
+The input signal should be a PWM signal (square wave) with a duty cycle that is >0% and <100%. The 
+
+The behaviour if the input is not a square wave is not defined, although the MCU will continue to sample the input, and resumes correct measurement when the square wave input is restored.
+
+## Performance
+
+The range of PWM frequencies that can be measured and the resolution with which they can be sampled depends on the following:
+
+- timer clock speed - normally this is your MCU speed, but it can be lower, or in some cases even higher. 
+- timer prescaler - can divide the timer clock.
+
+The sample resolution for a PWM input signal of frequency _Fp_ is given by
+
+_R = Fc / Fp_
+
+Where _R_ is the resolution in ticks, and _Fc_ is the timer tick frequency (timer clock with prescaler).
+
+This sample resolution is equal to the length of the PWM period in ticks. The timer needs to sample both the duty cycle and the full period, so the timer can't sample signals whose period would cause it to overflow. 
+
+On a 16 bit timer this means the period (and sample resolution) must be less than 65536 ticks, while on a 32 bit timer it must be less than 4294967296 ticks. This places a lower limit on the PWM frequencies that can be sampled.
+
+On the other side, the minimum duty cycle that can be reliably captured is limited by the duration of one timer tick, e.g. the minimum on-time that can be measured reliably is equal to two timer ticks in duration.
+
+So as the frequency increases, the resolution decreases, and the minimum duty cycle increases.
+
+For example, on a 64MHz STM32 MCU, using TIM3 (16 bit) you could capture a PWM signal at 10kHz with a resolution of 6400 ticks. This fits in the 16 bit timer, so no problem. Assuming the signal is perfectly stable (it usually isn't) that would be 12 bits of accuracy on your input. 
+
+If you lowered the PWM input frequency to 1kHz, you'd get a 64000 range - just fitting in the timer. But now the accuracy is greatly increased - almost 16 bits!
+
+If you increased the PWM frequency to 10Mhz, the resolution would be just 6 ticks, and the resulting accuracy very low - just 2 bits, with a minimum duty cycle of 33% and a maximum of 66%.
+
+Of course you could vary the 10MHz signal faster than the 1kHz one - so choosing the PWM input frequency is a tradeoff between accuracy and control bandwidth...
+
+Note: clock configuration is out of scope for this class. Set your clocks up in advance.
+
+
+
+## Roadmap
+
+- Support setting of the filtering function, this could help a lot against noise on the input
+- Support setting of the timer prescaler (not the clock prescaler!)
+- Support setting of the downsample function, this could help increase accuracy
+- Support choosing of the alternate timers on pins with more than one

src/utilities/stm32pwm/STM32PWMInput.cpp

@@ -0,0 +1,100 @@
+
+#include "./STM32PWMInput.h"
+
+#if defined(_STM32_DEF_)
+
+
+
+STM32PWMInput::STM32PWMInput(int pin){
+    _pin = pin;
+};
+
+
+STM32PWMInput::~STM32PWMInput(){};
+
+
+
+
+
+int STM32PWMInput::init(){
+    PinName pinN = digitalPinToPinName(_pin);
+    pinmap_pinout(pinN, PinMap_TIM);
+    uint32_t channel = STM_PIN_CHANNEL(pinmap_function(pinN, PinMap_TIM));
+    timer.Instance = (TIM_TypeDef *)pinmap_peripheral(pinN, PinMap_TIM);
+    timer.Init.Prescaler = 0;
+    timer.Init.CounterMode = TIM_COUNTERMODE_UP;
+    timer.Init.Period = 4.294967295E9;    // TODO max period, depends on which timer is used - 32 bits or 16 bits
+    timer.Init.ClockDivision = TIM_CLOCKDIVISION_DIV1;
+    timer.Init.AutoReloadPreload = TIM_AUTORELOAD_PRELOAD_DISABLE;
+    if (HAL_TIM_Base_Init(&timer) != HAL_OK) {
+        return -1;
+    }
+    TIM_ClockConfigTypeDef clkCfg = { .ClockSource=TIM_CLOCKSOURCE_INTERNAL };
+    if (HAL_TIM_ConfigClockSource(&timer, &clkCfg) != HAL_OK) {
+        return -2;
+    }
+    if (HAL_TIM_IC_Init(&timer) != HAL_OK) {
+        return -3;
+    }
+
+    TIM_SlaveConfigTypeDef slCfg = {
+        .SlaveMode = TIM_SLAVEMODE_RESET,
+        .InputTrigger = (channel==1)?TIM_TS_TI1FP1:TIM_TS_TI2FP2,
+        .TriggerPolarity = TIM_INPUTCHANNELPOLARITY_RISING,
+        .TriggerPrescaler = TIM_ICPSC_DIV1,
+        .TriggerFilter = 0
+    };
+    if (HAL_TIM_SlaveConfigSynchro(&timer, &slCfg) != HAL_OK) {
+        return -4;
+    }
+    TIM_IC_InitTypeDef icCfg = {
+        .ICPolarity = TIM_INPUTCHANNELPOLARITY_RISING,
+        .ICSelection = (channel==1)?TIM_ICSELECTION_DIRECTTI:TIM_ICSELECTION_INDIRECTTI,
+        .ICPrescaler = TIM_ICPSC_DIV1,
+        .ICFilter = 0
+    };
+    if (HAL_TIM_IC_ConfigChannel(&timer, &icCfg, TIM_CHANNEL_1) != HAL_OK) {
+        return -5;
+    }
+    icCfg.ICPolarity = TIM_INPUTCHANNELPOLARITY_FALLING;
+    icCfg.ICSelection = (channel==1)?TIM_ICSELECTION_INDIRECTTI:TIM_ICSELECTION_DIRECTTI;
+    if (HAL_TIM_IC_ConfigChannel(&timer, &icCfg, TIM_CHANNEL_2) != HAL_OK) {
+        return -6;
+    }
+    TIM_MasterConfigTypeDef mCfg = {
+        .MasterOutputTrigger = TIM_TRGO_RESET,
+        .MasterSlaveMode = TIM_MASTERSLAVEMODE_DISABLE
+    };
+    if (HAL_TIMEx_MasterConfigSynchronization(&timer, &mCfg) != HAL_OK) {
+        return -7;
+    }
+    if (HAL_TIM_IC_Start(&timer, TIM_CHANNEL_1)!=HAL_OK) {
+        return -8;
+    }
+    if (HAL_TIM_IC_Start(&timer, TIM_CHANNEL_2)!=HAL_OK) {
+        return -9;
+    }
+    timer.Instance->CR1 |= TIM_CR1_CEN;
+    return 0;
+};
+
+
+float STM32PWMInput::getDutyCyclePercent(){
+    uint32_t period = getPeriodTicks();
+    if (period<1) return 0.0f;
+    return getDutyCycleTicks() / (float)period * 100.0f;
+};
+
+
+uint32_t STM32PWMInput::getDutyCycleTicks(){
+    return timer.Instance->CCR2;
+};
+
+
+uint32_t STM32PWMInput::getPeriodTicks(){
+    return timer.Instance->CCR1;
+};
+
+
+
+#endif

src/utilities/stm32pwm/STM32PWMInput.h

@@ -0,0 +1,27 @@
+#pragma once
+
+#include "Arduino.h"
+
+#if defined(_STM32_DEF_)
+
+
+class STM32PWMInput {
+    public:
+        STM32PWMInput(int pin);
+        ~STM32PWMInput();
+
+        int init();
+
+        float getDutyCyclePercent();
+        uint32_t getDutyCycleTicks();
+        uint32_t getPeriodTicks();
+    protected:
+        int _pin;
+        TIM_HandleTypeDef timer;
+};
+
+
+
+
+
+#endif