grblHAL core  20250806
ioports.h File Reference

Go to the source code of this file.

Data Structures

struct  io_port_t
 Properties and handlers for auxiliary digital and analog I/O. More...
 
union  driver_caps_t
 
union  io_port_cando_t
 
struct  io_ports_detail_t
 
struct  io_ports_data
 
struct  io_analog_t
 
struct  io_digital_t
 
struct  ioports_pwm_t
 Precalculated values that may be set/used by HAL driver to speed up analog input to PWM conversions. *‍/. More...
 

Macros

#define IOPORT_UNASSIGNED   255
 

Typedefs

typedef void(* digital_out_ptr) (uint8_t port, bool on)
 Pointer to function for setting a digital output. More...
 
typedef bool(* analog_out_ptr) (uint8_t port, float value)
 Pointer to function for setting an analog output. More...
 
typedef int32_t(* wait_on_input_ptr) (io_port_type_t type, uint8_t port, wait_mode_t wait_mode, float timeout)
 Pointer to function for reading a digital or analog input. More...
 
typedef int32_t(* ll_wait_on_input_ptr) (uint8_t port, wait_mode_t wait_mode, float timeout)
 Pointer to function for reading a digital or analog input. More...
 
typedef void(* set_pin_description_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t port, const char *s)
 Pointer to function for setting pin description for a digital or analog port. More...
 
typedef void(* ll_set_pin_description_ptr) (io_port_direction_t dir, uint8_t port, const char *s)
 Pointer to function for setting pin description for a digital or analog port. More...
 
typedef xbar_t *(* get_pin_info_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t port)
 Pointer to function for getting information about a digital or analog port.
NOTE: The port information pointed to will be overwritten by the next call to this function. More...
 
typedef xbar_t *(* ll_get_pin_info_ptr) (io_port_direction_t dir, uint8_t port)
 Pointer to function for getting information about a digital or analog port.
NOTE: The port information pointed to will be overwritten by the next call to this function. More...
 
typedef bool(* claim_port_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t *port, const char *description)
 Pointer to function for claiming a digital or analog port for exclusive use. More...
 
typedef bool(* ll_claim_port_ptr) (io_port_direction_t dir, uint8_t port, uint8_t user_port, const char *description)
 Pointer to function for claiming a digital or analog port for exclusive use. More...
 
typedef bool(* swap_pins_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t port_from, uint8_t port_to)
 Pointer to function for swapping two digital or analog ports. More...
 
typedef void(* ioport_interrupt_callback_ptr) (uint8_t port, bool state)
 Pointer to callback function for input port interrupt events. More...
 
typedef bool(* ioport_register_interrupt_handler_ptr) (uint8_t port, pin_irq_mode_t irq_mode, ioport_interrupt_callback_ptr interrupt_callback)
 Pointer to function for registering or deregistering an interrupt handler for a digital input port. More...
 
typedef bool(* ll_ioport_register_interrupt_handler_ptr) (uint8_t port, uint8_t user_port, pin_irq_mode_t irq_mode, ioport_interrupt_callback_ptr interrupt_callback)
 Pointer to function for registering or deregistering an interrupt handler for a digital input port. More...
 
typedef bool(* ioports_enumerate_callback_ptr) (xbar_t *properties, uint8_t port, void *data)
 
typedef struct io_ports_data io_ports_data_t
 

Enumerations

enum  io_port_type_t { Port_Analog = 0 , Port_Digital = 1 }
 
enum  io_port_direction_t { Port_Input = 0 , Port_Output = 1 }
 

Functions

uint8_t ioports_available (io_port_type_t type, io_port_direction_t dir)
 Get number of digital or analog ports available. More...
 
uint8_t ioports_unclaimed (io_port_type_t type, io_port_direction_t dir)
 Get number of unclaimed digital or analog ports available. More...
 
xbar_tioport_get_info (io_port_type_t type, io_port_direction_t dir, uint8_t port)
 Return information about a digital or analog port. More...
 
