stspin220.h

00001 /******************************************************//**
00002   * @file    stspin220.h 
00003   * @author  IPC Rennes
00004   * @version V1.1.0
00005   * @date    May 26th, 2016
00006   * @brief   Header for STSPIN220 driver (fully integrated microstepping motor driver)
00007   * @note    (C) COPYRIGHT 2016 STMicroelectronics
00008   ******************************************************************************
00009   * @attention
00010   *
00011   * <h2><center>&copy; COPYRIGHT(c) 2016 STMicroelectronics</center></h2>
00012   *
00013   * Redistribution and use in source and binary forms, with or without modification,
00014   * are permitted provided that the following conditions are met:
00015   *   1. Redistributions of source code must retain the above copyright notice,
00016   *      this list of conditions and the following disclaimer.
00017   *   2. Redistributions in binary form must reproduce the above copyright notice,
00018   *      this list of conditions and the following disclaimer in the documentation
00019   *      and/or other materials provided with the distribution.
00020   *   3. Neither the name of STMicroelectronics nor the names of its contributors
00021   *      may be used to endorse or promote products derived from this software
00022   *      without specific prior written permission.
00023   *
00024   * THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
00025   * AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
00026   * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE
00027   * DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT HOLDER OR CONTRIBUTORS BE LIABLE
00028   * FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR CONSEQUENTIAL
00029   * DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF SUBSTITUTE GOODS OR
00030   * SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS INTERRUPTION) HOWEVER
00031   * CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY,
00032   * OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
00033   * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
00034   *
00035   ******************************************************************************
00036   */
00037 
00038 /* Define to prevent recursive inclusion -------------------------------------*/
00039 #ifndef __STSPIN220_H
00040 #define __STSPIN220_H
00041 
00042 #ifdef __cplusplus
00043  extern "C" {
00044 #endif 
00045 
00046 /* Includes ------------------------------------------------------------------*/
00047 #include "stspin220_target_config.h"
00048 #include "motor.h"
00049 
00050 /* Definitions ---------------------------------------------------------------*/
00051 
00052 /** @addtogroup Components
00053  * @{
00054  */
00055     
00056 /** @defgroup STSPIN220
00057   * @{
00058   */
00059 
00060 /** @defgroup Stspin220_Exported_Constants Stspin220 Exported Constants
00061   * @{
00062   */
00063 /// Current FW major version
00064 #define STSPIN220_FW_MAJOR_VERSION (uint8_t)(1)
00065 /// Current FW minor version
00066 #define STSPIN220_FW_MINOR_VERSION (uint8_t)(1)
00067 /// Current FW patch version
00068 #define STSPIN220_FW_PATCH_VERSION (uint8_t)(0)
00069 /// Current FW version
00070 #define STSPIN220_FW_VERSION       (uint32_t)((STSPIN220_FW_MAJOR_VERSION<<16)|\
00071                                               (STSPIN220_FW_MINOR_VERSION<<8)|\
00072                                               (STSPIN220_FW_PATCH_VERSION))
00073 
00074 /// Max position
00075 #define STSPIN220_MAX_POSITION           (0x7FFFFFFF)
00076 
00077 /// Min position
00078 #define STSPIN220_MIN_POSITION           (0x80000000)
00079 
00080 /// Position range
00081 #define STSPIN220_POSITION_RANGE         ((uint32_t)(STSPIN220_MAX_POSITION -\
00082                                                         STSPIN220_MIN_POSITION))
00083 /// STSPIN220 error base number
00084 #define STSPIN220_ERROR_BASE             (0xA000)
00085 
00086 /// run bit mask
00087 #define STSPIN220_RUN_BIT_MASK           (0x01)
00088 
00089 /// move bit mask
00090 #define STSPIN220_MOVE_BIT_MASK          (0x02)
00091 
00092 /// soft stop bit mask
00093 #define STSPIN220_SOFT_STOP_BIT_MASK     (0x04)
00094    
00095 /// direction change bit mask
00096 #define STSPIN220_DIR_CHANGE_BIT_MASK    (0x08)
00097 
00098 /// Maximum frequency of the step clock frequency in Hz
00099 #define STSPIN220_MAX_STCK_FREQ          (10000)
00100 
00101 /// Minimum frequency of the step clock frequency in Hz
00102 #define STSPIN220_MIN_STCK_FREQ          (8)
00103 
00104 /// Minimum duration of standby 
00105 #define STANDBY_MIN_DURATION             (1)
00106     
00107 /// Dead time after standby exit
00108 #define AFTER_STANDBY_EXIT_DEAD_TIME     (1)
00109 
00110 /// Reset delay to select step mode
00111 #define SELECT_STEP_MODE_DELAY           (1)
00112 
00113 /// PWM REF and bridges disable delay
00114 #define DISABLE_DELAY                    (1)
00115 
00116 /// Microstepping sequencer maximum value
00117 #define SEQUENCER_MAX_VALUE              (uint16_t)(0x3FF)
00118 
00119 /// MCU wait time after power bridges are enabled
00120 #define BRIDGE_TURN_ON_DELAY                                     (10)
00121 
00122 /// RC Filtering delay on the PWM
00123 #define PWM_FILTER_TIME_CONSTANT                                 (5)
00124 /**
00125   * @}
00126   */
00127 
00128 /* Types ---------------------------------------------------------------------*/
00129 
00130 /** @defgroup Stspin220_Exported_Types Stspin220 Exported Types
00131   * @{
00132   */
00133 
00134 /** @defgroup Error_Types Error Types
00135   * @{
00136   */
00137 /// Errors
00138 typedef enum {
00139   STSPIN220_ERROR_SET_HOME         = STSPIN220_ERROR_BASE,      /// Error while setting home position
00140   STSPIN220_ERROR_SET_MAX_SPEED    = STSPIN220_ERROR_BASE + 1,  /// Error while setting max speed
00141   STSPIN220_ERROR_SET_MIN_SPEED    = STSPIN220_ERROR_BASE + 2,  /// Error while setting min speed
00142   STSPIN220_ERROR_SET_ACCELERATION = STSPIN220_ERROR_BASE + 3,  /// Error while setting acceleration
00143   STSPIN220_ERROR_SET_DECELERATION = STSPIN220_ERROR_BASE + 4,  /// Error while setting decelaration
00144   STSPIN220_ERROR_MCU_OSC_CONFIG   = STSPIN220_ERROR_BASE + 5,  /// Error while configuring mcu oscillator
00145   STSPIN220_ERROR_MCU_CLOCK_CONFIG = STSPIN220_ERROR_BASE + 6,  /// Error while configuring mcu clock
00146   STSPIN220_ERROR_POSITION         = STSPIN220_ERROR_BASE + 7,  /// Unexpected current position (wrong number of steps)
00147   STSPIN220_ERROR_SPEED            = STSPIN220_ERROR_BASE + 8,  /// Unexpected current speed
00148   STSPIN220_ERROR_INIT             = STSPIN220_ERROR_BASE + 9,  /// Unexpected number of devices or unexpected value for predefined parameter
00149   STSPIN220_ERROR_SET_DIRECTION    = STSPIN220_ERROR_BASE + 10, /// Error while setting direction
00150   STSPIN220_ERROR_SET_STEP_MODE    = STSPIN220_ERROR_BASE + 11, /// Attempt to set an unsupported step mode
00151   STSPIN220_ERROR_APPLY_SPEED      = STSPIN220_ERROR_BASE + 12, /// Error while applying speed
00152   STSPIN220_ERROR_SET_TORQUE       = STSPIN220_ERROR_BASE + 13, /// Error while setting torque
00153   STSPIN220_ERROR_STEP_CLOCK       = STSPIN220_ERROR_BASE + 14  /// Error related to step clock
00154 }errorTypes_t;
00155 /**
00156   * @}
00157   */
00158 
00159 /** @defgroup Device_Commands Device Commands
00160   * @{
00161   */
00162 /// Device commands 
00163 typedef enum {
00164   NO_CMD              = 0x00, 
00165   RUN_CMD             = (STSPIN220_RUN_BIT_MASK),
00166   MOVE_CMD            = (STSPIN220_MOVE_BIT_MASK),
00167 } deviceCommand_t;
00168 /**
00169   * @}
00170   */
00171 
00172 /** @defgroup Device_Parameters Device Parameters
00173   * @{
00174   */
00175 /// Device Parameters Structure Type
00176 typedef struct {
00177     /// accumulator used to store speed increase smaller than 1 pps
00178     volatile uint32_t accu;           
00179     /// Position in microstep according to current step mode
00180     volatile int32_t currentPosition;
00181     /// Position of sequencer
00182     volatile int16_t sequencerPosition;
00183     /// mark position in microstep (motor position control mode)
00184     volatile int32_t markPosition;
00185     /// position in microstep at the end of the accelerating phase
00186     volatile uint32_t endAccPos;      
00187     /// nb of in microstep performed from the beggining of the goto or the move command 
00188     volatile uint32_t relativePos;    
00189     /// position in microstep step at the start of the decelerating phase
00190     volatile uint32_t startDecPos;    
00191     /// nb of microstep steps to perform for the goto or move commands
00192     uint32_t stepsToTake;
00193     
00194     /// constant speed phase torque value (%)
00195     volatile uint8_t runTorque;
00196     /// acceleration phase torque value (%)
00197     volatile uint8_t accelTorque;
00198     /// deceleration phase torque value (%)
00199     volatile uint8_t decelTorque;
00200     /// holding phase torque value (%)
00201     volatile uint8_t holdTorque;
00202     /// current selected torque value
00203     volatile uint8_t currentTorque;
00204     /// torque update
00205     volatile bool updateTorque;
00206     /// PWM frequency used to generate REF voltage
00207     volatile uint32_t refPwmFreq;
00208     /// torque boost enable
00209     volatile bool torqueBoostEnable;
00210     /// torque boost speed threshold
00211     volatile uint16_t torqueBoostSpeedThreshold;
00212     
00213     /// acceleration in pps^2 
00214     volatile uint16_t acceleration;
00215     /// deceleration in pps^2
00216     volatile uint16_t deceleration;
00217     /// max speed in pps (speed use for goto or move command)
00218     volatile uint16_t maxSpeed;
00219     /// min speed in pps
00220     volatile uint16_t minSpeed;
00221     /// current speed in pps
00222     volatile uint16_t speed;
00223     
00224     /// command under execution
00225     volatile deviceCommand_t commandExecuted; 
00226     /// FORWARD or BACKWARD direction
00227     volatile motorDir_t direction;                 
00228     /// current state of the device
00229     volatile motorState_t motionState;
00230     /// current step mode
00231     volatile motorStepMode_t stepMode;
00232     /// latched step mode
00233     motorStepMode_t stepModeLatched;
00234     /// current stop mode
00235     motorStopMode_t stopMode;
00236     
00237 }deviceParams_t; 
00238 /**
00239   * @}
00240   */
00241 
00242 /// Motor driver initialization structure definition  
00243 typedef struct
00244 {
00245   /// acceleration in pps^2
00246   uint16_t acceleration;
00247   /// deceleration in pps^2
00248   uint16_t deceleration;
00249   /// max speed in pps (speed use for goto or move command)
00250   uint16_t maxSpeed;
00251   /// min speed in pps
00252   uint16_t minSpeed;
00253   /// acceleration phase torque value (%)
00254   uint8_t accelTorque;
00255   /// deceleration phase torque value (%)
00256   uint8_t decelTorque;
00257   /// constant speed phase torque value (%)
00258   uint8_t runTorque;
00259   /// holding phase torque value (%)
00260   uint8_t holdTorque;
00261   /// torque boost enable
00262   bool torqueBoostEnable;
00263   /// torque boost speed threshold
00264   uint16_t torqueBoostSpeedThreshold;
00265   /// step mode
00266   motorStepMode_t stepMode;
00267   /// stop mode
00268   motorStopMode_t stopMode;
00269   /// PWM frequency used to generate REF voltage
00270   uint32_t vrefPwmFreq;
00271 } Stspin220_Init_t;
00272 /**
00273   * @}
00274   */
00275 
00276 /**
00277   * @}
00278   */
00279 
00280 /* Functions --------------------------------------------------------*/
00281 
00282 /** @defgroup MotorControl_Board_Linked_Functions MotorControl Board Linked Functions
00283   * @{
00284   */
00285 ///Delay of the requested number of milliseconds
00286 extern void Stspin220_Board_Delay(uint32_t delay);
00287 ///Enable Irq
00288 extern void Stspin220_Board_EnableIrq(void);
00289 ///Disable Irq
00290 extern void Stspin220_Board_DisableIrq(void);
00291 ///Setting the Stck Timeout delay and attaching a callback function to it
00292 extern void Stspin220_Board_TimStckSetFreq(uint16_t newFreq);
00293 ///Initialises the step clock pin level
00294 extern void Stspin220_Board_TimStckInit(void);
00295 ///Stopping the Timeout
00296 extern uint8_t Stspin220_Board_TimStckStop(volatile uint8_t *pToggleOdd);
00297 ///Set the duty cycle of the PwmOut used for the REF
00298 extern void Stspin220_Board_PwmRefSetDutyCycle(uint8_t dutyCycle);
00299 ///Set the frequency of the PwmOut used for the REF
00300 extern void Stspin220_Board_PwmRefSetFreq(uint32_t newFreq);
00301 ///Start the reference voltage pwm
00302 extern void Stspin220_Board_PwmRefStart(void);
00303 ///Reset the STSPIN220 reset pin
00304 extern void Stspin220_Board_ReleaseReset(void);
00305 ///Set the STSPIN220 reset pin 
00306 extern void Stspin220_Board_Reset(void);
00307 ///Set direction GPIO
00308 extern void Stspin220_Board_SetDirectionGpio(uint8_t gpioState);
00309 ///Reset the STCK\MODE3 pin
00310 extern void Stspin220_Board_StckMode3_Reset(void);
00311 ///Set the STCK\MODE3 pin
00312 extern void Stspin220_Board_StckMode3_Set(void);
00313 ///Enable the power bridges (leave the output bridges HiZ)
00314 extern void Stspin220_Board_Enable(void); 
00315 ///Disable the power bridges (leave the output bridges HiZ)    
00316 extern void Stspin220_Board_Disable(void); 
00317 ///Select the STSPIN220 mode1, mode2, mode3 and mode4 pins levels
00318 extern bool Stspin220_Board_SetModePins(uint8_t modePin1Level,\
00319   uint8_t modePin2Level,\
00320   uint8_t modePin3Level,\
00321   uint8_t modePin4Level);
00322 ///Select Full Step mode
00323 extern void Stspin220_Board_SetFullStep(void);
00324 ///Unselect Full Step mode
00325 extern void Stspin220_Board_UnsetFullStep(void);
00326 /**
00327   * @}
00328   */
00329 
00330   /**
00331   * @}
00332   */
00333 
00334 /**
00335   * @}
00336   */
00337   
00338 #ifdef __cplusplus
00339   }
00340 #endif
00341 
00342 #endif /* #ifndef __STSPIN220_H */
00343 
00344 /******************* (C) COPYRIGHT 2016 STMicroelectronics *****END OF FILE****/