HAL function pointers and data structures definitions. More...

#include <time.h>
#include "grbl.h"
#include "core_handlers.h"
#include "gcode.h"
#include "coolant_control.h"
#include "spindle_control.h"
#include "crossbar.h"
#include "stepper.h"
#include "nvs.h"
#include "probe.h"
#include "ioports.h"
#include "rgb.h"
#include "plugins.h"

Data Structures
union	driver_cap_t
	Bitmap flags for driver capabilities, to be set by driver in driver_init(), flags may be cleared after to switch off option. More...

struct	periph_port_t

struct	coolant_ptrs_t
	Handlers for coolant support. More...

struct	limits_ptrs_t
	Limit switches handlers. More...

struct	homing_ptrs_t
	Limit switches handler for homing cycle. More...

struct	control_signals_ptrs_t
	Control switches handlers. More...

union	motor_map_t
	Motor vs. axis mapping NOTE: id and axis values are equal for primary motors, unequal for secondary (ganged) motors. More...

struct	stepper_ptrs_t
	Stepper motor handlers. More...

struct	delay_t
	Delay struct, currently not used by core - may be used by drivers. More...

struct	probe_ptrs_t
	Handlers for probe input(s). More...

struct	tool_ptrs_t
	Handlers for tool changes. More...

struct	user_mcode_ptrs_t
	Optional handlers for user defined M-codes. More...

struct	encoder_ptrs_t

struct	rtc_ptrs_t

struct	grbl_hal_t
	HAL structure used for the driver interface. More...

Macros
#define	HAL_VERSION 10

Typedefs
typedef bool(*	driver_setup_ptr) (settings_t *settings)
	Pointer to function called to set up driver peripherals after settings are loaded. More...

typedef void(*	driver_reset_ptr) (void)
	Pointer to function to be called when a soft reset occurs. More...

typedef uint32_t(*	get_free_mem_ptr) (void)
	Pointer to function for getting free memory (as sum of all free blocks in the heap). More...

typedef void(*	register_periph_pin_ptr) (const periph_pin_t *pin)
	Pointer to function for registering information about a peripheral pin. More...

typedef void(*	set_periph_pin_description_ptr) (const pin_function_t function, const pin_group_t group, const char *description)
	Pointer to function for setting pin description for a peripheral pin. More...

typedef void(*	pin_info_ptr) (xbar_t pin, void data)
	Pointer to callback function for pin enumerations. More...

typedef void(*	enumerate_pins_ptr) (bool low_level, pin_info_ptr callback, void *data)
	Pointer to function for enumerate pin information. More...

typedef void(*	coolant_set_state_ptr) (coolant_state_t state)
	Pointer to function for setting the coolant state. More...

typedef coolant_state_t(*	coolant_get_state_ptr) (void)
	Pointer to function for getting the coolant state. More...

typedef void(*	limits_enable_ptr) (bool on, axes_signals_t homing_cycle)
	Pointer to function for enabling/disabling limit switches functionality. More...

typedef limit_signals_t(*	limits_get_state_ptr) (void)
	Pointer to function for getting limit switches state. More...

typedef void(*	limit_interrupt_callback_ptr) (limit_signals_t state)
	Pointer to callback function for reporting limit switches events (interrupts). Set by the core on startup. More...

typedef home_signals_t(*	home_get_state_ptr) (void)
	Pointer to function for getting home switches state. More...

typedef float(*	homing_get_feedrate_ptr) (axes_signals_t axes, homing_mode_t mode)

typedef control_signals_t(*	control_signals_get_state_ptr) (void)
	Pointer to function for getting control switches state. More...

typedef void(*	control_signals_callback_ptr) (control_signals_t signals)
	Pointer to callback function for reporting control switches events (interrupts). Set by the core on startup. More...

typedef void(*	motor_iterator_callback_ptr) (motor_map_t motor)
	Signature of the callback function to receive motor vs. axis mappings. More...

