grblHAL plugins

grblHAL's HAL interface is based on function pointers that may be used to add functionality without any need to change the core grbl code. They may also be changed on the fly to redirect calls, eg. the SD-card interface utilizes this to temporarily redirect input from the serial stream to the SD card.

NOTE: A plugin needs to be supported by the processor specific driver - as a minimum a initialization call has to be made.

• EEPROM - for non-volatile storage of settings/data on an external EEPROM or FRAM.

• Encoder - for adjusting overrides¹. Support for jogging is planned.

• Keypad - for I2C based keypad¹. Support for jogging etc. This is an example of an implementation.

• Networking - for telnet or websocket communication plus a number of other networking protocols².

• Odometer - for logging of distances travelled and machining time. NOTE: For review.

• Plasma/THC - for plasma machines¹. NOTE: Under development, testers wanted.

• SD card - for executing gcode stored on SD card and running macros from the card or in the littlefs finling system when available.

• Spindle - for spindles controlled via MODBUS. NOTE: Not yet verified, testers wanted.

• Trinamic - for Trinamic TMC2130, TMC2209 and TMC5160 stepper drivers controlled via SPI, UART or I2C¹.

• Laser/PPI - for laser machines. NOTE: Under development, testers wanted.

• Laser/Coolant - for laser machines. NOTE: Under development, testers wanted.

• Laser/LigthBurn clusters - for laser machines. NOTE: Under development, testers wanted.

• Fans - for fan control.

• Bluetooth - for Bluetooth modules used for wireless communication¹. NOTE: Preview version.

• WebUI - adds ESP32-WEBUI support for some networking capable boards and drivers.

• Embroidery - adds functionality for streaming Brother .PES and Tajima .DST format files from SD card¹. NOTE: Under development, testers wanted.

• Miscellaneous - assorted small and useful plugins, follow the link to see which.

Third party plugins

• 'Datron like' RGB indicator lights - by 5ocworkshop.
• Add status of digital aux outputs to real-time report - by Avatario34.

Example and template plugins

A number of example and template plugins can be found here. Some are usable 'as-is', some not.

NOTE: The ESP32 and RP2040 drivers require the AddMyPlugin option to be set to ON in CMakeLists.txt to enable compilation of _myplugin.c.

I have written a plugin and I want to make it available to grblHAL users

Pull requests for the plugin code itself is not possible as a new repository has to be created and linked to the different drivers by adding it as a submodule. You will have to add it to your own github repository and create pull request(s) against the core.

Plugin name:

A plugin has to be given an "official" name so that it can be enabled and added to the startup sequence.
A #define symbol <NAME>_ENABLE and a corresponding function void <name>_init(void) is required, <NAME> and <name> is the upper and lower case name of your plugin.
To add a call to the init function at startup it has to be added to plugins_init.h in the Third party plugin section. Create a pull request for plugins_init.h to get it added.
An example:

#if PROBE_RELAY_ENABLE
    extern void probe_relay_init (void);
    probe_relay_init();
#endif

To install the plugin the user has to download the code from your repo and copy it to the folder where driver.c is located and add #define symbol <NAME>_ENABLE 1 somewhere in the drivers _mymachine.h file.

Addional M-codes:

If your plugin provides additional M-codes these should be documented in the repo readme and the plugin code. A pull request for getting them added to gcode.h might be accepted, more likely so if similar in function to those defined by Marlin.
It is also kind of ok to just cast the enum value in the code, however there is a slight risk that it could clash with other plugins - but not too high if similar to those in the Marlin list.

Additional $-settings:

Setting numbers for your plugin has to be added to settings.h to avoid clashes. If any is needed start a discussion first as I do not yet have a clear idea about how this should be handled, I guess it should be possible to use non-core settings in some cases.

Notes:
The symbol definition may be added to the compiler command line instead, some IDEs allows this from the UI.
There is no owner of third party plugin names, existing names can be used for alternative implementations as long as they provide similar functionality.
Implementations should add information about itself in the $I report, see one of the templates for how this is done.

¹ Plugin has $-settings, adding or removing it may cause settings for other plugins to be reset to default values.
² Driver support code has $-settings, adding or removing this may cause settings for other plugins to be reset to default values.

2024-11-13