grblHAL core  20241107
spindle_control.h File Reference
#include "pid.h"

Go to the source code of this file.

Data Structures

union  spindle_state_t
 
union  spindle_cap_t
 Bitmap flags for spindle capabilities. More...
 
struct  spindle_data_t
 Used when HAL driver supports spindle synchronization. More...
 
struct  pwm_piece_t
 
union  spindle_settings_flags_t
 
struct  spindle_settings_t
 
struct  spindle1_settings_t
 
union  spindle_pwm_flags_t
 
struct  spindle_pwm
 Precalculated values that may be set/used by HAL driver to speed up RPM to PWM conversions if variable spindle is supported. *‍/. More...
 
union  spindle_context_ptr_t
 
struct  spindle_ptrs
 Handlers and data for spindle support. More...
 
struct  spindle_css_data_t
 Data used for Constant Surface Speed (CSS) mode calculations. More...
 
struct  spindle_param
 Structure used for holding the current state of an enabled spindle. More...
 
struct  spindle_data_ptrs_t
 
struct  spindle_info_t
 Structure holding data passed to the callback function called by spindle_enumerate_spindles(). More...
 

Macros

#define SPINDLE_NONE   0
 
#define SPINDLE_HUANYANG1   1
 
#define SPINDLE_HUANYANG2   2
 
#define SPINDLE_GS20   3
 
#define SPINDLE_YL620A   4
 
#define SPINDLE_MODVFD   5
 
#define SPINDLE_H100   6
 
#define SPINDLE_ONOFF0   7
 
#define SPINDLE_ONOFF0_DIR   8
 
#define SPINDLE_ONOFF1   9
 
#define SPINDLE_ONOFF1_DIR   10
 
#define SPINDLE_PWM0   11
 
#define SPINDLE_PWM0_NODIR   12
 
#define SPINDLE_PWM1   13
 
#define SPINDLE_PWM1_NODIR   14
 
#define SPINDLE_PWM2   15
 
#define SPINDLE_PWM2_NODIR   16
 
#define SPINDLE_PWM0_CLONE   17
 
#define SPINDLE_SOLENOID   18
 
#define SPINDLE_STEPPER   19
 
#define SPINDLE_NOWFOREVER   20
 
#define SPINDLE_MY_SPINDLE   30
 
#define SPINDLE_ALL_VFD   ((1<<SPINDLE_HUANYANG1)|(1<<SPINDLE_HUANYANG2)|(1<<SPINDLE_GS20)|(1<<SPINDLE_YL620A)|(1<<SPINDLE_MODVFD)|(1<<SPINDLE_H100)|(1<<SPINDLE_NOWFOREVER))
 
#define SPINDLE_ALL   (SPINDLE_ALL_VFD|(1<<SPINDLE_PWM0))
 
#define spindle_validate_at_speed(d, r)   { d.rpm = r; d.state_programmed.at_speed = !d.at_speed_enabled || (d.rpm >= d.rpm_low_limit && d.rpm <= d.rpm_high_limit); }
 

Typedefs

typedef int8_t spindle_id_t
 
typedef int8_t spindle_num_t
 
typedef bool(* spindle_config_ptr) (struct spindle_ptrs *spindle)
 Pointer to function for configuring a spindle. More...
 
typedef void(* spindle_set_state_ptr) (struct spindle_ptrs *spindle, spindle_state_t state, float rpm)
 Pointer to function for setting the spindle state. More...
 
typedef spindle_state_t(* spindle_get_state_ptr) (struct spindle_ptrs *spindle)
 Pointer to function for getting the spindle state. More...
 
typedef uint_fast16_t(* spindle_get_pwm_ptr) (struct spindle_ptrs *spindle, float rpm)
 Pointer to function for converting a RPM value to a PWM value. More...
 
typedef void(* spindle_update_pwm_ptr) (struct spindle_ptrs *spindle, uint_fast16_t pwm)
 Pointer to function for updating spindle speed on the fly. More...
 
