spindle_control.h

Go to the documentation of this file.

/*
  spindle_control.h - spindle control methods
 
  Part of grblHAL
 
  Copyright (c) 2017-2025 Terje Io
  Copyright (c) 2012-2015 Sungeun K. Jeon
  Copyright (c) 2009-2011 Simen Svale Skogsrud
 
  grblHAL is free software: you can redistribute it and/or modify
  it under the terms of the GNU General Public License as published by
  the Free Software Foundation, either version 3 of the License, or
  (at your option) any later version.
 
  grblHAL is distributed in the hope that it will be useful,
  but WITHOUT ANY WARRANTY; without even the implied warranty of
  MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
  GNU General Public License for more details.
 
  You should have received a copy of the GNU General Public License
  along with grblHAL. If not, see <http://www.gnu.org/licenses/>.
*/
 
#ifndef _SPINDLE_CONTROL_H_
#define _SPINDLE_CONTROL_H_
 
#include "pid.h"
 
#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 // typically implemented by driver.c
#define SPINDLE_ONOFF0_DIR  8 // typically implemented by driver.c
#define SPINDLE_ONOFF1      9
#define SPINDLE_ONOFF1_DIR 10
#define SPINDLE_PWM0       11 // typically implemented by driver.c
#define SPINDLE_PWM0_NODIR 12 // typically implemented by driver.c
#define SPINDLE_PWM1       13 // typically implemented by driver.c
#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))
 
typedef int8_t spindle_id_t;
typedef int8_t spindle_num_t;
 
// if changed to > 8 bits planner_cond_t needs to be changed too
typedef union {
    uint8_t value;
    uint8_t mask;
    struct {
        uint8_t on               :1,
                ccw              :1,
                pwm              :1, 
                reserved         :1,
                override_disable :1,
                encoder_error    :1,
                at_speed         :1, 
                synchronized     :1;
    };
} spindle_state_t;
 
typedef union {
    uint16_t value; 
    struct {
        uint16_t variable          :1, 
                 direction         :1, 
                 at_speed          :1, 
                 laser             :1, 
                 pwm_invert        :1, 
                 pid               :1,
                 pwm_linearization :1,
                 rpm_range_locked  :1, 
                 gpio_controlled   :1, 
                 cmd_controlled    :1, 
                 cloned            :1, 
                 torch             :1, 
                 unassigned        :4;
    };
} spindle_cap_t;
 
typedef struct {
    float rpm;
    float rpm_low_limit;
    float rpm_high_limit;
    float angular_position; 
    float rpm_programmed;
    uint32_t index_count;
    uint32_t pulse_count;
    uint32_t error_count;
    bool at_speed_enabled;
    spindle_state_t state_programmed;
} spindle_data_t;
 
typedef enum {
    SpindleData_Counters,           
    SpindleData_RPM,                
    SpindleData_AngularPosition,    
    SpindleData_AtSpeed             
} spindle_data_request_t;
 
typedef enum {
    SpindleType_PWM,        
    SpindleType_Basic,      
    SpindleType_VFD,        
    SpindleType_Solenoid,   
    SpindleType_Stepper,    
    SpindleType_Null,       
} spindle_type_t;
 
typedef enum {
    SpindleHAL_Raw,         
    SpindleHAL_Configured,  
    SpindleHAL_Active,      
} spindle_hal_t;
 
struct spindle_ptrs;    // members defined below
struct spindle_pwm;     // members defined below
struct spindle_param;   // members defined below
 
typedef bool (*spindle_config_ptr)(struct spindle_ptrs *spindle);
 
typedef void (*spindle_set_state_ptr)(struct spindle_ptrs *spindle, spindle_state_t state, float rpm);
 
#ifdef GRBL_ESP32
typedef void (*esp32_spindle_off_ptr)(struct spindle_ptrs *spindle);
#endif
 
typedef spindle_state_t (*spindle_get_state_ptr)(struct spindle_ptrs *spindle);
 
typedef uint_fast16_t (*spindle_get_pwm_ptr)(struct spindle_ptrs *spindle, float rpm);
 
typedef void (*spindle_update_pwm_ptr)(struct spindle_ptrs *spindle, uint_fast16_t pwm);
 