typedef void(*	motor_iterator_ptr) (motor_iterator_callback_ptr callback)
	Pointer to function for iterating over stepper motor vs. axis mappings. More...

typedef void(*	stepper_wake_up_ptr) (void)
	Pointer to function for enabling all stepper motors and the main stepper interrupt. More...

typedef void(*	stepper_go_idle_ptr) (bool clear_signals)
	Pointer to function for disabling the main stepper interrupt. More...

typedef void(*	stepper_enable_ptr) (axes_signals_t enable)
	Pointer to function for enabling/disabling stepper motors. More...

typedef void(*	stepper_disable_motors_ptr) (axes_signals_t axes, squaring_mode_t mode)
	Pointer to function for enabling/disabling step signals for individual motors. More...

typedef void(*	stepper_cycles_per_tick_ptr) (uint32_t cycles_per_tick)
	Pointer to function for setting the step pulse interrupt rate for the next motion segment. More...

typedef void(*	stepper_pulse_start_ptr) (stepper_t *stepper)
	Pointer to function for setting up steppers for the next step pulse. More...

typedef void(*	stepper_output_step_ptr) (axes_signals_t step_outbits, axes_signals_t dir_outbits)
	Pointer to function for outputting a single step pulse and direction signal. More...

typedef axes_signals_t(*	stepper_get_ganged_ptr) (bool auto_squared)
	Pointer to function for getting which axes are configured for auto squaring. More...

typedef void(*	stepper_interrupt_callback_ptr) (void)
	Pointer to callback function for outputting the next direction and step pulse signals. Set by the core on startup. More...

typedef void(*	delay_callback_ptr) (void)
	Signature of delay callback functions. More...

typedef probe_state_t(*	probe_get_state_ptr) (void)
	Pointer to function for getting probe status. More...

typedef void(*	probe_configure_ptr) (bool is_probe_away, bool probing)
	Pointer to function for setting probe operation mode. More...

typedef void(*	probe_connected_toggle_ptr) (void)
	Pointer to function for toggling probe connected status. More...

typedef void(*	tool_select_ptr) (tool_data_t *tool, bool next)
	Pointer to function for selecting a tool. More...

typedef status_code_t(*	tool_change_ptr) (parser_state_t *gc_state)
	Pointer to function for executing a tool change. More...

typedef user_mcode_t(*	user_mcode_check_ptr) (user_mcode_t mcode)
	Pointer to function for checking if user defined M-code is supported. More...

typedef status_code_t(*	user_mcode_validate_ptr) (parser_block_t gc_block, parameter_words_t parameter_words)
	Pointer to function for validating parameters for a user defined M-code. More...

typedef void(*	user_mcode_execute_ptr) (sys_state_t state, parser_block_t *gc_block)
	Pointer to function for executing a user defined M-code. More...

typedef uint8_t(*	encoder_get_n_encoders_ptr) (void)
	Pointer to function for getting number of encoders supported. More...

typedef void(*	encoder_on_event_ptr) (encoder_t *encoder, int32_t position)
	Pointer to callback function to receive encoder events. More...

typedef void(*	encoder_reset_ptr) (uint_fast8_t id)
	Pointer to function for resetting encoder data. More...

typedef bool(*	irq_claim_ptr) (irq_type_t irq, uint_fast8_t id, irq_callback_ptr callback)
	Pointer to function for claiming higher level interrupt requests (irq). More...

typedef bool(*	rtc_get_datetime_ptr) (struct tm *datetime)
	Pointer to function for setting the current datetime. More...

typedef bool(*	rtc_set_datetime_ptr) (struct tm *datetime)
	Pointer to function for setting the current datetime. More...

typedef void(*	pallet_shuttle_ptr) (void)
	Pointer to function for performing a pallet shuttle. More...