typedef void(* spindle_update_rpm_ptr) (struct spindle_ptrs *spindle, float rpm)
 Pointer to function for updating spindle RPM. More...
 
typedef spindle_data_t *(* spindle_get_data_ptr) (spindle_data_request_t request)
 Pointer to function for getting spindle data. More...
 
typedef void(* spindle_reset_data_ptr) (void)
 Pointer to function for resetting spindle data. More...
 
typedef void(* spindle_pulse_on_ptr) (uint_fast16_t pulse_length)
 Pointer to function for outputting a spindle on pulse. Used for Pulses Per Inch (PPI) laser mode. More...
 
typedef struct spindle_pwm spindle_pwm_t
 Precalculated values that may be set/used by HAL driver to speed up RPM to PWM conversions if variable spindle is supported. *‍/. More...
 
typedef struct spindle_ptrs spindle_ptrs_t
 
typedef struct spindle_param spindle_param_t
 Structure used for holding the current state of an enabled spindle. More...
 
typedef void(* spindle_enumerate_callback_ptr) (spindle_info_t *spindle, void *data)
 Pointer to callback function called by spindle_enumerate_spindles(). More...
 

Enumerations

enum  spindle_data_request_t { SpindleData_Counters , SpindleData_RPM , SpindleData_AngularPosition , SpindleData_AtSpeed }
 
enum  spindle_type_t {
  SpindleType_PWM , SpindleType_Basic , SpindleType_VFD , SpindleType_Solenoid ,
  SpindleType_Stepper , SpindleType_Null
}
 
enum  spindle_hal_t { SpindleHAL_Raw , SpindleHAL_Configured , SpindleHAL_Active }
 

Functions

void spindle_set_override (spindle_ptrs_t *spindle, override_t speed_override)
 Set spindle speed override. More...
 
bool spindle_sync (spindle_ptrs_t *spindle, spindle_state_t state, float rpm)
 G-code parser entry-point for setting spindle state. Forces a planner buffer sync and bails if an abort or check-mode is active. If the spindle supports at speed functionality it will wait for it to reach the speed and raise an alarm if the speed is not reached within the timeout period. More...
 
bool spindle_set_state (spindle_ptrs_t *spindle, spindle_state_t state, float rpm)
 Immediately sets spindle running state with direction and spindle rpm, if enabled. Called by g-code parser spindle_sync(), parking retract and restore, g-code program end, sleep, and spindle stop override. More...
 
float spindle_set_rpm (spindle_ptrs_t *spindle, float rpm, override_t speed_override)
 Calculate and set programmed RPM according to override and max/min limits. More...
 
bool spindle_restore (spindle_ptrs_t *spindle, spindle_state_t state, float rpm)
 Restore spindle running state with direction, enable, spindle RPM and appropriate delay. More...
 
void spindle_all_off (void)
 Turn off all enabled spindles. More...
 
bool spindle_precompute_pwm_values (spindle_ptrs_t *spindle, spindle_pwm_t *pwm_data, spindle_settings_t *settings, uint32_t clock_hz)
 Precompute PWM values for faster conversion. More...
 
spindle_id_t spindle_register (const spindle_ptrs_t *spindle, const char *name)
 Register a spindle with the core. More...
 
spindle_id_t spindle_add_null (void)
 Register a null spindle that has no connection to the outside world. This is done automatically on startup if no spindle can be succesfully enabled. More...
 
uint8_t spindle_get_count (void)
 Get number of registered spindles. More...
 
bool spindle_select (spindle_id_t spindle_id)
 Enables a spindle and sets it as default spindle (spindle number 0). More...
 
spindle_cap_t spindle_get_caps (bool active)
 Get the merged spindle capabilities of all registered spindles. More...
 
void spindle_update_caps (spindle_ptrs_t *spindle, spindle_pwm_t *pwm_caps)
 Update the capabilities of a registered PWM spindle. May be used by the driver on spindle initialization or when spindle settings has been changed. More...
 