xbar_tioport_claim (io_port_type_t type, io_port_direction_t dir, uint8_t *port, const char *description)
 Claim a digital or analog port for exclusive use. More...
 
bool ioport_claimable (io_port_type_t type, io_port_direction_t dir, uint8_t port)
 Check if a analog or digital port is available for exclusive use. More...
 
io_port_cando_t ioports_can_do (void)
 Get basic ioports capabilities. More...
 
uint8_t ioport_find_free (io_port_type_t type, io_port_direction_t dir, pin_cap_t filter, const char *description)
 find claimable or claimed analog or digital port. Search starts from the last port number. More...
 
bool ioports_enumerate (io_port_type_t type, io_port_direction_t dir, pin_cap_t filter, ioports_enumerate_callback_ptr callback, void *data)
 Enumerate ports. More...
 
bool ioport_set_description (io_port_type_t type, io_port_direction_t dir, uint8_t port, const char *description)
 Set pin description. More...
 
bool ioport_set_function (xbar_t *pin, pin_function_t function, driver_caps_t caps)
 Set pin function. More...
 
bool ioport_analog_out (uint8_t port, float value)
 
bool ioport_digital_out (uint8_t port, uint32_t value)
 
int32_t ioport_wait_on_input (io_port_type_t type, uint8_t port, wait_mode_t wait_mode, float timeout)
 
bool ioport_analog_out_config (uint8_t port, pwm_config_t *config)
 
bool ioport_digital_pwm_config (uint8_t port, pwm_config_t *config)
 
bool ioport_digital_in_config (uint8_t port, gpio_in_config_t *config)
 
bool ioport_enable_irq (uint8_t port, pin_irq_mode_t irq_mode, ioport_interrupt_callback_ptr handler)
 
bool ioport_digital_out_config (uint8_t port, gpio_out_config_t *config)
 
bool ioports_add_analog (io_analog_t *ports)
 
bool ioports_add_digital (io_digital_t *ports)
 
void ioports_add_settings (driver_settings_load_ptr settings_loaded, setting_changed_ptr setting_changed)
 
bool ioport_remap (io_port_type_t type, io_port_direction_t dir, uint8_t from, uint8_t to)
 Remap (virtual) port. More...
 
void ioport_save_input_settings (xbar_t *xbar, gpio_in_config_t *config)
 
void ioport_save_output_settings (xbar_t *xbar, gpio_out_config_t *config)
 
void ioport_setting_changed (setting_id_t id)
 
uint8_t ioports_map_reverse (io_ports_detail_t *type, uint8_t port)
 
bool ioports_precompute_pwm_values (pwm_config_t *config, ioports_pwm_t *pwm_data, uint32_t clock_hz)
 Precompute PWM values for faster conversion. More...
 
uint_fast16_t ioports_compute_pwm_value (ioports_pwm_t *pwm_data, float value)
 Analog value to PWM conversion. More...
 
bool ioports_add (io_ports_data_t *ports, io_port_type_t type, uint8_t n_in, uint8_t n_out)
 Deprecated - use ioports_add_analog() or ioports_add_digital() instead. More...
 
bool ioport_can_claim_explicit (void)
 Deprecated - use ioports_can_do() instead. More...
 
void ioport_assign_function (aux_ctrl_t *aux_ctrl, pin_function_t *function)
 Deprecated - use ioport_set_function() instead. More...
 
void ioport_assign_out_function (aux_ctrl_out_t *aux_ctrl, pin_function_t *function)
 Deprecated - use ioport_set_function() instead. More...
 

Macro Definition Documentation

◆ IOPORT_UNASSIGNED

#define IOPORT_UNASSIGNED   255

Typedef Documentation

◆ analog_out_ptr

typedef bool(* analog_out_ptr) (uint8_t port, float value)

Pointer to function for setting an analog output.

Parameters
portport number.
value
Returns
true if successful, false otherwise.

◆ claim_port_ptr

typedef bool(* claim_port_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t *port, const char *description)