Functions
bool	driver_init (void)
	Driver main entry point. This will be called once by the core after the HAL structure has been nulled and handlers provided by the core is set up. The driver should initialize all the required handlers and capabilities flags in this function. On successful return from this function the core will load settings from non-volatile storage (NVS) if handler functions were provided or load default values if not. Then hal.driver_setup() will be called so that the driver can configure the remaining MCU peripherals. More...

Variables
grbl_hal_t	hal
	Global HAL struct. More...

Detailed Description

HAL function pointers and data structures definitions.

Macro Definition Documentation

◆ HAL_VERSION

#define HAL_VERSION 10

Typedef Documentation

◆ control_signals_callback_ptr

typedef void(* control_signals_callback_ptr) (control_signals_t signals)

Pointer to callback function for reporting control switches events (interrupts). Set by the core on startup.

Parameters

signals input pin states in a control_signals_t struct.

◆ control_signals_get_state_ptr

typedef control_signals_t(* control_signals_get_state_ptr) (void)

Pointer to function for getting control switches state.

Returns: switch states in a control_signals_t struct.

◆ coolant_get_state_ptr

typedef coolant_state_t(* coolant_get_state_ptr) (void)

Pointer to function for getting the coolant state.

Returns: state in a coolant_state_t union variable.

◆ coolant_set_state_ptr

typedef void(* coolant_set_state_ptr) (coolant_state_t state)

Pointer to function for setting the coolant state.

Parameters

state a coolant_state_t union variable.

◆ delay_callback_ptr

typedef void(* delay_callback_ptr) (void)

Signature of delay callback functions.

◆ driver_reset_ptr

typedef void(* driver_reset_ptr) (void)

Pointer to function to be called when a soft reset occurs.

◆ driver_setup_ptr

typedef bool(* driver_setup_ptr) (settings_t *settings)

Pointer to function called to set up driver peripherals after settings are loaded.

◆ encoder_get_n_encoders_ptr

typedef uint8_t(* encoder_get_n_encoders_ptr) (void)

Pointer to function for getting number of encoders supported.

Returns: number of encoders.

◆ encoder_on_event_ptr

typedef void(* encoder_on_event_ptr) (encoder_t *encoder, int32_t position)

Pointer to callback function to receive encoder events.

Parameters

encoder	pointer to a encoder_t struct.
position	encoder position.

◆ encoder_reset_ptr

typedef void(* encoder_reset_ptr) (uint_fast8_t id)

Pointer to function for resetting encoder data.

Parameters

id	encoder id.

◆ enumerate_pins_ptr

typedef void(* enumerate_pins_ptr) (bool low_level, pin_info_ptr callback, void *data)

Pointer to function for enumerate pin information.

Parameters

low_level	true if low level information is required, false if used for reporting.
callback	pointer to a pin_info_ptr type function to receive the pin information.
data	pointer to void that can be used to pass data to the callback function. May be NULL. The callback function will be called for each pin.

◆ get_free_mem_ptr

typedef uint32_t(* get_free_mem_ptr) (void)

Pointer to function for getting free memory (as sum of all free blocks in the heap).

◆ home_get_state_ptr

typedef home_signals_t(* home_get_state_ptr) (void)

Pointer to function for getting home switches state.

Returns: switch states in a home_signals_t struct.

◆ homing_get_feedrate_ptr

typedef float(* homing_get_feedrate_ptr) (axes_signals_t axes, homing_mode_t mode)

◆ irq_claim_ptr

typedef bool(* irq_claim_ptr) (irq_type_t irq, uint_fast8_t id, irq_callback_ptr callback)

Pointer to function for claiming higher level interrupt requests (irq).

Parameters

irq	irq type as a irq_type_t enum value.
id	irq id, normally 0, > 0 if there are several sources for the same irq type.
callback	function as a irq_callback_ptr function pointer.

◆ limit_interrupt_callback_ptr

typedef void(* limit_interrupt_callback_ptr) (limit_signals_t state)

