RFC: Bind aux pin by port number in plugins

[terjeio]

I have been trying to find a solution to this conundrum and have come up with two alternative solutions.

Claim the pin by port number:

The main issue is to convey which port is used for what without making it complicated for the end user.
The aux pins gets a default label such as Aux out 0, this is bound to the physical pin by a entry in the board map file.
For the M62-M66 commands the aux number (port) is the P parameter used to interact with the pin. If a port is claimed explicitly by port number this no longer true (unless it is the highest numbered port) leading to a "hole" in the P parameters available. Handling that in the gcode parser is not straightforward so I needed to come up with a better solution that avoids generating "holes" and is backwards compatible with the current method¹.

My solution is to add a new call to the hal.port struct for claiming a port. This moves the port outside the available (for M-codes) ports range via a simple remapping table. Since this breaks the mapping of the P parameter to the Aux number I decided to add the P parameter value to the $pins report. An example:

uint8_t port1 = 1, port2 = 3;

hal.port.claim(Port_Digital, Port_Output, &port2, "Claimed port3");
hal.port.claim(Port_Digital, Port_Output, &port1, "Claimed port1");

$pins output:

[PIN:PB15,Aux out 0,P0]
[PIN:PB2,Aux out 1,Claimed port1]
[PIN:PA5,Aux out 2,P1]
[PIN:PA6,Aux out 3,Claimed port3]
[PIN:PA7,Aux out 4,P2]

With proper PCB labeling this should make it clear which port/pin is used for what, either available for M-commands and which P parameter value to use or claimed by a plugin.

Pin swapping:

This just swaps the port to pin binding between two ports. If the ports are inputs and a plugin has registered an interrupt handler for one of them they cannot be swapped. An example:

hal.port.swap_pins(Port_Digital, Port_Output, 0, 1);

I am not sure this method is needed. The first method cover the needs?

---

It can be mentioned that there is an optional entry point in the hal.port struct that can be used to request details about a given port. E.g. an input port can be checked for interrupt capabilities.

---

¹ The current method is simply claiming ports by assigning from and decrementing number of available ports.

[willtel]

*Hi Terje,* *I am no expert, but **I am looking at using STM32 – Nucleo-144 Boards which would **e**liminate the **n**umber of **a**vailable pins for a particular project (CNC, Laser, PnP etc)* *BUT how to allocate the Port/Pins is a problem.* *Thus I think your **solution “**Claim the pin by port number:” **is a Good Solution**, and would * *open up grblHAL for any type of project without limitations.*

…

On Fri, Nov 12, 2021 at 7:32 AM Terje Io ***@***.***> wrote: I have been trying to find a solution to this conundrum and have come up with two alternative solutions. *Claim the pin by port number:* The main issue is to convey which port is used for what without making it complicated for the end user. The aux pins gets a default label such as *Aux out 0*, this is bound to the physical pin by a entry in the board map file. For the M62-M66 <http://www.linuxcnc.org/docs/html/gcode/m-code.html#mcode:m62-m65> commands the aux number (port) is the P parameter used to interact with the pin. If a port is claimed explicitly by port number this no longer true (unless it is the highest numbered port) leading to a "hole" in the P parameters available. Handling that in the gcode parser is not straightforward so I needed to come up with a better solution that avoids generating "holes" and is backwards compatible with the current method1. My solution is to add a new call to the hal.port struct <http://svn.io-engineering.com/grblHAL/html/structio__port__t.html> for claiming a port. This moves the port outside the available (for M-codes) ports range via a simple remapping table. Since this breaks the mapping of the P parameter to the Aux number I decided to add the P parameter value to the $pins report. An example: uint8_t port1 = 1, port2 = 3; hal.port.claim(Port_Digital, Port_Output, &port2, "Claimed port3"); hal.port.claim(Port_Digital, Port_Output, &port1, "Claimed port1"); $pins output: [PIN:PB15,Aux out 0,P0] [PIN:PB2,Aux out 1,Claimed port1] [PIN:PA5,Aux out 2,P1] [PIN:PA6,Aux out 3,Claimed port3] [PIN:PA7,Aux out 4,P2] With proper PCB labeling this should make it clear which port/pin is used for what, either available for M-commands and which P parameter value to use or claimed by a plugin. *Pin swapping:* This just swaps the port to pin binding between two ports. If the ports are inputs and a plugin has registered an interrupt handler for one of them they cannot be swapped. An example: hal.port.swap_pins(Port_Digital, Port_Output, 0, 1); I am not sure this method is needed. The first method cover the needs? ------------------------------ It can be mentioned that there is an optional entry point in the hal.port struct that can be used to request details about a given port. E.g. an input port can be checked for interrupt capabilities. ------------------------------ 1 The current method is simply claiming ports by assigning from and decrementing number of available ports. — You are receiving this because you are subscribed to this thread. Reply to this email directly, view it on GitHub <#83>, or unsubscribe <https://github.com/notifications/unsubscribe-auth/AC5DYJZOG2W5R7ZLGOKFGCDULQZALANCNFSM5H3MVIYA> . Triage notifications on the go with GitHub Mobile for iOS <https://apps.apple.com/app/apple-store/id1477376905?ct=notification-email&mt=8&pt=524675> or Android <https://play.google.com/store/apps/details?id=com.github.android&referrer=utm_campaign%3Dnotification-email%26utm_medium%3Demail%26utm_source%3Dgithub>.

