Files
2026-10-16 18:25:42 +02:00

222 lines
9.5 KiB
C

/*
* Controller.h
*
* Created on: Dec 9, 2024
* Author: Thorsten
*/
/*! \file */
#ifndef INC_SPINDLE_CONTROLLER_H_
#define INC_SPINDLE_CONTROLLER_H_
#include "Console.h"
/*!
* The SpindleHandle_t handle is an instance pointer of the spindle library which is generated whenever
* the SPINDLE_CreateInstance function returns with success.
*/
typedef struct SpindleHandle* SpindleHandle_t;
/*!
* The SpindlePhysicalParams_t structure is represents the abstraction functions and members as a container.
* The objetcs are passed as structure pointer when calling SPINDLE_CreateInstance. It contains function pointers
* to platform specific functions which enable the spindle or regulate the speed and direction of it.
* There are also limit values for the maximum, minimum and absolute minimum RPM and an additional
* context pointer which is passed the the abstraction functions. The user must provide a configured
* structure in its design when calling SPINDLE_CreateInstance.
*/
typedef struct SpindlePhysicalParams
{
/*!
* This function pointer is used to change the duty cycle of the spindle. This function is
* necessary for changing the PWM generation itself. It also sets the direction of the spindle
* which means turning clock wise or counter clock wise
*
* The pointer must not be null
*
* @param[in,out] h optional handle of the spindle library.
* @param[in,out] context optional context pointer the user has passed by the SPINDLE_CreateInstance call.
* @param[in] dutyCycle value between 0 = 0% and 1 = 100%
* @param[in] backwards sets the direction of the spindle (clockwise or counter clockwise = backward).
*
* The behavior is schematically as follows:
* @startuml
* Library -> platform_set_duty_cycle_function : Requests a duty cycle change
* platform_set_duty_cycle_function -> timer_driver : change duty cycle
* platform_set_duty_cycle_function <- timer_driver
* Library <- platform_set_duty_cycle_function
* @enduml
*/
void (*setDutyCycle)(SpindleHandle_t h, void* context, int backwards, float dutyCycle);
/*!
* This function pointer is used to enable or disable the PWM output and to set
* the enable outputs od the half bridges of the spindle
*
* The pointer must not be null
*
* @param[in,out] h optional handle of the spindle library.
* @param[in,out] context optional context pointer the user has passed by the SPINDLE_CreateInstance call.
* @param[in] ena value that sets enable or disable state (1 = enabled, 0 = disabled)
*
* The behavior is schematically as follows:
* @startuml
* alt ena = 1
* Library -> platform_enable_function : Requests a duty cycle change
* platform_enable_function -> timer_driver : enable PWM
* platform_enable_function <- timer_driver
* platform_enable_function -> gpio_driver : enable H-bridge
* platform_enable_function <- gpio_driver
* Library <- platform_enable_function
* else ena = 0
* Library -> platform_enable_function : Requests a duty cycle change
* platform_enable_function -> timer_driver : disable PWM or set duty cycle to 0
* platform_enable_function <- timer_driver
* platform_enable_function -> gpio_driver : disable H-bridge
* platform_enable_function <- gpio_driver
* Library <- platform_enable_function
* end
* @enduml
*/
void (*enaPWM) (SpindleHandle_t h, void* context, int ena);
/*!
* specifies the maximum positive RPM value which represents a duty cycle of 1.0
*/
float maxRPM;
/*!
* specifies the minimum possible absolute RPM value which is usable with the spindle
* a requested RPM value lower than this value is limited and therefore its not possible
* to let the spindle run slower. This value is used for clock wise and counter clock wise
* spindle rotation in the same way.
*/
float absMinRPM;
/*!
* specifies the minimum negative RPM value. Mostly this value is symmetrical to the max value
* which means it can be the same value
*/
float minRPM;
/*!
* optional context pointer for platform abstraction. can be null.
*/
void* context;
} SpindlePhysicalParams_t;
/*!
* The SPINDLE_CreateInstance function is used to create the spindle controller. There is a singleton pattern implemented
* for the controller so there is only one instance possible for the design. In case it is called multiple times, it returns
* the instance pointer of the first created spindle controller
*
* The return value of SPINDLE_CreateInstance is a null pointer in case an error occured or a pointer of type SpindleHandle_t.
*
* param uxStackDepth is the stack depth of the console processor thread in words
* param xPrio is the spindle controller priority.
* param cH of type ConsoleHandle_t is the handle pointer of a console processor instance which is required to register the
* console command for the spindle controller
* param p of type SpindlePhysicalParams_t* is a pointer to the platform abstraction functions
*
* ATTENTION: This function is not locked or guarded and therefore its never thread safe when calling from two different threads
* at the same or nearly the same time while no instance has been created before! One pointer and its ressources could be lost
* which leads to a memory leak and/or to console command registration issues at runtime when using the spindle command!
*/
SpindleHandle_t SPINDLE_CreateInstance( unsigned int uxStackDepth, int xPrio, ConsoleHandle_t cH, SpindlePhysicalParams_t* p );
/*!
* The SPINDLE_GetStatus function is used to return the current state of the spindel controller.
*/
void SPINDLE_GetStatus(SpindleHandle_t h, int *enabled, int *rpm);
/*!
* \mainpage FreeRTOS Spindle Library
* \section intro_sec Introduction
*
* The following code documentation is a set of tipps and diagramms 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 static_sec static compile flags of the library
* There are no additional static compile flags or DEFINES which the user can configure
*
* \section instantiation library instantiation
* The library is implemented as a singleton pattern. This means that only one instance
* can be created at runtime. Calling the SPINDLE_CreateInstance multiple times will
* succeed but always the pointer of the first instance will be returned.
*
* \section state_example Examples
* The following example shows how to create a instance of the spindle controller library.
*
* \code
*
* // set parameters for the physical system
* SpindlePhysicalParams_t s;
* s.maxRPM = 9000.0f;
* s.minRPM = -9000.0f;
* s.absMinRPM = 1600.0f;
* s.setDirection = SPINDLE_SetDirection;
* s.setDutyCycle = SPINDLE_SetDutyCycle;
* s.enaPWM = SPINDLE_EnaPWM;
* s.context = NULL;
* SPINDLE_CreateInstance( 4*configMINIMAL_STACK_SIZE, configMAX_PRIORITIES - 3, c, &s);
*
* ...
*
* \endcode
*
* The following example shows the usage of the spindle library via console. With the spindle command
* the user can start or stop the spindle and it can also change the spindle speed with the start command
* The command returns OK or FAIL in the given cases of failure or success. There is also a status command.
* It returns the state of the spindle (turning) and the RPM which has been set. It also terminates with "OK"
* or "FAIL"
*
* \code
* // starts the spindle
* $> spindle start <RPM>
*
* // sets another spped of the spindle
* $> spindle start <RPM>
*
* // stops the spindle
* $> spindle stop
* \endcode
*
* \code
* // get the status the spindle
* $> spindle status
* \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
* -# 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 SpindlePhysicalParams_t structure when calling SPINDLE_CreateInstance.
* -# when all functions are defined, no error should be returned after the call of SPINDLE_CreateInstance. Porting is done.
*
* \section additional note
* when porting the platform functions, it is not required to execute anything in the SpindlePhysicalParams_t[setDirection] function, because
* the setDutyCycle function and the enaPWM function is called directly after the setDirection function. So it is sufficient to only store a
* variable value anywhere and interpret it later in the setDutyCyle function!
*/
#endif /* INC_SPINDLE_CONTROLLER_H_ */