void spindle_bind_encoder (const spindle_data_ptrs_t *encoder_data)
 
bool spindle_set_at_speed_range (spindle_ptrs_t *spindle, spindle_data_t *spindle_data, float rpm)
 
spindle_ptrs_tspindle_get_hal (spindle_id_t spindle_id, spindle_hal_t hal)
 Get the handlers (function pointers) etc. associated with the spindle. More...
 
const char * spindle_get_name (spindle_id_t spindle_id)
 Get the registered name of a spindle. More...
 
spindle_id_t spindle_get_default (void)
 Get the spindle id of the default spindle (spindle number 0). More...
 
spindle_num_t spindle_enable (spindle_id_t spindle_id)
 Enable a spindle and make it available for use by gcode. More...
 
bool spindle_enumerate_spindles (spindle_enumerate_callback_ptr callback, void *data)
 Enumerate registered spindles by calling a callback function for each of them. More...
 
bool spindle_is_enabled (spindle_num_t spindle_num)
 Check if a spindle is enabled and available or not. More...
 
bool spindle_is_on (void)
 Check if any of the enabled spindles is running. More...
 
spindle_ptrs_tspindle_get (spindle_num_t spindle_num)
 Get the handlers (function pointers) etc. associated with an enabled spindle. More...
 

Macro Definition Documentation

◆ SPINDLE_ALL

#define SPINDLE_ALL   (SPINDLE_ALL_VFD|(1<<SPINDLE_PWM0))

◆ SPINDLE_ALL_VFD

#define SPINDLE_ALL_VFD   ((1<<SPINDLE_HUANYANG1)|(1<<SPINDLE_HUANYANG2)|(1<<SPINDLE_GS20)|(1<<SPINDLE_YL620A)|(1<<SPINDLE_MODVFD)|(1<<SPINDLE_H100)|(1<<SPINDLE_NOWFOREVER))

◆ SPINDLE_GS20

#define SPINDLE_GS20   3

◆ SPINDLE_H100

#define SPINDLE_H100   6

◆ SPINDLE_HUANYANG1

#define SPINDLE_HUANYANG1   1

◆ SPINDLE_HUANYANG2

#define SPINDLE_HUANYANG2   2

◆ SPINDLE_MODVFD

#define SPINDLE_MODVFD   5

◆ SPINDLE_MY_SPINDLE

#define SPINDLE_MY_SPINDLE   30

◆ SPINDLE_NONE

#define SPINDLE_NONE   0

◆ SPINDLE_NOWFOREVER

#define SPINDLE_NOWFOREVER   20

◆ SPINDLE_ONOFF0

#define SPINDLE_ONOFF0   7

◆ SPINDLE_ONOFF0_DIR

#define SPINDLE_ONOFF0_DIR   8

◆ SPINDLE_ONOFF1

#define SPINDLE_ONOFF1   9

◆ SPINDLE_ONOFF1_DIR

#define SPINDLE_ONOFF1_DIR   10

◆ SPINDLE_PWM0

#define SPINDLE_PWM0   11

◆ SPINDLE_PWM0_CLONE

#define SPINDLE_PWM0_CLONE   17

◆ SPINDLE_PWM0_NODIR

#define SPINDLE_PWM0_NODIR   12

◆ SPINDLE_PWM1

#define SPINDLE_PWM1   13

◆ SPINDLE_PWM1_NODIR

#define SPINDLE_PWM1_NODIR   14

◆ SPINDLE_PWM2

#define SPINDLE_PWM2   15

◆ SPINDLE_PWM2_NODIR

#define SPINDLE_PWM2_NODIR   16

◆ SPINDLE_SOLENOID

#define SPINDLE_SOLENOID   18

◆ SPINDLE_STEPPER

#define SPINDLE_STEPPER   19

◆ spindle_validate_at_speed

#define spindle_validate_at_speed (   d,
 
)    { d.rpm = r; d.state_programmed.at_speed = !d.at_speed_enabled || (d.rpm >= d.rpm_low_limit && d.rpm <= d.rpm_high_limit); }