Pointer to callback function for reporting limit switches events (interrupts). Set by the core on startup.

Parameters

state input pin states in a limit_signals_t struct.

◆ limits_enable_ptr

typedef void(* limits_enable_ptr) (bool on, axes_signals_t homing_cycle)

Pointer to function for enabling/disabling limit switches functionality.

Parameters

on	true to enable limit switches interrupts.
homing	true when machine is in a homing cycle. Usually ignored by driver code, may be used if Trinamic drivers are supported.

◆ limits_get_state_ptr

typedef limit_signals_t(* limits_get_state_ptr) (void)

Pointer to function for getting limit switches state.

Returns: switch states in a limit_signals_t struct.

◆ motor_iterator_callback_ptr

typedef void(* motor_iterator_callback_ptr) (motor_map_t motor)

Signature of the callback function to receive motor vs. axis mappings.

Parameters

motor a motor_map_t struct.

◆ motor_iterator_ptr

typedef void(* motor_iterator_ptr) (motor_iterator_callback_ptr callback)

Pointer to function for iterating over stepper motor vs. axis mappings.

Parameters

callback pointer to a motor_iterator_callback_ptr function to be called for each motor.

◆ pallet_shuttle_ptr

typedef void(* pallet_shuttle_ptr) (void)

Pointer to function for performing a pallet shuttle.

◆ pin_info_ptr

typedef void(* pin_info_ptr) (xbar_t *pin, void *data)

Pointer to callback function for pin enumerations.

Parameters

pin	pointer to the xbar_t structure holding the pin information.
data	pointer to void that may hold data data useful to the callback function.

◆ probe_configure_ptr

typedef void(* probe_configure_ptr) (bool is_probe_away, bool probing)

Pointer to function for setting probe operation mode.

Parameters

is_probe_away	true if probing away from the workpiece, false otherwise. When probing away the signal must be inverted in the probe_get_state_ptr() implementation.
probing	true if probe cycle is active, false otherwise.

◆ probe_connected_toggle_ptr

typedef void(* probe_connected_toggle_ptr) (void)

Pointer to function for toggling probe connected status.

If the driver does not support a probe connected input signal this can be used to implement toggling of probe connected status via a CMD_PROBE_CONNECTED_TOGGLE real time command.

◆ probe_get_state_ptr

typedef probe_state_t(* probe_get_state_ptr) (void)

Pointer to function for getting probe status.

Returns: probe state in a probe_state_t union.

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

◆ register_periph_pin_ptr

typedef void(* register_periph_pin_ptr) (const periph_pin_t *pin)

Pointer to function for registering information about a peripheral pin.

Parameters

pin	as periph_pin_t struct containing pin information.

◆ rtc_get_datetime_ptr

typedef bool(* rtc_get_datetime_ptr) (struct tm *datetime)

Pointer to function for setting the current datetime.

Parameters

datetime pointer to a tm struct.

Returns: true if successful.

◆ rtc_set_datetime_ptr

typedef bool(* rtc_set_datetime_ptr) (struct tm *datetime)

Pointer to function for setting the current datetime.

Parameters

datetime pointer to a tm struct.

Returns: true if successful.

◆ set_periph_pin_description_ptr

typedef void(* set_periph_pin_description_ptr) (const pin_function_t function, const pin_group_t group, const char *description)

Pointer to function for setting pin description for a peripheral pin.

Parameters

function	as pin_function_t enum.
group	as pin_group_t enum.
description	pointer to null terminated description string.

◆ stepper_cycles_per_tick_ptr

typedef void(* stepper_cycles_per_tick_ptr) (uint32_t cycles_per_tick)

Pointer to function for setting the step pulse interrupt rate for the next motion segment.

The driver should limit the maximum time between step interrupts to a few seconds if a 32-bit timer is used.

Parameters

cycles_per_tick number of clock ticks between main stepper interrupts.

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

◆ stepper_disable_motors_ptr