Pointer to function for claiming a digital or analog port for exclusive use.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portport number.
descriptiondescription of the pin function.
Returns
true if successful, false if not.

◆ digital_out_ptr

typedef void(* digital_out_ptr) (uint8_t port, bool on)

Pointer to function for setting a digital output.

Parameters
portport number
ontrue to set output high, false to set it low

◆ get_pin_info_ptr

typedef xbar_t*(* get_pin_info_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t port)

Pointer to function for getting information about a digital or analog port.
NOTE: The port information pointed to will be overwritten by the next call to this function.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portport number.
Returns
pointer to port information in a xbar_t struct if successful, NULL if not.

◆ io_ports_data_t

◆ ioport_interrupt_callback_ptr

typedef void(* ioport_interrupt_callback_ptr) (uint8_t port, bool state)

Pointer to callback function for input port interrupt events.

Parameters
portport number.
statetrue if port level is high, false if it is low.

◆ ioport_register_interrupt_handler_ptr

typedef bool(* ioport_register_interrupt_handler_ptr) (uint8_t port, pin_irq_mode_t irq_mode, ioport_interrupt_callback_ptr interrupt_callback)

Pointer to function for registering or deregistering an interrupt handler for a digital input port.

Parameters
portport number.
irq_modea pin_irq_mode_t enum value.
interrupt_callbackpointer to the callback function to register or NULL to deregister the current callback.
Returns
true if successful, false otherwise.

◆ ioports_enumerate_callback_ptr

typedef bool(* ioports_enumerate_callback_ptr) (xbar_t *properties, uint8_t port, void *data)

◆ ll_claim_port_ptr

typedef bool(* ll_claim_port_ptr) (io_port_direction_t dir, uint8_t port, uint8_t user_port, const char *description)

Pointer to function for claiming a digital or analog port for exclusive use.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portport number.
descriptiondescription of the pin function.
Returns
true if successful, false if not.

◆ ll_get_pin_info_ptr

typedef xbar_t*(* ll_get_pin_info_ptr) (io_port_direction_t dir, uint8_t port)

Pointer to function for getting information about a digital or analog port.
NOTE: The port information pointed to will be overwritten by the next call to this function.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portport number.
Returns
pointer to port information in a xbar_t struct if successful, NULL if not.

◆ ll_ioport_register_interrupt_handler_ptr

typedef bool(* ll_ioport_register_interrupt_handler_ptr) (uint8_t port, uint8_t user_port, pin_irq_mode_t irq_mode, ioport_interrupt_callback_ptr interrupt_callback)

Pointer to function for registering or deregistering an interrupt handler for a digital input port.

Parameters
portport number.
user_portport number to be used for the callback.
irq_modea pin_irq_mode_t enum value.
interrupt_callbackpointer to the callback function to register or NULL to deregister the current callback.
Returns
true if successful, false otherwise.

◆ ll_set_pin_description_ptr

typedef void(* ll_set_pin_description_ptr) (io_port_direction_t dir, uint8_t port, const char *s)

Pointer to function for setting pin description for a digital or analog port.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portport number.
spointer to null terminated description string.

◆ ll_wait_on_input_ptr

typedef int32_t(* ll_wait_on_input_ptr) (uint8_t port, wait_mode_t wait_mode, float timeout)

Pointer to function for reading a digital or analog input.

NOTE: The latest value read is stored in sys sys.var5399.

Parameters
typeas an io_port_type_t enum value.
portport number.
wait_modea wait_mode_t enum value.
timeoutin seconds, ignored if wait_mode is WaitMode_Immediate (0).
Returns
read value if successful, -1 otherwise.

◆ set_pin_description_ptr

typedef void(* set_pin_description_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t port, const char *s)

Pointer to function for setting pin description for a digital or analog port.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portport number.
spointer to null terminated description string.

◆ swap_pins_ptr

typedef bool(* swap_pins_ptr) (io_port_type_t type, io_port_direction_t dir, uint8_t port_from, uint8_t port_to)