typedef void (*spindle_update_rpm_ptr)(struct spindle_ptrs *spindle, float rpm);
 
typedef spindle_data_t *(*spindle_get_data_ptr)(spindle_data_request_t request);
 
typedef void (*spindle_reset_data_ptr)(void);
 
typedef void (*spindle_pulse_on_ptr)(struct spindle_ptrs *spindle, uint_fast16_t pulse_length);
 
typedef struct {
    float rpm;
    float start;
    float end;
} pwm_piece_t;
 
typedef union {
    uint8_t value;
    uint8_t mask;
    struct {
        uint8_t enable_rpm_controlled :1, // PWM spindle only
                laser_mode_disable    :1, // PWM spindle only
                pwm_disable           :1, // PWM spindle only
                unassigned            :5;
    };
} spindle_settings_flags_t;
 
typedef union {
    uint8_t value;
    uint8_t mask;
    struct {
        uint8_t allow_axis_control    :1,
                sync_position         :1,
                unassigned            :6;
    };
} stepper_spindle_settings_flags_t;
 
typedef struct {
    spindle_state_t invert;
    spindle_settings_flags_t flags;
    float rpm_max;
    float rpm_min;
    float pwm_freq;
    float pwm_off_value;
    float pwm_min_value;
    float pwm_max_value;
    float at_speed_tolerance;                   
    pwm_piece_t pwm_piece[SPINDLE_NPWM_PIECES];
} spindle_pwm_settings_t;
 
typedef struct {
    uint8_t ref_id;
    uint8_t encoder_spindle;
    uint16_t ppr;                               
    uint16_t on_delay;
    uint16_t off_delay;
    float at_speed_tolerance;                   
} spindle_settings_t;
 
typedef struct {
    uint8_t port_on;
    uint8_t port_dir;
    uint8_t port_pwm;
    spindle_pwm_settings_t cfg;
} spindle1_pwm_settings_t;
 
typedef union {
    uint8_t value;
    struct {
        uint8_t invert_pwm          :1, 
                always_on           :1,
                cloned              :1,
                rpm_controlled      :1,
                laser_mode_disable  :1,
                laser_off_overdrive :1,
                enable_out          :1,
                unused              :1;
    };
} spindle_pwm_flags_t;
 
typedef struct spindle_pwm {
    uint32_t f_clock;
    spindle_pwm_settings_t *settings;
    uint_fast16_t period;
    uint_fast16_t off_value;        
    uint_fast16_t min_value;
    uint_fast16_t max_value;
    float off_overdrive_pct;        
    uint_fast16_t pwm_overdrive;    
    spindle_pwm_flags_t flags;
    float rpm_min;                  
    float pwm_gradient;
    int_fast16_t offset;
    uint_fast16_t n_pieces;
    pwm_piece_t piece[SPINDLE_NPWM_PIECES];
    void (*set_laser_overdrive)(struct spindle_pwm *pwm_data, float pct);
    uint_fast16_t (*compute_value)(struct spindle_pwm *pwm_data, float rpm, bool pid_limit);
} spindle_pwm_t;
 
typedef union
{
    spindle_pwm_t *pwm;
} spindle_context_ptr_t __attribute__ ((__transparent_union__));
 
struct spindle_ptrs {
    spindle_id_t id;                    
    uint8_t ref_id;                     
    struct spindle_param *param;        
    spindle_type_t type;                
    spindle_cap_t cap;                  
    spindle_context_ptr_t context;      
    uint_fast16_t pwm_off_value;        
    float rpm_min;                      
    float rpm_max;                      
    float at_speed_tolerance;           
    spindle_config_ptr config;          
    spindle_set_state_ptr set_state;    
    spindle_get_state_ptr get_state;    
    spindle_get_pwm_ptr get_pwm;        
    spindle_update_pwm_ptr update_pwm;  
    spindle_update_rpm_ptr update_rpm;  
#ifdef GRBL_ESP32
    esp32_spindle_off_ptr esp32_off;    
#endif
    // Optional entry points.
    spindle_pulse_on_ptr pulse_on;      
    spindle_get_data_ptr get_data;      
    spindle_reset_data_ptr reset_data;  
};
 