◆ SPINDLE_YL620A

#define SPINDLE_YL620A   4

Typedef Documentation

◆ spindle_config_ptr

typedef bool(* spindle_config_ptr) (struct spindle_ptrs *spindle)

Pointer to function for configuring a spindle.

Parameters
spindlea pointer to a spindle_struct.
Returns
true if successful, \false if not.

◆ spindle_enumerate_callback_ptr

typedef void(* spindle_enumerate_callback_ptr) (spindle_info_t *spindle, void *data)

Pointer to callback function called by spindle_enumerate_spindles().

Parameters
spindleprointer to a spindle_info_t struct.

◆ spindle_get_data_ptr

typedef spindle_data_t*(* spindle_get_data_ptr) (spindle_data_request_t request)

Pointer to function for getting spindle data.

Parameters
requestrequest type as a spindle_data_request_t enum.
Returns
pointer to the requested information in a spindle_data_t structure.

NOTE: this function requires input from a spindle encoder.

◆ spindle_get_pwm_ptr

typedef uint_fast16_t(* spindle_get_pwm_ptr) (struct spindle_ptrs *spindle, float rpm)

Pointer to function for converting a RPM value to a PWM value.

Typically this is a wrapper for the spindle_compute_pwm_value() function provided by the core.

Parameters
rpmspindle RPM.
Returns
the corresponding PWM value.

◆ spindle_get_state_ptr

typedef spindle_state_t(* spindle_get_state_ptr) (struct spindle_ptrs *spindle)

Pointer to function for getting the spindle state.

Returns
state in a spindle_state_t union variable.

◆ spindle_id_t

typedef int8_t spindle_id_t

◆ spindle_num_t

typedef int8_t spindle_num_t

◆ spindle_param_t

Structure used for holding the current state of an enabled spindle.

◆ spindle_ptrs_t

typedef struct spindle_ptrs spindle_ptrs_t

◆ spindle_pulse_on_ptr

typedef void(* spindle_pulse_on_ptr) (uint_fast16_t pulse_length)

Pointer to function for outputting a spindle on pulse. Used for Pulses Per Inch (PPI) laser mode.

Parameters
pulse_lengthspindle on length in microseconds.

◆ spindle_pwm_t

typedef struct spindle_pwm spindle_pwm_t

Precalculated values that may be set/used by HAL driver to speed up RPM to PWM conversions if variable spindle is supported. *‍/.

◆ spindle_reset_data_ptr

typedef void(* spindle_reset_data_ptr) (void)

Pointer to function for resetting spindle data.

◆ spindle_set_state_ptr

typedef void(* spindle_set_state_ptr) (struct spindle_ptrs *spindle, spindle_state_t state, float rpm)

Pointer to function for setting the spindle state.

Parameters
statea spindle_state_t union variable.
rpmspindle RPM.

◆ spindle_update_pwm_ptr

typedef void(* spindle_update_pwm_ptr) (struct spindle_ptrs *spindle, uint_fast16_t pwm)

Pointer to function for updating spindle speed on the fly.

Parameters
pwmnew spindle PWM value.
Returns
the actual PWM value used.

NOTE: this function will be called from an interrupt context.

◆ spindle_update_rpm_ptr

typedef void(* spindle_update_rpm_ptr) (struct spindle_ptrs *spindle, float rpm)

Pointer to function for updating spindle RPM.

Parameters
rpmspindle RPM.

Enumeration Type Documentation

◆ spindle_data_request_t

Enumerator
SpindleData_Counters 

0

SpindleData_RPM 

1

SpindleData_AngularPosition 

2

SpindleData_AtSpeed 

3

◆ spindle_hal_t

Enumerator
SpindleHAL_Raw 

0 - NOTE: read-only

SpindleHAL_Configured 

1

SpindleHAL_Active 

2

◆ spindle_type_t

Enumerator
SpindleType_PWM 

0

