[alexbn71]

[P190] Security - Fingerprint (Grow R503/R307)

New plugin for the Grow fingerprint modules on a serial port: R503 (with RGB LED ring), R307, R502, ZFM-20, AS608 and compatibles. Plugin ID 190 as reserved in #3839 (see #5670).

Resolves #5670

Features

• Recognises a finger and sends its slot ID and score to controllers and rules (<task>#ID, -1 = not recognised)
• Enrol / delete / count / list fingers with commands; fingerprint,enroll without ID uses the first free slot
• Enrolment progress as task value and events; JSON answers for fingerprint,list and fingerprint,enroll over HTTP
• R503 LED ring feedback and fingerprint,led command
• Touch detection on the WAKEUP pin, or polling
• Non-blocking state machine, uses the ESPEasy serial helper
• Device page shows the module state and the used templates (via TaskValuesWriterHelper)

Changes

• src/_P190_Fingerprint.ino, src/src/PluginStructs/P190_*
• define_plugin_sets.h: added to PLUGIN_SET_MAX (ESP32 only) and to the PLUGIN_USES_SERIAL list; Custom-sample.h entry
• Documentation: P190.rst, commands and events (also included in the Command and Events reference), plugin list, _plugin_substitutions_p19x.repl, MAX build set overview

Testing

• Builds with a minimal custom build (custom_ESP32_4M316k) against the current mega
• Hardware: ESP32 with an R503 clone on HW Serial2 at 57600 baud, firmware built from mega-20260720 with this plugin (P190): recognition, enrolment at the first free slot and at a given slot, fingerprint,list, fingerprint,delete, fingerprint,led and the automatic LED ring feedback. Not tested on hardware: fingerprint,deleteall.
• Documentation builds with Sphinx without new warnings.

Notes / questions

• Category: new Security category in _plugin_categories.repl and _Plugin.rst (as suggested in the review).
• Build sets: only MAX for now. Let me know if it should go into a COLLECTION set as well.
• The code was written with the help of an AI assistant (Claude), then built, tested on hardware and reviewed by me.

[tonhuisman]

Great, I'll have a look at the code asap.
One thing that makes developers life on GH easier is coupling this PR to the issue, so the issue will auto-close on merge, by adding a line in the opening message with Resolves #5670 👍

[alexbn71]

Done, thanks! The PR now resolves #5670.

[tonhuisman]

There is one thing missing still, but it's not very obvious: Source formatting. (It's mentioned in the developer documentation though)
We use Uncrustify for (C++) source formatting. and that involves installing an extra tool, uncrustify, either on Windows, Mac or Linux/WSL. And setting it as the default formatting tool in VSCode (should work also in VSCode-derived AI harnesses like Cursor, Codex, etc.).
When configured correctly, it will add quite some formatting changes. Formatting can be done in VSCode by using the standard shortcut <Alt>-<Shift>-F

[alexbn71]

Thanks for the hint! I installed Uncrustify (0.79) and formatted the sources with the repository uncrustify.cfg in f99f6bc. A few one-line loops and case statements were rewritten so the formatted code stays readable.

[tonhuisman]

A request to keep stuff a bit organized: Can you resolve the comments that you've resolved/fixed/improved/etc.?

[alexbn71]

Sure, done: I resolved the threads that are fixed. The one about the minimum score is still open, as there I only partly followed your suggestion (see my reply there), so I leave that to you.

[tonhuisman]

There are a few features that aren't available in the plugin, not sure if you have planned to add them, as they can be a bit tricky, or even risky, to implement, so don't start Claude yet 😃 but let's first discuss this:

• Setting a different baud rate for the sensor
• Changing the module address
• Changing the password (and handling the required verify)

The baud rate and module address aren't that hard to implement, and they should also properly take care of updating the settings.
Changing the module address will allow to use multiple sensor on the same serial port, as long as they use the same serial settings.
Changing the password must be handled rather carefully, as it requires the password to be verified, and can cause the sensor to be bricked if you lose that password. And bricking could also happen if you lose the changed module address.

NB: There parameters are stored in flash memory in the sensor, and there is no way to do a factory reset on the sensor, so only a lucky guess or a brute-force trial and error, until the correct module address or password is found, can revive it.

These changes to the sensor configuration can also be set from an external application (Windows or mobile-app only, AFAICS), but come with the same risks, and should then also be updated in the plugin configuration.

[alexbn71]

Thanks for raising this, I hadn't planned them for this first version, on purpose:

• Baud rate: the safest of the three, as a mismatch can be recovered by trying the 5 possible rates. I'd add it in a follow-up PR, together with an automatic baud detection at init, so a module set to another rate (e.g. by the vendor app) is still found.
• Address and password: as you say, losing either one bricks the module, so I'd rather not offer them from the web UI for now. They can be set with the vendor tools, and the plugin already has the matching Password and Address settings. I'll make the docs clearer about that, including the risk.
• Multiple sensors on one serial port: with a plain UART the TX outputs of the modules would drive the same line, so it would need extra hardware (diodes / open drain), I don't think it's a common use case.

If you prefer to have any of them in this PR, let me know.

Docs updated in 51f76a1: the plugin settings say that baud rate, password and address must match the module and are not changed by the plugin, plus a warning about losing the password or address.