typedef struct spindle_ptrs spindle_ptrs_t;
 
typedef struct {
    float surface_speed;    
    float target_rpm;       
    float delta_rpm;        
    float max_rpm;          
    float tool_offset;      
    uint_fast8_t axis;      
} spindle_css_data_t;
 
typedef struct spindle_param {
    float rpm;
    float rpm_overridden;
    spindle_state_t state;
    override_t override_pct;    
    spindle_css_data_t css;     
    spindle_ptrs_t *hal;
} spindle_param_t;
 
typedef struct {
    spindle_get_data_ptr get;      
    spindle_reset_data_ptr reset;  
} spindle_data_ptrs_t;
 
typedef struct  {
    spindle_id_t id;
    uint8_t ref_id;
    spindle_num_t num;
    const char *name;
    bool enabled;
    bool is_current;
    const spindle_ptrs_t *hal;
} spindle_info_t;
 
typedef bool (*spindle_enumerate_callback_ptr)(spindle_info_t *spindle, void *data);
 
void spindle_set_override (spindle_ptrs_t *spindle, override_t speed_override);
 
// Sets spindle running state with direction, enable, and spindle RPM.
bool spindle_set_state (spindle_ptrs_t *spindle, spindle_state_t state, float rpm);
 
// Called by g-code parser when setting spindle state and requires a buffer sync.
bool spindle_set_state_synced (spindle_ptrs_t *spindle, spindle_state_t state, float rpm);
 
bool spindle_check_state (spindle_ptrs_t *spindle, spindle_state_t state);
 
// Spindle speed calculation and limit handling
float spindle_set_rpm (spindle_ptrs_t *spindle, float rpm, override_t speed_override);
 
// Restore spindle running state with direction, enable, spindle RPM and appropriate delay.
bool spindle_restore (spindle_ptrs_t *spindle, spindle_state_t state, float rpm, uint16_t on_delay_ms);
 
void spindle_all_off (void);
 
//
// The following functions are not called by the core, may be called by driver code.
//
 
#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); }
/*
__attribute__((always_inline)) static inline void spindle_validate_at_speed (spindle_data_t *spindle_data, float rpm)
{
    spindle_data->rpm = rpm;
    spindle_data->state_programmed.at_speed = !spindle_data->at_speed_enabled || (spindle_data->rpm >= spindle_data->rpm_low_limit && spindle_data->rpm <= spindle_data->rpm_high_limit);
}
*/
 
bool spindle_precompute_pwm_values (spindle_ptrs_t *spindle, spindle_pwm_t *pwm_data, spindle_pwm_settings_t *settings, uint32_t clock_hz);
 
spindle_id_t spindle_register (const spindle_ptrs_t *spindle, const char *name);
 
spindle_id_t spindle_add_null (void);
 
uint8_t spindle_get_count (void);
 
bool spindle_get_id (uint8_t ref_id, spindle_id_t *spindle_id);
 
bool spindle_select (spindle_id_t spindle_id);
 
spindle_cap_t spindle_get_caps (bool active);
 
void spindle_update_caps (spindle_ptrs_t *spindle, spindle_pwm_t *pwm_caps);
 
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_t *spindle_get_hal (spindle_id_t spindle_id, spindle_hal_t hal);
 
const char *spindle_get_name (spindle_id_t spindle_id);
 
spindle_id_t spindle_get_default (void);
 
spindle_num_t spindle_enable (spindle_id_t spindle_id);
 
bool spindle_enumerate_spindles (spindle_enumerate_callback_ptr callback, void *data);
 
//
 
bool spindle_is_enabled (spindle_num_t spindle_num);
 
bool spindle_is_on (void);
 
spindle_ptrs_t *spindle_get (spindle_num_t spindle_num);
 
#if N_SPINDLE > 1
 
typedef void (*spindle1_settings_changed_ptr)(spindle1_pwm_settings_t *settings);
 
spindle1_pwm_settings_t *spindle1_settings_add (bool claim_ports);
void spindle1_settings_register (spindle_cap_t cap, spindle1_settings_changed_ptr on_changed);
 
#endif
 
#endif // _SPINDLE_CONTROL_H_