Bringing back prior (and new) button long-press actions (+extended documentation)

[T0bi79]

This brings back prior (and adds new) features to the GPIO control module - especially different modes for long-press actions.

Long version:
This PR finally closes issue #1377 that was inadvertently already closed with my previous, preparatory PR #1397.

• The boolean button option "hold_repeat" was upgraded to a textual "hold_mode" with several options. This brings back postponed as well as secondary actions and introduces some new variants.
• I wrote an extensive component documentation for the GPIO module with many examples (previous one was way too short IMHO)
• I tested and optimized the ShutDown button class with the integrated LED support. For example, it had some timing options which were mostly ignored in favor of hardcoded values. Now the config values get effective.
• I also tested the TwoButtonControl class (with minor updates) and the LED class.
• Since I do not have a rotary encoder, I did neither test but also not touch the related code. (I just removed some lines from respective ini examples that are not evaluated by this component)
• Also, I added more available functions to the function_calls.py. This includes the new random track/folder playout commands added by my earlier PR Additional commands to play random cards/folders or tracks #1365.
• On my breadboards I encountered double/unwanted actions especially when releasing buttons, especially when they haven't just been tipped very shortly. Though I did not experience similar effects on older Phoniebox versions, such effects seem to be a well-known behavior of the GPIO library, as I found in the forums. I added a workaround which works fine for me, but left it disabled by default. It can be activated using a config file option described in the manual.

Even longer version:
See the single commit notes in my repo for some more (but less relevant) details ;-)

[s-martin]

Thank you for the PR and improving GPIO control!

Is the renaming of the parameters working in existing installations?
If not would it make sense to update the ini file, while reading it, if necessary?

[s-martin]

How does renaming these parameters work with existing installations, i.e. ini-files which use the old parameter names?

[T0bi79]

Hi @s-martin s-martin. See PR #1406 for my response.

[T0bi79]

Thank you for the PR and improving GPIO control!

Is the renaming of the parameters working in existing installations?
If not would it make sense to update the ini file, while reading it, if necessary?

Hi @s-martin!

My answer has two parts:

1. I already found the code with existing insonsistencies among all these ini files and how it is implemented/evaluated in the python scripts.
   Typical examples were pull_up_down (new scheme) vs. pull_up (old scheme), Pin1/Pin2 (new?) vs. PinUp/PinDown (old?), functionCallUp/Down (old?) vs. functionCall1/2 (new?). or enable(typo? found several times) vs. enabled.

   In your example, the ini file defines a control of type TwoButtonControl which defines the GPIOs as PinUp and PinDown and the actions as functionCallUp and functionCallDown. However, if gpio_control.py finds a control of Type TwoButtonControl it actually expects Pin1 / Pin2 and functionCall1 / functionCall2.

   The funny thing is that this particular ini entry actually still worked because gpio_control.py has a special treatment for TwoButtonControl if (and only if) the ini section is named "VolumeControl". In this case it actually did the same thing just by querying the old(?) names.
   But if the user would rename the ini section to something else (e.g. "Primary VolumeControl" or whatever) it would suddenly stop working and probably no user could understand why.

   My first tought was that all of these inconsistencies evolved unintentionally so I cleaned up / unified everything I found. Maybe the special treatment of entries named VolumeControl was somehow intentional for backward compatibility. In this case I somehow broke it ;-) This special treatment is actually still contained in my PR with the updated ini naming - but is more or less redundant now and could be removed. The only (remaining) difference is that TwoButtonControls named VolumeControl have the auto-repeat feature (old: hold_repeat, new: hold mode: Repeat") enabled by default / as fallback (which does not apply to the ini sample entry which defines auto-repeat itself).

2.) It might be a good idea to make a list or approach how old GPIO entries/parameters could be updated by automatic conversions. I consider this a good idea which is a cleaner style than some special constructs in the code (which even do not work for arbitrary entries but only for such with one reserved name). I'm quite confident that this will not be very complex. I'll think about it soon and post it here...

[T0bi79]

@s-martin

I just tested it and it is quite easy to add a new function that checks the ini file for deprecated syntax after loading it and upgrades it to the current format. This obviously works quite well. I could finish it (after testing it a bit further) and add it to my source branch so it will be added to this PR.

One question beforehand: I can integrate it in two ways:

• Option1: Once we patched the ConfigParser object, we save the updated gpio_settings.ini to disk.

  • Advantages: Patches become permanent, no need for further patching. Patching function could be removed after 2 or 3 years when little old configs will have survived in the field,
  • Disadvantages: All potential user comments and (upper, lower) case of the option keys will be lost. Though this is a readability/convenience issue only, this might annoy some users. However, we could make a gpio_settings.bak backup of the previous version so that nothing will be lost completely.

• Option 2: We apply the patches within the configparser object without saving it to disk.

  • Advantage: We don't touch the ini file and everthing will work correctly anyway.
  • Disadvantages: We have to invoke this function and repeat the patching at every startup (but this runs quickly). We encourage users to keep deprecated ini format so it will be less easy to remove this patcher after 2 or 3 years...

Which option is preferred?

[s-martin]

@T0bi79
I would go for option 1 with a bak file.

[T0bi79]

@s-martin : auto-correction feature is implemented :)