Pointer to function for swapping two digital or analog ports.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
port_fromport number.
port_toport number.
Returns
true if successful, false if not.

◆ wait_on_input_ptr

typedef int32_t(* wait_on_input_ptr) (io_port_type_t type, uint8_t port, wait_mode_t wait_mode, float timeout)

Pointer to function for reading a digital or analog input.

NOTE: The latest value read is stored in sys sys.var5399.

Parameters
typeas an io_port_type_t enum value.
portport number.
wait_modea wait_mode_t enum value.
timeoutin seconds, ignored if wait_mode is WaitMode_Immediate (0).
Returns
read value if successful, -1 otherwise.

Enumeration Type Documentation

◆ io_port_direction_t

Enumerator
Port_Input 

0

Port_Output 

1

◆ io_port_type_t

Enumerator
Port_Analog 

0

Port_Digital 

1

Function Documentation

◆ ioport_analog_out()

bool ioport_analog_out ( uint8_t  port,
float  value 
)

◆ ioport_analog_out_config()

bool ioport_analog_out_config ( uint8_t  port,
pwm_config_t config 
)

◆ ioport_assign_function()

void ioport_assign_function ( aux_ctrl_t aux_ctrl,
pin_function_t function 
)

Deprecated - use ioport_set_function() instead.

◆ ioport_assign_out_function()

void ioport_assign_out_function ( aux_ctrl_out_t aux_ctrl,
pin_function_t function 
)

Deprecated - use ioport_set_function() instead.

◆ ioport_can_claim_explicit()

bool ioport_can_claim_explicit ( void  )

Deprecated - use ioports_can_do() instead.

◆ ioport_claim()

xbar_t* ioport_claim ( io_port_type_t  type,
io_port_direction_t  dir,
uint8_t *  port,
const char *  description 
)

Claim a digital or analog port for exclusive use.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portpointer to a uint8_t holding the ports aux number, returns the actual port number to use if successful.
descriptionpointer to a char constant for the pin description.
Returns
pointer to a xbar_t structure with details about the claimed port if successful, NULL if not.

◆ ioport_claimable()

bool ioport_claimable ( io_port_type_t  type,
io_port_direction_t  dir,
uint8_t  port 
)

Check if a analog or digital port is available for exclusive use.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
porta uint8_t holding the ports aux number.
Returns
TRUE if available, FALSE if not.

◆ ioport_digital_in_config()

bool ioport_digital_in_config ( uint8_t  port,
gpio_in_config_t config 
)

◆ ioport_digital_out()

bool ioport_digital_out ( uint8_t  port,
uint32_t  value 
)

◆ ioport_digital_out_config()

bool ioport_digital_out_config ( uint8_t  port,
gpio_out_config_t config 
)

◆ ioport_digital_pwm_config()

bool ioport_digital_pwm_config ( uint8_t  port,
pwm_config_t config 
)

◆ ioport_enable_irq()

bool ioport_enable_irq ( uint8_t  port,
pin_irq_mode_t  irq_mode,
ioport_interrupt_callback_ptr  handler 
)

◆ ioport_find_free()

uint8_t ioport_find_free ( io_port_type_t  type,
io_port_direction_t  dir,
pin_cap_t  filter,
const char *  description 
)

find claimable or claimed analog or digital port. Search starts from the last port number.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
descriptionpointer to a char constant for the pin description of a previousely claimed port or a port number to be used as the upper limit for the search, or NULL if searching for the first free port.
Returns
the port number if successful, 0xFF (255) if not.

◆ ioport_get_info()

xbar_t* ioport_get_info ( io_port_type_t  type,
io_port_direction_t  dir,
uint8_t  port 
)

Return information about a digital or analog port.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portthe port aux number.
Returns
pointer to xbar_t struct if successful, NULL if not.

◆ ioport_remap()

bool ioport_remap ( io_port_type_t  type,
io_port_direction_t  dir,
uint8_t  port_from,
uint8_t  port_to 
)