typedef void(* stepper_disable_motors_ptr) (axes_signals_t axes, squaring_mode_t mode)

Pointer to function for enabling/disabling step signals for individual motors.

Used by auto squaring functionality where two motors are employed for one or more axes.

Parameters

axes	a axes_signals_t union containing separate flags for each motor to enable/disable.
mode	a squaring_mode_t enum for which side to enable/disable.

◆ stepper_enable_ptr

typedef void(* stepper_enable_ptr) (axes_signals_t enable)

Pointer to function for enabling/disabling stepper motors.

Parameters

enable a axes_signals_t union containing separate flags for each motor to enable/disable.

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

◆ stepper_get_ganged_ptr

typedef axes_signals_t(* stepper_get_ganged_ptr) (bool auto_squared)

Pointer to function for getting which axes are configured for auto squaring.

Returns: which axes are configured for ganging or auto squaring in an axes_signals_t union.

◆ stepper_go_idle_ptr

typedef void(* stepper_go_idle_ptr) (bool clear_signals)

Pointer to function for disabling the main stepper interrupt.

Parameters

clear_signals when true stepper motor outputs can be reset to the default state. This parameter can often be ignored.

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

◆ stepper_interrupt_callback_ptr

typedef void(* stepper_interrupt_callback_ptr) (void)

Pointer to callback function for outputting the next direction and step pulse signals. Set by the core on startup.

To be called by the driver from the main stepper interrupt handler (when the timer times out).

◆ stepper_output_step_ptr

typedef void(* stepper_output_step_ptr) (axes_signals_t step_outbits, axes_signals_t dir_outbits)

Pointer to function for outputting a single step pulse and direction signal.

This is for an experimental implementation of plasma Torch Height Control (THC) and may be removed and/or changed.

Parameters

step_outbits	a axes_signals_t union containing the axes to output a step signal for.
dir_outbits	a axes_signals_t union containing the axes to output a direction signal for.

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

◆ stepper_pulse_start_ptr

typedef void(* stepper_pulse_start_ptr) (stepper_t *stepper)

Pointer to function for setting up steppers for the next step pulse.

For plain drivers the most of the information pointed to by the stepper argument can be ignored. The most used fields are these:
stepper::step_outbits
stepper::dir_outbits - these are only necessary to output to the drivers when stepper::dir_change is true.

If the driver is to support spindle synced motion many more needs to be referenced...

Parameters

stepper pointer to a stepper struct containing information about the stepper signals to be output.

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

◆ stepper_wake_up_ptr

typedef void(* stepper_wake_up_ptr) (void)

Pointer to function for enabling all stepper motors and the main stepper interrupt.

The first interrupt should be generated after a short delay to allow the drivers time to apply power to the motors.

◆ tool_change_ptr

typedef status_code_t(* tool_change_ptr) (parser_state_t *gc_state)

Pointer to function for executing a tool change.

Parameters

gc_state pointer to parser_state_t struct.

◆ tool_select_ptr

typedef void(* tool_select_ptr) (tool_data_t *tool, bool next)

Pointer to function for selecting a tool.

Parameters

tool	pointer to tool_data_t struct.
next	true if tool is selected for next the next tool change (M6), false to as set current tool.

◆ user_mcode_check_ptr

typedef user_mcode_t(* user_mcode_check_ptr) (user_mcode_t mcode)

Pointer to function for checking if user defined M-code is supported.

Parameters

mcode as a user_mcode_t enum.

Returns: the mcode argument if M-code is handled, UserMCode_Ignore if not.

◆ user_mcode_execute_ptr

typedef void(* user_mcode_execute_ptr) (sys_state_t state, parser_block_t *gc_block)

Pointer to function for executing a user defined M-code.

The M-code to execute is found in gc_block->user_mcode, parameter values in gc_block->values and claimed/validated parameter letters in the gc_block->words bitfield union.

Parameters

state	as a sys_state_t variable.
gc_block	pointer to a parser_block_t structure.

