hal.h File Reference

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"

Go to the source code of this file.

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	encoder_ptrs_t
union	timer_cap_t
struct	timer_cfg_t
struct	timer_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, bool hold)
	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_claim_motor_ptr) (uint_fast8_t axis_id, bool claim)
	Pointer to function for claiming/releasing motor(s) from/to normal step/dir signalling. 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 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 void *	hal_timer_t
	Timer handle, actual type defined by driver implementation. More...
typedef void(*	timer_irq_handler_ptr) (void *context)
typedef hal_timer_t(*	timer_claim_ptr) (timer_cap_t cap, uint32_t timebase)
	Pointer to function for claiming a timer. More...
typedef bool(*	timer_cfg_ptr) (hal_timer_t timer, timer_cfg_t *cfg)
	Pointer to function for configuring a timer. More...
typedef bool(*	timer_start_ptr) (hal_timer_t timer, uint32_t period)
	Pointer to function for starting a timer. More...
typedef bool(*	timer_stop_ptr) (hal_timer_t timer)
	Pointer to function for stopping a running timer. 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...

Enumerations
enum	timer_resolution_t { Timer_16bit = 0 , Timer_32bit , Timer_64bit }

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).

hal_timer_t

typedef void* hal_timer_t

Timer handle, actual type defined by driver implementation.

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_claim_motor_ptr

typedef void(* stepper_claim_motor_ptr) (uint_fast8_t axis_id, bool claim)

Pointer to function for claiming/releasing motor(s) from/to normal step/dir signalling.

Parameters

axis_id	a the axis to claim/release motor(s) for.
claim	true to claim a motor(s), false to release.

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, bool hold)

Pointer to function for enabling/disabling stepper motors.

Parameters

enable	a axes_signals_t union containing separate flags for each motor to enable/disable.
hold	a true to keep motor powered with reduced current, false otherwise.

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.

timer_cfg_ptr

typedef bool(* timer_cfg_ptr) (hal_timer_t timer, timer_cfg_t *cfg)

Pointer to function for configuring a timer.

Parameters

timer	a hal_timer_t pointer.
cfg	pointer to a timer_cfg_t struct.

Returns

true if successful.

timer_claim_ptr

typedef hal_timer_t(* timer_claim_ptr) (timer_cap_t cap, uint32_t timebase)

Pointer to function for claiming a timer.

Parameters

cap	pointer to a timer_cap_t struct containing the required capabilities.
timebase	timebase in ns.

Returns

a hal_timer_t pointer if successful, NULL if not.

timer_irq_handler_ptr

typedef void(* timer_irq_handler_ptr) (void *context)

timer_start_ptr

typedef bool(* timer_start_ptr) (hal_timer_t timer, uint32_t period)

Pointer to function for starting a timer.

Parameters

timer	a hal_timer_t pointer.
period	delay in.

Returns

true if successful.

timer_stop_ptr

typedef bool(* timer_stop_ptr) (hal_timer_t timer)

Pointer to function for stopping a running timer.

Parameters

timer

a hal_timer_t pointer.

Returns

true if successful.

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.

Enumeration Type Documentation

timer_resolution_t

enum timer_resolution_t

Enumerator
Timer_16bit
Timer_32bit
Timer_64bit

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.