Remap (virtual) port.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
port_fromthe assigned port number.
port_tothe remapped port number. The original port number will be swapped with port_from.
Returns
true if successful, false if original port is already claimed.

◆ ioport_save_input_settings()

void ioport_save_input_settings ( xbar_t xbar,
gpio_in_config_t config 
)

◆ ioport_save_output_settings()

void ioport_save_output_settings ( xbar_t xbar,
gpio_out_config_t config 
)

◆ ioport_set_description()

bool ioport_set_description ( io_port_type_t  type,
io_port_direction_t  dir,
uint8_t  port,
const char *  description 
)

Set pin description.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
portthe port aux number.
descriptionpointer to a char constant for the pin description.

◆ ioport_set_function()

bool ioport_set_function ( xbar_t pin,
pin_function_t  function,
driver_caps_t  caps 
)

Set pin function.

Parameters
portpointer to a xbar_t structure.
functiona pin_function_t enum value.
capspointer to driver_caps_t capability flags.

◆ ioport_setting_changed()

void ioport_setting_changed ( setting_id_t  id)

◆ ioport_wait_on_input()

int32_t ioport_wait_on_input ( io_port_type_t  type,
uint8_t  port,
wait_mode_t  wait_mode,
float  timeout 
)

◆ ioports_add()

bool ioports_add ( io_ports_data_t ports,
io_port_type_t  type,
uint8_t  n_in,
uint8_t  n_out 
)

Deprecated - use ioports_add_analog() or ioports_add_digital() instead.

◆ ioports_add_analog()

bool ioports_add_analog ( io_analog_t ports)

◆ ioports_add_digital()

bool ioports_add_digital ( io_digital_t ports)

◆ ioports_add_settings()

void ioports_add_settings ( driver_settings_load_ptr  settings_loaded,
setting_changed_ptr  setting_changed 
)

◆ ioports_available()

uint8_t ioports_available ( io_port_type_t  type,
io_port_direction_t  dir 
)

Get number of digital or analog ports available.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
Returns
number of ports available excluding remapped ports but including claimed ports if the API implementation supports that.

◆ ioports_can_do()

io_port_cando_t ioports_can_do ( void  )

Get basic ioports capabilities.

Returns
a io_port_cando_t union.

◆ ioports_compute_pwm_value()

uint_fast16_t ioports_compute_pwm_value ( ioports_pwm_t pwm_data,
float  value 
)

Analog value to PWM conversion.

Parameters
pwm_datapointer to a ioports_pwm_t structure.
valueanalog value to be converted.
Returns
the PWM value to use.

NOTE: ioports_precompute_pwm_values() must be called to precompute values before this function is called. Typically this is done by the ioports initialization code.

◆ ioports_enumerate()

bool ioports_enumerate ( io_port_type_t  type,
io_port_direction_t  dir,
pin_cap_t  filter,
ioports_enumerate_callback_ptr  callback,
void *  data 
)

Enumerate ports.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
filtera pin_cap_t union with fields set that must match the port capabilities.
callbackpointer to a ioports_enumerate_callback_ptr function that will be called for each matching port. If the function returns true the enumeration will end.
dataa pointer to context data passed to the callback function.

◆ ioports_map_reverse()

uint8_t ioports_map_reverse ( io_ports_detail_t type,
uint8_t  port 
)

◆ ioports_precompute_pwm_values()

bool ioports_precompute_pwm_values ( pwm_config_t config,
ioports_pwm_t pwm_data,
uint32_t  clock_hz 
)

Precompute PWM values for faster conversion.

Parameters
configpointer to a pwm_config_t structure.
pwm_datapointer to a ioports_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 control.

◆ ioports_unclaimed()

uint8_t ioports_unclaimed ( io_port_type_t  type,
io_port_direction_t  dir 
)

Get number of unclaimed digital or analog ports available.

Parameters
typeas an io_port_type_t enum value.
diras an io_port_direction_t enum value.
Returns
number of ports available.