SpindleType_Basic 

1 - on/off + optional direction

SpindleType_VFD 

2

SpindleType_Solenoid 

3

SpindleType_Stepper 

4

SpindleType_Null 

5

Function Documentation

◆ spindle_add_null()

spindle_id_t spindle_add_null ( void  )

Register a null spindle that has no connection to the outside world. This is done automatically on startup if no spindle can be succesfully enabled.

Returns
assigned spindle id as a spindle_id_t if successful, -1 if not.

◆ spindle_all_off()

void spindle_all_off ( void  )

Turn off all enabled spindles.

◆ spindle_bind_encoder()

void spindle_bind_encoder ( const spindle_data_ptrs_t encoder_data)

◆ spindle_enable()

spindle_num_t spindle_enable ( spindle_id_t  spindle_id)

Enable a spindle and make it available for use by gcode.

Parameters
spindle_idspindle id as a spindle_id_t.
Returns
assigned spindle number as a spindle_num_t if successful -1 if not.

NOTE: up to N_SYS_SPINDLE spindles can be enabled at a time.

◆ spindle_enumerate_spindles()

bool spindle_enumerate_spindles ( spindle_enumerate_callback_ptr  callback,
void *  data 
)

Enumerate registered spindles by calling a callback function for each of them.

Parameters
callbackpointer to a spindle_enumerate_callback_ptr type function.
datapointer to optional data to pass to the callback function.
Returns
true if spindles are registered and a callback function was provided, false otherwise.

◆ spindle_get()

spindle_ptrs_t* spindle_get ( spindle_num_t  spindle_num)

Get the handlers (function pointers) etc. associated with an enabled spindle.

Parameters
spindle_numspindle number as a spindle_num_t.
Returns
pointer to a spindle_ptrs_t structure if successful, NULL if not.

NOTE: do not modify the returned structure!

◆ spindle_get_caps()

spindle_cap_t spindle_get_caps ( bool  active)

Get the merged spindle capabilities of all registered spindles.

Parameters
activetrue to return active capabilities, false to return default capabilities.
Returns
capabilities in a spindle_cap_t structure.

◆ spindle_get_count()

uint8_t spindle_get_count ( void  )

Get number of registered spindles.

Returns
number of registered spindles.

◆ spindle_get_default()

spindle_id_t spindle_get_default ( void  )

Get the spindle id of the default spindle (spindle number 0).

Returns
spindle id as a spindle_id_t if successful, -2 if not (no spindle available).

◆ spindle_get_hal()

spindle_ptrs_t* spindle_get_hal ( spindle_id_t  spindle_id,
spindle_hal_t  hal 
)

Get the handlers (function pointers) etc. associated with the spindle.

Parameters
spindle_idspindle id as a spindle_id_t.
hala spindle_hal_t enum value:
SpindleHAL_Raw - get the read only version as supplied at registration
SpindleHAL_Configured - get the version with run-time modifications applied by the spindle driver.
SpindleHAL_Active - get the enabled version available from gcode. Can be overriden by event handlers prior to activation.
Returns
pointer to a spindle_ptrs_t structure if successful, NULL if not.

NOTE: do not modify the returned structure!

◆ spindle_get_name()

const char* spindle_get_name ( spindle_id_t  spindle_id)

Get the registered name of a spindle.

Parameters
spindle_idspindle id as a spindle_id_t.
Returns
pointer to a null terminated string if succesful, NULL if not.

◆ spindle_is_enabled()

bool spindle_is_enabled ( spindle_num_t  spindle_num)

Check if a spindle is enabled and available or not.

Parameters
spindle_numspindle number as a spindle_num_t.
Returns
true if the spindle is enabled, false otherwise.

◆ spindle_is_on()

bool spindle_is_on ( void  )

Check if any of the enabled spindles is running.

Returns
true if a spindle is running, false otherwise.

◆ spindle_precompute_pwm_values()

