1035 lines
40 KiB
C
1035 lines
40 KiB
C
/*
|
|
* LibL6474.h
|
|
*
|
|
* Created on: Dec 2, 2024
|
|
* Author: Thorsten
|
|
*/
|
|
|
|
/*! \file */
|
|
|
|
#ifndef INC_LIBL6474_H_
|
|
#define INC_LIBL6474_H_ INC_LIBL6474_H_
|
|
|
|
/*!
|
|
* The LibL6474Config.h must be provided by the user project. The header in conf folder is only a template!
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
#include "LibL6474Config.h"
|
|
|
|
|
|
/*!
|
|
* The L6474x_State_t enum is used to describe the current state of the driver library which helps
|
|
* the user to decide the next steps to be taken or to get notified about an unexpected state which is caused
|
|
* by an error
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef enum L6474x_State
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* stRESET is used to signal the initial power up state or a full device reset state in which the chip is kept
|
|
* until the user releases a reset state
|
|
*/
|
|
stRESET = 0x00,
|
|
|
|
/*!
|
|
* stDISABLED is used to signal the ready but disabled state of the chip. It is kept in this step until the
|
|
* user enables the power output stages
|
|
*/
|
|
stDISABLED = 0x01,
|
|
|
|
/*!
|
|
* stENABLED is used to signal the ready and enabled state of the chip. It is kept in this step until the
|
|
* user disables the power output stages or an error happens
|
|
*/
|
|
stENABLED = 0x02,
|
|
|
|
/*!
|
|
* stINVALID is used to signal a state which requires user interaction because something is completely wrong
|
|
* in regular cases, this state can not be present. This is an indicator of memory corruption or misleading
|
|
* usage of the library
|
|
*/
|
|
stINVALID = 0x04
|
|
|
|
} L6474x_State_t;
|
|
|
|
|
|
/*!
|
|
* The L6474x_StepMode_t enum is used to describe the current step mode (resolution) of the driver library and the
|
|
* stepper motor. This changes the internal calculations for speed and position and requires a new reference run in
|
|
* case it will be changed at runtime.
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef enum L6474x_StepMode
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* smFULL requires minimum of 4 steps for a full turn of the motor axis. This mode results in the highest torque but in
|
|
* the most noisy operation and the lowest resolution
|
|
*/
|
|
smFULL = 0x00,
|
|
|
|
/*!
|
|
* smHALF requires minimum of 8 steps for a full turn of the motor axis. better resolution but less torque
|
|
*/
|
|
smHALF = 0x01,
|
|
|
|
/*!
|
|
* smMICRO4 requires minimum of 16 steps for a full turn of the motor axis. better resolution but less torque
|
|
*/
|
|
smMICRO4 = 0x02,
|
|
|
|
/*!
|
|
* smMICRO8 requires minimum of 32 steps for a full turn of the motor axis. better resolution but less torque
|
|
*/
|
|
smMICRO8 = 0x03,
|
|
|
|
/*!
|
|
* smMICRO16 requires minimum of 64 steps for a full turn of the motor axis. better resolution but less torque
|
|
*/
|
|
smMICRO16 = 0x04
|
|
} L6474x_StepMode_t;
|
|
|
|
/*!
|
|
* The L6474x_Direction_t enum describes the direction of the driver and therefore the rotation of the stepper axis.
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef enum L6474x_Direction
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* dirFOREWARD is interpreted as clock wise rotation
|
|
*/
|
|
dirFOREWARD = 0x00,
|
|
|
|
/*!
|
|
* dirFOREWARD is interpreted as counter clock wise rotation
|
|
*/
|
|
dirBACKWARD = 0x01
|
|
} L6474x_Direction_t;
|
|
|
|
/*!
|
|
* The L6474x_ErrorCode_t enum describes the possible error codes when using the API commands. Those error codes are
|
|
* mostly returned as return value by the API function which has been called previously
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef enum L6474x_ErrorCode
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* errcNONE means no error and the operation was successful
|
|
*/
|
|
errcNONE = 0,
|
|
|
|
/*!
|
|
* errcINV_ARG means that at least one argument was invalid or out of range
|
|
*/
|
|
errcINV_ARG = -1,
|
|
|
|
/*!
|
|
* errcNULL_ARG means that at least one argument was a null pointer where it was not expected
|
|
*/
|
|
errcNULL_ARG = -2,
|
|
|
|
/*!
|
|
* errcINV_STATE means that the stepper driver or the library is not in the state of type L6474x_State_t and
|
|
* therefore the operation can not be executed
|
|
*/
|
|
errcINV_STATE = -3,
|
|
|
|
/*!
|
|
* errcINTERNAL means an error which happens when calling abstraction functions which then return an error code
|
|
*/
|
|
errcINTERNAL = -4,
|
|
|
|
/*!
|
|
* errcLOCKING in case the library is used multi-threaded, it might happen, that a function can not be locked
|
|
* because another caller is still using the library (lock guard principle). In mutex case this should not
|
|
* be returned by the API
|
|
*/
|
|
errcLOCKING = -5,
|
|
|
|
/*!
|
|
* errcDEVICE_STATE means that the state of the driver chip permits the operation
|
|
*/
|
|
errcDEVICE_STATE = -6,
|
|
|
|
/*!
|
|
* errcPENDING means that another operation is still pending and therefore the operation can not be executed
|
|
* while there is still a pending one
|
|
*/
|
|
errcPENDING = -7,
|
|
|
|
/*!
|
|
* errcFORBIDDEN means that operation is not possible with the given arguments or this library
|
|
*/
|
|
errcFORBIDDEN = -8
|
|
|
|
} L6474x_ErrorCode_t;
|
|
|
|
|
|
/*!
|
|
* The L6474_Status_t enum describes the status register content of the stepper driver chip. It is reinterpreted
|
|
* so it can be naturally used in the code to get some of the error codes or state bits of the driver.
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef struct L6474_Status
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* high impedance state active
|
|
*/
|
|
unsigned char HIGHZ ;
|
|
|
|
/*!
|
|
* direction is clock wise or counter clock wise
|
|
*/
|
|
unsigned char DIR ;
|
|
|
|
/*!
|
|
* a command has not been performed
|
|
*/
|
|
unsigned char NOTPERF_CMD;
|
|
|
|
/*!
|
|
* a command was invalid
|
|
*/
|
|
unsigned char WRONG_CMD ;
|
|
|
|
/*!
|
|
* under-voltage lock out
|
|
*/
|
|
unsigned char UVLO ;
|
|
|
|
/*!
|
|
* threshold warning
|
|
*/
|
|
unsigned char TH_WARN ;
|
|
|
|
/*!
|
|
* thermal shutdown
|
|
*/
|
|
unsigned char TH_SD ;
|
|
|
|
/*!
|
|
* over current detection (short circuit)
|
|
*/
|
|
unsigned char OCD ;
|
|
|
|
/*!
|
|
* movement is ongoing (pending)
|
|
*/
|
|
unsigned char ONGOING ;
|
|
} L6474_Status_t;
|
|
|
|
|
|
/*!
|
|
* The L6474x_OCD_TH_t enum describes the possible overcurrent threshold values which can be set in the library
|
|
* and which are then taken into account by the stepper driver
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef enum L6474x_OCD_TH
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
ocdth375mA = 0x00,
|
|
ocdth750mA = 0x01,
|
|
ocdth1125mA = 0x02,
|
|
ocdth1500mA = 0x03,
|
|
ocdth1875mA = 0x04,
|
|
ocdth2250mA = 0x05,
|
|
ocdth2625mA = 0x06,
|
|
ocdth3000mA = 0x07,
|
|
ocdth3375mA = 0x08,
|
|
ocdth3750mA = 0x09,
|
|
ocdth4125mA = 0x0A,
|
|
ocdth4500mA = 0x0B,
|
|
ocdth4875mA = 0x0C,
|
|
ocdth5250mA = 0x0D,
|
|
ocdth5625mA = 0x0E,
|
|
ocdth6000mA = 0x0F
|
|
} L6474x_OCD_TH_t;
|
|
|
|
/*!
|
|
* The L6474_Handle_t handle is an instance pointer of the driver library which is generated whenever
|
|
* the L6474_CreateInstance function returns with success. Therefore at least a L6474x_Platform_t
|
|
* platform description pointer is required
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef struct L6474_Handle* L6474_Handle_t;
|
|
|
|
|
|
/*!
|
|
* The L6474x_Platform_t structure is used to encapsulate platform specific parameters and to provide environment
|
|
* specific functions in a generalized format. Theses functions are malloc and free or some PWM and GPIO abstractions
|
|
* The lock guards and thread safety mechanisms are also abstracted by this structure
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef struct L6474x_Platform
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* classic malloc function pointer which returns null in case of an error or a memory void* pointer with the
|
|
* given size by the first argument. The user must provide this function as part of the platform abstraction.
|
|
* The minimal functionality can be reached by providing a function which simply calls malloc.
|
|
*
|
|
* @param[in] size number of bytes requested by the memory allocation request
|
|
*
|
|
* The behavior is schematically as follows:
|
|
* @startuml
|
|
* Library -> platform_malloc_function : Requests dynamic memory
|
|
* platform_malloc_function -> stdlib : call malloc
|
|
* platform_malloc_function <- stdlib
|
|
* Library <- platform_malloc_function : returns memory pointer
|
|
* @enduml
|
|
*/
|
|
void* (*malloc) ( unsigned int size );
|
|
|
|
/*!
|
|
* classic free function pointer which releases memory previously allocated by malloc.
|
|
* The user must provide this function as part of the platform abstraction.
|
|
* The minimal functionality can be reached by providing a function which simply calls free in case
|
|
* The malloc abstraction function is a call to malloc.
|
|
*
|
|
* @param[in] pMem pointer of the memory space which shall be freed
|
|
*
|
|
* The behavior is schematically as follows:
|
|
* @startuml
|
|
* Library -> platform_free_function : Requests release of allocated memory
|
|
* platform_free_function -> stdlib : call free
|
|
* platform_free_function <- stdlib
|
|
* Library <- platform_free_function
|
|
* @enduml
|
|
*/
|
|
void (*free) ( const void* const pMem );
|
|
|
|
/*!
|
|
* the transfer function is used to provide bus access to the stepper driver chip
|
|
*
|
|
* @param[in,out] pIO optional user context pointer which has been passed by the L6474_CreateInstance call
|
|
* @param[out] pRX pointer to the receive data buffer
|
|
* @param[in] pTX pointer to the transmit data buffer
|
|
* @param[in] length number of bytes for RX and TX
|
|
*
|
|
* The behavior is schematically as follows:
|
|
* @startuml
|
|
* Library -> platform_transfer_function : Requests read and write simultaneously
|
|
* loop num of bytes
|
|
* platform_transfer_function -> gpio_driver : CS low
|
|
* platform_transfer_function <- gpio_driver
|
|
* platform_transfer_function -> spi_driver : 1 byte rx + tx
|
|
* platform_transfer_function <- spi_driver
|
|
* platform_transfer_function -> gpio_driver : CS high
|
|
* platform_transfer_function <- gpio_driver
|
|
* end
|
|
* Library <- platform_transfer_function
|
|
* @enduml
|
|
*/
|
|
int (*transfer) ( void* pIO, char* pRX, const char* pTX, unsigned int length );
|
|
|
|
/*!
|
|
* the reset function is used to provide gpio access to the reset of the stepper driver chip. keep in mind
|
|
* that the chip has a reset not pin and so the ena signal must be inverted to set the correct reset level
|
|
* physically
|
|
*
|
|
* @param[in,out] pGPO optional user context pointer which has been passed by the L6474_CreateInstance call
|
|
* @param[in] ena output state to set without level inversion
|
|
*
|
|
* The behavior is schematically as follows:
|
|
* @startuml
|
|
* Library -> platform_reset_function : Requests reset of the chip
|
|
* platform_reset_function -> gpio_driver : set pin to !ena
|
|
* platform_reset_function <- gpio_driver
|
|
* Library <- platform_reset_function
|
|
* @enduml
|
|
*/
|
|
void (*reset) ( void* pGPO, const int ena );
|
|
|
|
/*!
|
|
* the sleep function implements a wait time with the argument in milliseconds
|
|
*
|
|
* @param[in] ms time to sleep in milliseconds
|
|
*
|
|
* The behavior is schematically as follows:
|
|
* @startuml
|
|
* Library -> platform_sleep_function : Requests sleep by the library
|
|
* platform_sleep_function -> scheduler : sleep(ms)
|
|
* platform_sleep_function <- scheduler
|
|
* Library <- platform_sleep_function
|
|
* @enduml
|
|
*/
|
|
void (*sleep) ( unsigned int ms );
|
|
|
|
#if defined(LIBL6474_STEP_ASYNC) && ( LIBL6474_STEP_ASYNC == 0 )
|
|
/*!
|
|
* the step function is a synchronous blocking function until the movement has been fully executed.
|
|
* This can be e.g. a PWM generation via GPIO pulsing given by the numPulses argument
|
|
*
|
|
* @param[in,out] pPWM optional user context pointer which has been passed by the L6474_CreateInstance call
|
|
* @param[in] dir output signal to drive the stepper clock wise or counter clockwise
|
|
* @param[in] numPulses number of high and low transitions to generate a pulse for the stepper chip
|
|
*
|
|
* The behavior is schematically as follows:
|
|
* @startuml
|
|
* Library -> platform_step_function : Requests generating pulses async
|
|
* loop 'numPulses' times
|
|
* platform_step_function -> gpio_driver : Set high
|
|
* platform_step_function <- gpio_driver
|
|
* platform_step_function -> scheduler : sleep(ms)
|
|
* platform_step_function <- scheduler
|
|
* platform_step_function -> gpio_driver : Set low
|
|
* platform_step_function <- gpio_driver
|
|
* platform_step_function -> scheduler : sleep(ms)
|
|
* platform_step_function <- scheduler
|
|
* end
|
|
* Library <- platform_step_function
|
|
* @enduml
|
|
*/
|
|
int (*step) ( void* pPWM, int dir, unsigned int numPulses );
|
|
#else
|
|
/*!
|
|
* the stepAsync function is an asynchronous non-blocking function which e.g. enables a timer which then generates
|
|
* the required amount of pulses given by the numPulses argument. The doneCLB is a callback provided by the library
|
|
* which is called when the asynchronous operation has been done
|
|
*
|
|
* @param[in,out] pPWM optional user context pointer which has been passed by the L6474_CreateInstance call
|
|
* @param[in] dir output signal to drive the stepper clock wise or counter clockwise
|
|
* @param[in] numPulses number of high and low transitions to generate a pulse for the stepper chip
|
|
* @param[in] doneClb callback function pointer, which is required to be called after the async process has been finished
|
|
* @param[in] h handle pointer which is at least required by the callback of doneClb argument
|
|
*
|
|
* The behavior is schematically as follows:
|
|
* @startuml
|
|
* Library ->> platform_step_function : Requests generating pulses async
|
|
* loop 'numPulses' times
|
|
* platform_step_function -> gpio_driver : Set high
|
|
* platform_step_function <- gpio_driver
|
|
* platform_step_function -> scheduler : sleep(ms)
|
|
* platform_step_function <- scheduler
|
|
* platform_step_function -> gpio_driver : Set low
|
|
* platform_step_function <- gpio_driver
|
|
* platform_step_function -> scheduler : sleep(ms)
|
|
* platform_step_function <- scheduler
|
|
* end
|
|
* @enduml
|
|
*/
|
|
int (*stepAsync) ( void* pPWM, int dir, unsigned int numPulses, void (*doneClb)(L6474_Handle_t), L6474_Handle_t h );
|
|
|
|
/*!
|
|
* the cancelStep function is a synchronous blocking function which cancels the asynchronous previously started step
|
|
* operation in case it has not been finished
|
|
*
|
|
* @param[in,out] pPWM optional user context pointer which has been passed by the L6474_CreateInstance call
|
|
*/
|
|
int (*cancelStep)( void* pPWM );
|
|
#endif
|
|
|
|
#if defined(LIBL6474_HAS_LOCKING) && LIBL6474_HAS_LOCKING == 1
|
|
/*!
|
|
* in case the library provides locking functions, this function locks the API for thread safety
|
|
*/
|
|
int (*lock) ( void );
|
|
|
|
/*!
|
|
* in case the library provides locking functions, this function unlocks the API to allow other callers to execute
|
|
* an API command
|
|
*/
|
|
void (*unlock) ( void );
|
|
#endif
|
|
|
|
#if defined(LIBL6474_HAS_FLAG) && LIBL6474_HAS_FLAG == 1
|
|
/*!
|
|
* in case the FLAG pin of the stepper driver chip is used, this function returns the current value of the FLAG pin.
|
|
* This is an optional abstraction function and is not required for regular operation because the library can
|
|
* read the device state by the status register as well.
|
|
*
|
|
* @param[in,out] pIO optional user context pointer which has been passed by the L6474_CreateInstance call
|
|
*/
|
|
int (*getFlag) ( void* pIO );
|
|
#endif
|
|
|
|
} L6474x_Platform_t;
|
|
|
|
/*!
|
|
* The L6474_Property_t enum is a address representation for externally changeable properties by the library via the
|
|
* API commands. In case the torque shall be changed, the user can call L6474_SetProperty with the L6474_PROP_TORQUE
|
|
* entry. Some of the properties can not be changed while the driver outputs are enabled and the library is in stENABLED
|
|
* state
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef enum
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* L6474_PROP_TORQUE is the current setpoint value of each phase of the stepper which follows the torque directly
|
|
*/
|
|
L6474_PROP_TORQUE = 0x09,
|
|
|
|
/*!
|
|
* L6474_PROP_TON is the minimum time for the ON-part of the current control loop
|
|
*/
|
|
L6474_PROP_TON = 0x0F,
|
|
|
|
/*!
|
|
* L6474_PROP_TOFF is the minimum time for the OFF-part of the current control loop
|
|
*/
|
|
L6474_PROP_TOFF = 0x10,
|
|
|
|
/*!
|
|
* L6474_PROP_ADC_OUT controls the ADC output behavior
|
|
*/
|
|
L6474_PROP_ADC_OUT = 0x12,
|
|
|
|
/*!
|
|
* L6474_PROP_OCDTH sets the overcurrent threshold detection value
|
|
*/
|
|
L6474_PROP_OCDTH = 0x13,
|
|
|
|
/*!
|
|
* L6474_PROP_TFAST is used to change switching times
|
|
*/
|
|
L6474_PROP_TFAST = 0x0E,
|
|
} L6474_Property_t;
|
|
|
|
/*!
|
|
* The L6474_BaseParameter_t structure is used to set default initialization values for the library whenever a reset
|
|
* has been called or the library is used the first time. It can be filled with the global defaults by calling
|
|
* L6474_SetBaseParameter and it then can be adapted or directly passed into L6474_Initialize which always needs
|
|
* to be called after resetting the stepper driver or the library
|
|
*/
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
typedef struct
|
|
// --------------------------------------------------------------------------------------------------------------------
|
|
{
|
|
/*!
|
|
* stepMode describes the stepping operation mode, see L6474x_StepMode_t
|
|
*/
|
|
L6474x_StepMode_t stepMode;
|
|
|
|
/*!
|
|
* OcdTh describes the overcurrent detection threshold, see L6474x_OCD_TH_t
|
|
*/
|
|
L6474x_OCD_TH_t OcdTh;
|
|
|
|
/*!
|
|
* TimeOnMin is used to change the minimum time for the ON-part of the current control loop
|
|
*/
|
|
char TimeOnMin;
|
|
|
|
/*!
|
|
* TimeOffMin is used to change the minimum time for the OFF-part of the current control loop
|
|
*/
|
|
char TimeOffMin;
|
|
|
|
/*!
|
|
* TorqueVal is used to change the current setpoint of the controller which follows directly the torque
|
|
*/
|
|
char TorqueVal;
|
|
|
|
/*!
|
|
* L6474_PROP_TFAST is used to change switching times
|
|
*/
|
|
char TFast;
|
|
|
|
} L6474_BaseParameter_t;
|
|
|
|
|
|
/*!
|
|
* L6474_CreateInstance is used once to create a library instance which encapsulates the handling for one stepper driver chip
|
|
* It needs a L6474x_Platform_t abstraction pointer and optionally some context pointers which are platform specific. The
|
|
* context pointers are passed to the abstraction functions which are provided by the platform structure.
|
|
*
|
|
* In case it fails, a null pointer is returned. In case it was successful, a handle pointer is returned which is always
|
|
* required for all other API calls
|
|
*/
|
|
L6474_Handle_t L6474_CreateInstance(L6474x_Platform_t* p, void* pIO, void* pGPO, void* pPWM);
|
|
|
|
/*!
|
|
* L6474_DestroyInstance is used to destroy a library instance which has been previously created by a call to L6474_CreateInstance
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error
|
|
*/
|
|
int L6474_DestroyInstance(L6474_Handle_t h);
|
|
|
|
|
|
/*!
|
|
* Calling L6474_ResetStandBy sets the driver in deep power down or reset state and the library will be set to default
|
|
* startup state again. All initialization steps must be done again by at least calling L6474_Initialize. The library
|
|
* is set to stRESET from any other state before.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error
|
|
*
|
|
* note that in case the stepper is enabled an moving, the operation will be safely disabled but depending on the
|
|
* speed, the position can not be tracked properly anymore. So a new reference run after re-initialization is required!
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*/
|
|
int L6474_ResetStandBy(L6474_Handle_t h);
|
|
|
|
/*!
|
|
* Calling L6474_SetBaseParameter sets the basic global default parameters for all properties in the L6474_BaseParameter_t
|
|
* structure. These parameters are required when calling L6474_Initialize
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error
|
|
*/
|
|
int L6474_SetBaseParameter(L6474_BaseParameter_t* p);
|
|
|
|
/*!
|
|
* Calling L6474_EncodePhaseCurrent converts the requested phase current into the register value which is
|
|
* required in the base parameter structure. The member for this value is named TorqueVal
|
|
*
|
|
* The function returns a register value which represents the given current value
|
|
*/
|
|
char L6474_EncodePhaseCurrent(float mA);
|
|
|
|
/*!
|
|
* Calling L6474_EncodePhaseCurrentParameter converts the requested phase current into the register value which is
|
|
* required in the base parameter structure. The member for this value is named TorqueVal. This function directly inserts
|
|
* the converted value into the given base parameter structure.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error
|
|
*/
|
|
int L6474_EncodePhaseCurrentParameter(L6474_BaseParameter_t* p, float mA);
|
|
|
|
/*!
|
|
* func L6474_Initialize is used to set all basic parameters and take the required steps to bring up the driver into an
|
|
* idle state. It sets the library to stDISABLED in case no error happens.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param p is required and can not be null. the struct can be filled by calling L6474_SetBaseParameter before.
|
|
*/
|
|
int L6474_Initialize(L6474_Handle_t h, L6474_BaseParameter_t* p);
|
|
|
|
/*!
|
|
* func L6474_SetStepMode is used to change the step mode and therefore the resolution. It is required to execute
|
|
* a new reference run because the position value of the lib does not match the stepping mode anymore. The library must not be
|
|
* in stRESET to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param mode is required and is one out of L6474x_StepMode_t
|
|
*/
|
|
int L6474_SetStepMode(L6474_Handle_t h, L6474x_StepMode_t mode);
|
|
|
|
/*!
|
|
* func L6474_SetStepMode is used to read back the step mode and therefore the resolution. The library must not be
|
|
* in stRESET to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param mode is required and is one out of L6474x_StepMode_t
|
|
*/
|
|
int L6474_GetStepMode(L6474_Handle_t h, L6474x_StepMode_t* mode);
|
|
|
|
/*!
|
|
* func L6474_SetPowerOutputs is used to enable or disable the driver output stages. The library must not be
|
|
* in stRESET to perform this operation. The libraries state will be changed to stENABLED or stDISABLED depending
|
|
* on the ena parameter.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param ena is required and is either 0 when disabling or 1 when enabling is requested
|
|
*/
|
|
int L6474_SetPowerOutputs(L6474_Handle_t h, int ena);
|
|
|
|
/*!
|
|
* func L6474_GetStatus is used to read back the current libraries and devices status. The library must not be
|
|
* in stRESET to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param status is required. And must not be null
|
|
*/
|
|
int L6474_GetStatus(L6474_Handle_t h, L6474_Status_t* status);
|
|
|
|
|
|
/*!
|
|
* func L6474_GetState is used to read back the current libraries state. The library can be
|
|
* in state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param state is required. And must not be null
|
|
*/
|
|
int L6474_GetState(L6474_Handle_t h, L6474x_State_t* state);
|
|
|
|
/*!
|
|
* func L6474_StepIncremental is used to issue a movement with the given amount of steps. The library has to be
|
|
* in stENABLED state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param steps is required. negative values lead to a counter clock wise movement, 0 does not lead to any movement
|
|
* but returns errcNONE in case no other issue is present.
|
|
*/
|
|
int L6474_StepIncremental(L6474_Handle_t h, int steps );
|
|
|
|
/*!
|
|
* func L6474_StopMovement is used to stop a pending movement in case it has been configured as async. If not,
|
|
* it always return errcNONE in case no other issue is present. The library has to be in stENABLED state
|
|
* to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*/
|
|
int L6474_StopMovement(L6474_Handle_t h);
|
|
|
|
/*!
|
|
* func L6474_IsMoving is used to read the state of movement. In case the stepper moves, it returns true. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param moving is required. It returns 0 when no movement is pending or 1 when there is a movement.
|
|
*/
|
|
int L6474_IsMoving(L6474_Handle_t h, int* moving);
|
|
|
|
/*!
|
|
* func L6474_SetProperty is used to write a property of the type of L6474_Property_t. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param prop is required.
|
|
*
|
|
* param value is required. The value formats can be found in the datasheet
|
|
*/
|
|
int L6474_SetProperty(L6474_Handle_t h, L6474_Property_t prop, int value);
|
|
|
|
/*!
|
|
* func L6474_SetProperty is used to read a property of the type of L6474_Property_t. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param prop is required.
|
|
*
|
|
* param value is required. The value formats can be found in the datasheet
|
|
*/
|
|
int L6474_GetProperty(L6474_Handle_t h, L6474_Property_t prop, int* value);
|
|
|
|
/*!
|
|
* func L6474_GetAbsolutePosition is used to read the current stepper position. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param position is required. It returns the position
|
|
*/
|
|
int L6474_GetAbsolutePosition(L6474_Handle_t h, int* position);
|
|
|
|
/*!
|
|
* func L6474_SetAbsolutePosition is used to write the current stepper position. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param position is required. It sets the position
|
|
*/
|
|
int L6474_SetAbsolutePosition(L6474_Handle_t h, int position);
|
|
|
|
/*!
|
|
* func L6474_GetElectricalPosition is used to read the current stepper electrical position. The library
|
|
* must not be in stRESET state to perform this operation. The electrical Position returns
|
|
* the step state and micro step component of the driver.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param position is required.
|
|
*/
|
|
int L6474_GetElectricalPosition(L6474_Handle_t h, int* position);
|
|
|
|
/*!
|
|
* func L6474_SetElectricalPosition is used to write the current stepper electrical position. The library
|
|
* must not be in stRESET state to perform this operation. The electrical Position consists of
|
|
* the step state and micro step component of the driver.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param position is required.
|
|
*/
|
|
int L6474_SetElectricalPosition(L6474_Handle_t h, int position);
|
|
|
|
/*!
|
|
* func L6474_GetPositionMark is used to read the current stepper position mark. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param position is required.
|
|
*/
|
|
int L6474_GetPositionMark(L6474_Handle_t h, int* position);
|
|
|
|
/*!
|
|
* func L6474_SetPositionMark is used to write the current stepper position mark. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param position is required.
|
|
*/
|
|
int L6474_SetPositionMark(L6474_Handle_t h, int position);
|
|
|
|
/*!
|
|
* func L6474_GetAlarmEnables is used to read the current enable bits for the ERROR ALARM and FLAG Pin. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param bits is required. The bitmask can be found in the datasheet
|
|
*/
|
|
int L6474_GetAlarmEnables(L6474_Handle_t h, int* bits);
|
|
|
|
/*!
|
|
* func L6474_SetAlarmEnables is used to write the current enable bits for the ERROR ALARM and FLAG Pin. The library
|
|
* must not be in stRESET state to perform this operation.
|
|
*
|
|
* The function returns errcNONE in case no error happens or any other error code from L6474x_ErrorCode_t enum
|
|
* in case of an error.
|
|
*
|
|
* param h is required and can not be null. the handle can be created by calling L6474_CreateInstance before.
|
|
*
|
|
* param bits is required. The bitmask can be found in the datasheet
|
|
*/
|
|
int L6474_SetAlarmEnables(L6474_Handle_t h, int bits);
|
|
|
|
|
|
/*!
|
|
* \mainpage Stepper Library Lib6474
|
|
* \section intro_sec Introduction
|
|
*
|
|
* The following code documentation is a set of tips and diagrams as well as function and structure descriptions
|
|
* which help when using the library. It is used to increase the implementation speed. Some examples are attached
|
|
* in this documentation as well
|
|
*
|
|
* \section install_sec Static compile flags
|
|
*
|
|
* LIBL6474_STEP_ASYNC:
|
|
* This DEFINE is used to switch from blocking synchronous mode to asynchronous non-blocking step mode.
|
|
* This changes the API behavior
|
|
*
|
|
* LIBL6474_HAS_LOCKING:
|
|
* This DEFINE is used to enable the lock guard and thread synchronization guard abstraction,
|
|
* which requires additional abstraction functions
|
|
*
|
|
* LIBL6474_DISABLE_OCD:
|
|
* Should only be used for debugging purposes and not for productive code!
|
|
* This DEFINE is used to disable the overcurrent detection feature in the library and the stepper driver
|
|
*
|
|
* LIBL6474_HAS_FLAG:
|
|
* enables the support of the flag pin
|
|
* This DEFINE is used to enable the FLAG pin support, which requires additional abstraction functions
|
|
*
|
|
* \section state_sec State diagram
|
|
* The following state diagram shows the internal state machine handling which follows or represents the
|
|
* state of the stepper driver chip. The fault conditions are not depicted in the diagram but in all regular
|
|
* cases the error handling is done by resetting and reinitialization of the stepper driver by the library.
|
|
*
|
|
* \dot
|
|
* digraph G {
|
|
*
|
|
* subgraph cluster_0 {
|
|
* node [style=filled];
|
|
* stRESET;
|
|
* stDISABLED;
|
|
* stENABLED;
|
|
* label = "State machine";
|
|
* color=blue
|
|
* }
|
|
*
|
|
* POR -> stRESET [label="L6474_CreateInstance"];
|
|
* stRESET -> stDISABLED [label="L6474_Initialize"];
|
|
*
|
|
* stDISABLED -> stENABLED [label="L6474_SetPowerOutputs"];
|
|
* stDISABLED -> stRESET [label="L6474_ResetStandBy"];
|
|
*
|
|
* stENABLED -> stDISABLED [label="L6474_SetPowerOutputs"];
|
|
* stENABLED -> stRESET [label="L6474_ResetStandBy"];
|
|
*
|
|
* POR [shape=Mdiamond];
|
|
* }
|
|
* \enddot
|
|
*
|
|
* \section state_example Examples
|
|
* The following example shows a part of the abstraction functions which are required
|
|
* for the usage of the Stepper library. It also shows how to create a instance of
|
|
* the stepper library.
|
|
* \code
|
|
* static void* StepLibraryMalloc( unsigned int size )
|
|
* {
|
|
* return malloc(size);
|
|
* }
|
|
*
|
|
* static void StepLibraryFree( const void* const ptr )
|
|
* {
|
|
* free((void*)ptr);
|
|
* }
|
|
*
|
|
* static int StepDriverSpiTransfer( void* pIO, char* pRX, const char* pTX, unsigned int length )
|
|
* {
|
|
* // byte based access, so keep in mind that only single byte transfers are performed!
|
|
* for ( unsigned int i = 0; i < length; i++ )
|
|
* {
|
|
* ...
|
|
* }
|
|
* return 0;
|
|
* }
|
|
*
|
|
* ...
|
|
*
|
|
* // pass all function pointers required by the stepper library
|
|
* // to a separate platform abstraction structure
|
|
* L6474x_Platform_t p;
|
|
* p.malloc = StepLibraryMalloc;
|
|
* p.free = StepLibraryFree;
|
|
* p.transfer = StepDriverSpiTransfer;
|
|
* p.reset = StepDriverReset;
|
|
* p.sleep = StepLibraryDelay;
|
|
* p.stepAsync = StepTimerAsync;
|
|
* p.cancelStep = StepTimerCancelAsync;
|
|
*
|
|
* // now create the handle
|
|
* L6474_Handle_t h = L6474_CreateInstance(&p, null, null, null);
|
|
*
|
|
* \endcode
|
|
*
|
|
* The following example shows a really simple instantiation and usage
|
|
* of the library with a simple default and straight forward configuration
|
|
* and no calculation of any step widths or resolutions
|
|
*
|
|
* \code
|
|
*
|
|
* ...
|
|
*
|
|
* int result = 0;
|
|
* ...
|
|
*
|
|
* // reset all and take all initialization steps
|
|
* result |= L6474_ResetStandBy(h);
|
|
* result |= L6474_Initialize(h, ¶m);
|
|
* result |= L6474_SetPowerOutputs(h, 1);
|
|
*
|
|
* ...
|
|
*
|
|
* // in case we have no error, we can enable the drivers
|
|
* // and then we step a bit
|
|
* if ( result == 0 )
|
|
* {
|
|
* result |= L6474_StepIncremental(h, 1000 );
|
|
* }
|
|
* else
|
|
* {
|
|
* // error handling
|
|
* ...
|
|
* }
|
|
*
|
|
* ...
|
|
*
|
|
* \endcode
|
|
*
|
|
* The following example shows how to change the phase current (max torque) of the stepper.
|
|
* This can be achieved by reinitializing the library or by changing the parameter by calling
|
|
* L6474_SetProperty;
|
|
*
|
|
* \code
|
|
*
|
|
* ...
|
|
*
|
|
* int result = 0;
|
|
* ...
|
|
*
|
|
* // first way: set the torque on initialization
|
|
* result |= L6474_ResetStandBy(h);
|
|
* result |= L6474_EncodePhaseCurrentParameter(¶m, 1200.0f);
|
|
* result |= L6474_Initialize(h, ¶m);
|
|
*
|
|
* ...
|
|
*
|
|
* // second way: set the torque after initialization
|
|
* char torqueval = L6474_EncodePhaseCurrent(1500.0f);
|
|
* result |= L6474_SetProperty(h, L6474_PROP_TORQUE, torqueval);
|
|
*
|
|
* ...
|
|
*
|
|
* \endcode
|
|
*/
|
|
|
|
/*!
|
|
* \page lib_port_page Library porting
|
|
* \section intro_sec Introduction
|
|
*
|
|
* The library is written with a minimum set of compiler dependencies to make it portable on most toolchains
|
|
* and most compilers which are able to compile C. There are no GCC attributes or MSVC pragmas included in the code
|
|
* furthermore there are no weak functions or other non ISO-C language keywords which are not parsable from
|
|
* all compilers. To include the library in a project, the following page helps to do the job and can be used as
|
|
* a step by step quick porting guide.
|
|
*
|
|
* \section step_by_step_sec required steps to include the library
|
|
* -# include all include paths of the library folder (inc-folder) to your project or copy them into your project as needed
|
|
* -# link all C files (src-folder) to your project or copy them to your project as needed
|
|
* -# adapt your makefile in case you have one. When using eclipse project this is not required
|
|
* -# copy the template header LibL6474Config.h file to your project or create your own and adapt the compile time parameters as needed.
|
|
* -# compile the source code once to make sure everything builds without issues and your include paths are correct.
|
|
* -# now implement the platform functions which are required be the L6474x_Platform_t structure when calling L6474_CreateInstance.
|
|
* -# when all functions are defined, no error should be returned after the call of L6474_CreateInstance. Porting is done.
|
|
*/
|
|
|
|
#endif /* INC_LIBL6474_H_ */
|