[5ocworkshop]

Terje,

I had not fully appreciated that you had established the pin to M-code relationship, now some of the previous discussion makes more sense to me.

I like your suggested approach of having them explicitly mapped and viewable by $pins. It makes sense to remove the pins used for non m-code functions from the list, even if it means a bit more lookup/labeling work for a given board. It is logical, documented and available from the grblHAL console when the machine is up.

I also prefer the approach of claiming a specific port as I could never quite get my head around asking for the "next available" port when there was physical wiring involved. It does mean there is a bit of a chicken and egg situation to first set things up, but that is true in general with wiring anything. As long as we document how to identify and claim available ports, it should be fine.

[terjeio]

@willtel Be aware that the mapping I am discussing here is not from physical pin numbers to the auxillary pin numbers (such as PB15 to Aux out 0 in the example above) . That mapping is taken care of by the driver code and is similar to how the Arduino framwork does it. It is about how to handle mapping from the auxillary pin numbers to the port numbers used by M62-M66 when plugins claims pins (from the pool of auxillary pins).

I had not fully appreciated that you had established the pin to M-code relationship

The ioports interface/API implementation was started with that in mind, use from plugins came after that.

It does mean there is a bit of a chicken and egg situation to first set things up, but that is true in general with wiring anything. As long as we document how to identify and claim available ports, it should be fine.

Whet is important to keep in mind is that generic plugins should not be limited to a particular driver or board if the needed resources are available. There could also be more than one plugin competing for the same resources...

Then there is the startup sequence, the plugin init function is called before the settings are loaded so pins cannot be claimed there if mapping is required. If a plugin provides its own setting(s) for mapping this is not neccesarily a problem as the plugin has to load them from storage anyway, pin claiming can then be done in the load function.

However, if there are more than one plugin claiming pins or your plugin wants more than one then it gets a bit complicated. Since the port numbers gets remapped and the claimed ports hidden and claiming is done by port number claiming has either to be done in descending port order or by using the aux number. Using the aux number is IMO the best method. To find that one has to loop through the available ports and call hal.port.get_pin_info() for each to check if it exists and is still available.

@5ocworkshop I guess I/we have to come up with some example/template code for how remapping (and fault handling) could be done, perhaps using your status lights code as a basis. What do you think?

Here is a trivial example from the updated Blueetooth plugin where an input port supporting change interrupt is required:

        state_port = hal.port.num_digital_in;

        // Claim first free aux input pin that supports change interrupt for STATE signal
        do {
            state_port--;
            port = hal.port.get_pin_info(Port_Digital, Port_Input, state_port);
            if((ok = port && (port->cap.irq_mode & IRQ_Mode_Change))) {
                hal.port.claim(Port_Digital, Port_Input, &state_port, "HC-05 STATE");
                break;
            }
        } while(state_port);

Note that a pointer to the state_port variable is passed to the claim function since claiming changes the port number, the changed port number has to be used for subsequent interactions with the API.

[terjeio]

I have modified the probe plugin template as an example for how a setting for selecting a pin can be implemented, see the attached file.

It is also an example of how ioSender uses data from the controller to present the new setting:

my_plugin.zip

Note the plugin uses HAL entry points that are not available in the current build (20211109) so it will not compile.

[terjeio]

I have added some wrapper functions to make it easier to write plugin code. These are called directly, not via HAL pointers.

[terjeio]

The probe relay plugin has now been updated to use the new wrapper functions if the core version supports them.