Returns: Status_OK enum value if validated ok, appropriate status_code_t enum value if not or Status_Unhandled if M-code is not recognized.

◆ user_mcode_validate_ptr

typedef status_code_t(* user_mcode_validate_ptr) (parser_block_t *gc_block, parameter_words_t *parameter_words)

Pointer to function for validating parameters for a user defined M-code.

The M-code to validate is found in gc_block->user_mcode, parameter values in gc_block->values and corresponding parameter letters in the gc_block->words bitfield union.

Parameter values claimed by the M-code must be flagged in the gc_block->words bitfield union by setting the respective parameter letters to false or the parser will raise the Status_GcodeUnusedWords error.

The validation function may set gc_block->user_mcode_sync to true if it is to be executed after all buffered motions are completed, otherwise it will be executed immediately.

NOTE: Valueless parameter letters are allowed for floats, these are set to NAN (not a number) if so. The validation function should always test these by using the isnan() function in addition to any range checks.

Parameters

gc_block	pointer to a parser_block_t structure.
parameter_words	pointer to a parameter_words_t structure. NOTE: this parameter is deprecated and will be removed, use gc_block->words instead.

Returns: Status_OK enum value if validated ok, appropriate status_code_t enum value if not or Status_Unhandled if the M-code is not recognized.

Function Documentation

◆ driver_init()

bool driver_init ( void )

Driver main entry point. This will be called once by the core after the HAL structure has been nulled and handlers provided by the core is set up. The driver should initialize all the required handlers and capabilities flags in this function. On successful return from this function the core will load settings from non-volatile storage (NVS) if handler functions were provided or load default values if not. Then hal.driver_setup() will be called so that the driver can configure the remaining MCU peripherals.

NOTE: This is the only driver function that is called directly from the core, all others are called via HAL function pointers.

Returns: true if completed successfully and the driver matches the hal.version number, false otherwise.

Variable Documentation

◆ hal

grbl_hal_t hal

extern

Global HAL struct.

Data Structures

Macros

Typedefs

Functions

Variables

Detailed Description

Macro Definition Documentation

◆ HAL_VERSION

Typedef Documentation

◆ control_signals_callback_ptr

◆ control_signals_get_state_ptr

◆ coolant_get_state_ptr

◆ coolant_set_state_ptr

◆ delay_callback_ptr

◆ driver_reset_ptr

◆ driver_setup_ptr

◆ encoder_get_n_encoders_ptr

◆ encoder_on_event_ptr

◆ encoder_reset_ptr

◆ enumerate_pins_ptr

◆ get_free_mem_ptr

◆ home_get_state_ptr

◆ homing_get_feedrate_ptr

◆ irq_claim_ptr

◆ limit_interrupt_callback_ptr

◆ limits_enable_ptr

◆ limits_get_state_ptr

◆ motor_iterator_callback_ptr

◆ motor_iterator_ptr

◆ pallet_shuttle_ptr

◆ pin_info_ptr

◆ probe_configure_ptr

◆ probe_connected_toggle_ptr

◆ probe_get_state_ptr

◆ register_periph_pin_ptr

◆ rtc_get_datetime_ptr

◆ rtc_set_datetime_ptr

◆ set_periph_pin_description_ptr

◆ stepper_cycles_per_tick_ptr

◆ stepper_disable_motors_ptr

◆ stepper_enable_ptr

◆ stepper_get_ganged_ptr

◆ stepper_go_idle_ptr

◆ stepper_interrupt_callback_ptr

◆ stepper_output_step_ptr

◆ stepper_pulse_start_ptr

◆ stepper_wake_up_ptr

◆ tool_change_ptr

◆ tool_select_ptr

◆ user_mcode_check_ptr

◆ user_mcode_execute_ptr

◆ user_mcode_validate_ptr

Function Documentation

◆ driver_init()

Variable Documentation

◆ hal