bool spindle_precompute_pwm_values ( spindle_ptrs_t spindle,
spindle_pwm_t pwm_data,
spindle_settings_t settings,
uint32_t  clock_hz 
)

Precompute PWM values for faster conversion.

Parameters
spindlepointer to a spindle_ptrs_t structure.
pwm_datapointer to a spindle_pwm_t structure, to hold the precomputed values.
clock_hztimer clock frequency used for PWM generation.
Returns
true if successful, false if no PWM range possible - driver should then revert to simple on/off spindle control.

◆ spindle_register()

spindle_id_t spindle_register ( const spindle_ptrs_t spindle,
const char *  name 
)

Register a spindle with the core.

Parameters
spindlepointer to a spindle_ptrs_t structure.
namepointer to a null terminated string.
Returns
assigned spindle id as a spindle_id_t if successful, -1 if not.

NOTE: The first spindle registered will become the default active spindle. NOTE: up to N_SPINDLE spindles can be registered at a time.

◆ spindle_restore()

bool spindle_restore ( spindle_ptrs_t spindle,
spindle_state_t  state,
float  rpm 
)

Restore spindle running state with direction, enable, spindle RPM and appropriate delay.

Parameters
spindlepointer to a spindle_ptrs_t structure.
statea spindle_state_t structure.
rpmthe spindle RPM to set.
Returns
true if successful, false if the current controller state is ABORTED.

◆ spindle_select()

bool spindle_select ( spindle_id_t  spindle_id)

Enables a spindle and sets it as default spindle (spindle number 0).

Parameters
spindle_idspindle id as a spindle_id_t.
Returns
true if succsesful, false if not.

◆ spindle_set_at_speed_range()

bool spindle_set_at_speed_range ( spindle_ptrs_t spindle,
spindle_data_t spindle_data,
float  rpm 
)

◆ spindle_set_override()

void spindle_set_override ( spindle_ptrs_t spindle,
override_t  speed_override 
)

Set spindle speed override.

Parameters
spindlepointer to a spindle_ptrs_t structure.
speed_overrideoverride as a percentage of the programmed RPM.

NOTE: Unlike motion overrides, spindle overrides do not require a planner reinitialization.

◆ spindle_set_rpm()

float spindle_set_rpm ( spindle_ptrs_t spindle,
float  rpm,
override_t  override_pct 
)

Calculate and set programmed RPM according to override and max/min limits.

Parameters
spindlepointer to a spindle_ptrs_t structure.
rpmthe programmed RPM.
override_pctoverride value in percent.
Returns
the calulated RPM.

◆ spindle_set_state()

bool spindle_set_state ( spindle_ptrs_t spindle,
spindle_state_t  state,
float  rpm 
)

Immediately sets spindle running state with direction and spindle rpm, if enabled. Called by g-code parser spindle_sync(), parking retract and restore, g-code program end, sleep, and spindle stop override.

Parameters
spindlepointer to a spindle_ptrs_t structure.
statea spindle_state_t structure.
rpmthe spindle RPM to set.
Returns
true if successful, false if the current controller state is ABORTED.

◆ spindle_sync()

bool spindle_sync ( spindle_ptrs_t spindle,
spindle_state_t  state,
float  rpm 
)

G-code parser entry-point for setting spindle state. Forces a planner buffer sync and bails if an abort or check-mode is active. If the spindle supports at speed functionality it will wait for it to reach the speed and raise an alarm if the speed is not reached within the timeout period.

Parameters
spindlepointer to a spindle_ptrs_t structure.
statea spindle_state_t structure.
rpmthe spindle RPM to set.
Returns
true if successful, false if the current controller state is ABORTED.

◆ spindle_update_caps()

void spindle_update_caps ( spindle_ptrs_t spindle,
spindle_pwm_t pwm_caps 
)

Update the capabilities of a registered PWM spindle. May be used by the driver on spindle initialization or when spindle settings has been changed.

Parameters
spindlepointer to a spindle_ptrs_t structure.
pwm_capspointer to a spindle_pwm_t structure.