ESPHome 2026.11.0b6
Loading...
Searching...
No Matches
fingerprint_grow.cpp
Go to the documentation of this file.
1#include "fingerprint_grow.h"
2#include "esphome/core/gpio.h"
3#include "esphome/core/log.h"
5#include <cinttypes>
6
8
9ESPHOME_LOG_TAG(TAG, "fingerprint_grow");
10
11// Based on Adafruit's library: https://github.com/adafruit/Adafruit-Fingerprint-Sensor-Library
12
14 if (this->enrollment_image_ > this->enrollment_buffers_) {
15 this->finish_enrollment(this->save_fingerprint_());
16 return;
17 }
18
19 if (this->has_sensing_pin_) {
20 // A finger touch results in a low level (digital_read() == false)
21 if (this->sensing_pin_->digital_read()) {
22 ESP_LOGV(TAG, "No touch sensing");
23 this->waiting_removal_ = false;
24 if ((this->enrollment_image_ == 0) && // Not in enrolment process
26 this->sensor_sleep_();
27 }
28 return;
29 } else if (!this->waiting_removal_) {
30 this->finger_scan_start_callback_.call();
31 }
32 }
33
34 if (this->waiting_removal_) {
35 if ((!this->has_sensing_pin_) && (this->scan_image_(1) == NO_FINGER)) {
36 ESP_LOGD(TAG, "Finger removed");
37 this->waiting_removal_ = false;
38 }
39 return;
40 }
41
42 if (this->enrollment_image_ == 0) {
43 this->scan_and_match_();
44 return;
45 }
46
47 uint8_t result = this->scan_image_(this->enrollment_image_);
48 if (result == NO_FINGER) {
49 return;
50 }
51 this->waiting_removal_ = true;
52 if (result != OK) {
53 this->finish_enrollment(result);
54 return;
55 }
57 ++this->enrollment_image_;
58}
59
60void FingerprintGrowComponent::setup() {
61 this->has_sensing_pin_ = (this->sensing_pin_ != nullptr);
62 this->has_power_pin_ = (this->sensor_power_pin_ != nullptr);
63
64 // Call pins setup, so we effectively apply the config generated from the yaml file.
65 if (this->has_sensing_pin_) {
66 this->sensing_pin_->setup();
67 }
68 if (this->has_power_pin_) {
69 // Starts with output low (disabling power) to avoid glitches in the sensor
70 this->sensor_power_pin_->digital_write(false);
71 this->sensor_power_pin_->setup();
72
73 // If the user didn't specify an idle period to sleep, applies the default.
74 if (this->idle_period_to_sleep_ms_ == UINT32_MAX) {
75 this->idle_period_to_sleep_ms_ = DEFAULT_IDLE_PERIOD_TO_SLEEP_MS;
76 }
77 }
78
79 // Place the sensor in a known (sleep/off) state and sync internal var state.
80 this->sensor_sleep_();
81 delay(20); // This delay guarantees the sensor will in fact be powered power.
82
83 if (this->check_password_()) {
84 if (this->new_password_ != std::numeric_limits<uint32_t>::max()) {
85 if (this->set_password_())
86 return;
87 } else {
88 if (this->get_parameters_())
89 return;
90 }
91 }
92 this->mark_failed();
93}
94
95void FingerprintGrowComponent::enroll_fingerprint(uint16_t finger_id, uint8_t num_buffers) {
96 ESP_LOGI(TAG, "Starting enrollment in slot %d", finger_id);
97 PUBLISH_STATE(this->enrolling_binary_sensor_, true);
98 this->enrollment_slot_ = finger_id;
99 this->enrollment_buffers_ = num_buffers;
100 this->enrollment_image_ = 1;
101}
102
103void FingerprintGrowComponent::finish_enrollment(uint8_t result) {
104 if (result == OK) {
107 } else {
108 if (this->enrollment_slot_ != ENROLLMENT_SLOT_UNUSED) {
110 }
111 }
112 this->enrollment_image_ = 0;
113 this->enrollment_slot_ = ENROLLMENT_SLOT_UNUSED;
114 PUBLISH_STATE(this->enrolling_binary_sensor_, false);
115 ESP_LOGI(TAG, "Finished enrollment");
116}
117
119 if (this->has_sensing_pin_) {
120 ESP_LOGD(TAG, "Scan and match");
121 } else {
122 ESP_LOGV(TAG, "Scan and match");
123 }
124 if (this->scan_image_(1) == OK) {
125 this->waiting_removal_ = true;
126 this->data_ = {SEARCH, 0x01, 0x00, 0x00, (uint8_t) (this->capacity_ >> 8), (uint8_t) (this->capacity_ & 0xFF)};
127 switch (this->send_command_()) {
128 case OK: {
129 ESP_LOGD(TAG, "Fingerprint matched");
130 uint16_t finger_id = encode_uint16(this->data_[1], this->data_[2]);
131 uint16_t confidence = encode_uint16(this->data_[3], this->data_[4]);
132 PUBLISH_STATE(this->last_finger_id_sensor_, finger_id);
133 PUBLISH_STATE(this->last_confidence_sensor_, confidence);
134 this->finger_scan_matched_callback_.call(finger_id, confidence);
135 break;
136 }
137 case NOT_FOUND:
138 ESP_LOGD(TAG, "Fingerprint not matched to any saved slots");
140 break;
141 }
142 }
143}
144
146 if (this->has_sensing_pin_) {
147 ESP_LOGD(TAG, "Getting image %d", buffer);
148 } else {
149 ESP_LOGV(TAG, "Getting image %d", buffer);
150 }
151 this->data_ = {GET_IMAGE};
152 uint8_t send_result = this->send_command_();
153 switch (send_result) {
154 case OK:
155 break;
156 case NO_FINGER:
157 if (this->has_sensing_pin_) {
158 this->waiting_removal_ = true;
159 ESP_LOGD(TAG, "Finger Misplaced");
161 } else {
162 ESP_LOGV(TAG, "No finger");
163 }
164 return send_result;
165 case IMAGE_FAIL:
166 ESP_LOGE(TAG, "Imaging error");
168 return send_result;
169 default:
170 ESP_LOGD(TAG, "Unknown Scan Error: %d", send_result);
171 return send_result;
172 }
173
174 ESP_LOGD(TAG, "Processing image %d", buffer);
175 this->data_ = {IMAGE_2_TZ, buffer};
176 send_result = this->send_command_();
177 switch (send_result) {
178 case OK:
179 ESP_LOGI(TAG, "Processed image %d", buffer);
180 break;
181 case IMAGE_MESS:
182 ESP_LOGE(TAG, "Image too messy");
184 break;
185 case FEATURE_FAIL:
186 case INVALID_IMAGE:
187 ESP_LOGE(TAG, "Could not find fingerprint features");
189 break;
190 default:
191 break;
192 }
193 return send_result;
194}
195
197 ESP_LOGI(TAG, "Creating model");
198 this->data_ = {REG_MODEL};
199 switch (this->send_command_()) {
200 case OK:
201 break;
202 case ENROLL_MISMATCH:
203 ESP_LOGE(TAG, "Scans do not match");
204 [[fallthrough]];
205 default:
206 return this->data_[0];
207 }
208
209 ESP_LOGI(TAG, "Storing model");
210 this->data_ = {STORE, 0x01, (uint8_t) (this->enrollment_slot_ >> 8), (uint8_t) (this->enrollment_slot_ & 0xFF)};
211 switch (this->send_command_()) {
212 case OK:
213 ESP_LOGI(TAG, "Stored model");
214 break;
215 case BAD_LOCATION:
216 ESP_LOGE(TAG, "Invalid slot");
217 break;
218 case FLASH_ERR:
219 ESP_LOGE(TAG, "Error writing to flash");
220 break;
221 }
222 return this->data_[0];
223}
224
226 ESP_LOGD(TAG, "Checking password");
227 this->data_ = {VERIFY_PASSWORD, (uint8_t) (this->password_ >> 24), (uint8_t) (this->password_ >> 16),
228 (uint8_t) (this->password_ >> 8), (uint8_t) (this->password_ & 0xFF)};
229 switch (this->send_command_()) {
230 case OK:
231 ESP_LOGD(TAG, "Password verified");
232 return true;
233 case PASSWORD_FAIL:
234 ESP_LOGE(TAG, "Wrong password");
235 break;
236 }
237 return false;
238}
239
241 ESP_LOGI(TAG, "Setting new password: %" PRIu32, this->new_password_);
242 this->data_ = {SET_PASSWORD, (uint8_t) (this->new_password_ >> 24), (uint8_t) (this->new_password_ >> 16),
243 (uint8_t) (this->new_password_ >> 8), (uint8_t) (this->new_password_ & 0xFF)};
244 if (this->send_command_() == OK) {
245 ESP_LOGI(TAG, "New password successfully set");
246 ESP_LOGI(TAG, "Define the new password in your configuration and reflash now");
247 ESP_LOGW(TAG, "!!!Forgetting the password will render your device unusable!!!");
248 return true;
249 }
250 return false;
251}
252
254 ESP_LOGD(TAG, "Getting parameters");
255 this->data_ = {READ_SYS_PARAM};
256 if (this->send_command_() == OK) {
257 ESP_LOGD(TAG, "Got parameters");
258 // Bear in mind data_[0] is the transfer status, the parameters table start at data_[1]
259 PUBLISH_STATE(this->status_sensor_, encode_uint16(this->data_[1], this->data_[2]));
260 this->system_identifier_code_ = encode_uint16(this->data_[3], this->data_[4]);
261 this->capacity_ = encode_uint16(this->data_[5], this->data_[6]);
262 PUBLISH_STATE(this->capacity_sensor_, this->capacity_);
263 PUBLISH_STATE(this->security_level_sensor_, encode_uint16(this->data_[7], this->data_[8]));
264 PUBLISH_STATE(this->enrolling_binary_sensor_, false);
266 return true;
267 }
268 return false;
269}
270
272 ESP_LOGD(TAG, "Getting fingerprint count");
273 this->data_ = {TEMPLATE_COUNT};
274 if (this->send_command_() == OK) {
275 ESP_LOGD(TAG, "Got fingerprint count");
276 PUBLISH_STATE(this->fingerprint_count_sensor_, encode_uint16(this->data_[1], this->data_[2]));
277 }
278}
279
280void FingerprintGrowComponent::delete_fingerprint(uint16_t finger_id) {
281 ESP_LOGI(TAG, "Deleting fingerprint in slot %d", finger_id);
282 this->data_ = {DELETE, (uint8_t) (finger_id >> 8), (uint8_t) (finger_id & 0xFF), 0x00, 0x01};
283 switch (this->send_command_()) {
284 case OK:
285 ESP_LOGI(TAG, "Deleted fingerprint");
287 break;
288 case DELETE_FAIL:
289 ESP_LOGE(TAG, "Reader failed to delete fingerprint");
290 break;
291 }
292}
293
294void FingerprintGrowComponent::delete_all_fingerprints() {
295 ESP_LOGI(TAG, "Deleting all stored fingerprints");
296 this->data_ = {DELETE_ALL};
297 switch (this->send_command_()) {
298 case OK:
299 ESP_LOGI(TAG, "Deleted all fingerprints");
301 break;
302 case DB_CLEAR_FAIL:
303 ESP_LOGE(TAG, "Reader failed to clear fingerprint library");
304 break;
305 }
306}
307
308void FingerprintGrowComponent::led_control(bool state) {
309 ESP_LOGD(TAG, "Setting LED");
310 if (state) {
311 this->data_ = {LED_ON};
312 } else {
313 this->data_ = {LED_OFF};
314 }
315 switch (this->send_command_()) {
316 case OK:
317 ESP_LOGD(TAG, "LED set");
318 break;
319 case PACKET_RCV_ERR:
320 case TIMEOUT:
321 break;
322 default:
323 ESP_LOGE(TAG, "Try aura_led_control instead");
324 break;
325 }
326}
327
328void FingerprintGrowComponent::aura_led_control(uint8_t state, uint8_t speed, uint8_t color, uint8_t count) {
329 const uint32_t now = millis();
330 const uint32_t elapsed = now - this->last_aura_led_control_;
331 if (elapsed < this->last_aura_led_duration_) {
332 delay(this->last_aura_led_duration_ - elapsed);
333 }
334 ESP_LOGD(TAG, "Setting Aura LED");
335 this->data_ = {AURA_CONFIG, state, speed, color, count};
336 switch (this->send_command_()) {
337 case OK:
338 ESP_LOGD(TAG, "Aura LED set");
339 this->last_aura_led_control_ = millis();
340 this->last_aura_led_duration_ = 10 * speed * count;
341 break;
342 case PACKET_RCV_ERR:
343 case TIMEOUT:
344 break;
345 default:
346 ESP_LOGE(TAG, "Try led_control instead");
347 break;
348 }
349}
350
351uint8_t FingerprintGrowComponent::transfer_(std::vector<uint8_t> &data_buffer) {
352 this->discard_available();
353 this->write((uint8_t) (START_CODE >> 8));
354 this->write((uint8_t) (START_CODE & 0xFF));
355 this->write(this->address_[0]);
356 this->write(this->address_[1]);
357 this->write(this->address_[2]);
358 this->write(this->address_[3]);
359 this->write(COMMAND);
360
361 uint16_t wire_length = data_buffer.size() + 2;
362 this->write((uint8_t) (wire_length >> 8));
363 this->write((uint8_t) (wire_length & 0xFF));
364
365 uint16_t sum = (wire_length >> 8) + (wire_length & 0xFF) + COMMAND;
366 for (auto data : data_buffer) {
367 this->write(data);
368 sum += data;
369 }
370
371 this->write((uint8_t) (sum >> 8));
372 this->write((uint8_t) (sum & 0xFF));
373
374 data_buffer.clear();
375
376 uint8_t byte;
377 uint16_t idx = 0, length = 0;
378
379 for (uint16_t timer = 0; timer < 1000; timer++) {
380 if (this->available() == 0) {
381 delay(1);
382 continue;
383 }
384
385 byte = this->read();
386
387 switch (idx) {
388 case 0:
389 if (byte != (uint8_t) (START_CODE >> 8))
390 continue;
391 break;
392 case 1:
393 if (byte != (uint8_t) (START_CODE & 0xFF)) {
394 idx = 0;
395 continue;
396 }
397 break;
398 case 2:
399 case 3:
400 case 4:
401 case 5:
402 if (byte != this->address_[idx - 2]) {
403 idx = 0;
404 continue;
405 }
406 break;
407 case 6:
408 if (byte != ACK) {
409 idx = 0;
410 continue;
411 }
412 break;
413 case 7:
414 length = (uint16_t) byte << 8;
415 break;
416 case 8:
417 length |= byte;
418 break;
419 default:
420 data_buffer.push_back(byte);
421 if ((idx - 8) == length) {
422 switch (data_buffer[0]) {
423 case OK:
424 case NO_FINGER:
425 case IMAGE_FAIL:
426 case IMAGE_MESS:
427 case FEATURE_FAIL:
428 case NO_MATCH:
429 case NOT_FOUND:
430 case ENROLL_MISMATCH:
431 case BAD_LOCATION:
432 case DELETE_FAIL:
433 case DB_CLEAR_FAIL:
434 case PASSWORD_FAIL:
435 case INVALID_IMAGE:
436 case FLASH_ERR:
437 break;
438 case PACKET_RCV_ERR:
439 ESP_LOGE(TAG, "Reader failed to process request");
440 break;
441 default:
442 ESP_LOGE(TAG, "Unknown response received from reader: 0x%.2X", data_buffer[0]);
443 break;
444 }
445 this->last_transfer_ms_ = millis();
446 return data_buffer[0];
447 }
448 break;
449 }
450 idx++;
451 }
452 ESP_LOGE(TAG, "No response received from reader");
453 data_buffer.clear();
454 data_buffer.push_back(TIMEOUT);
455 this->last_transfer_ms_ = millis();
456 return TIMEOUT;
457}
458
460 this->sensor_wakeup_();
461 return this->transfer_(this->data_);
462}
463
465 // Immediately return if there is no power pin or the sensor is already on
466 if ((!this->has_power_pin_) || (this->is_sensor_awake_))
467 return;
468
469 this->sensor_power_pin_->digital_write(true);
470 this->is_sensor_awake_ = true;
471
472 uint8_t byte = TIMEOUT;
473
474 // Wait for the byte HANDSHAKE_SIGN from the sensor meaning it is operational.
475 for (uint16_t timer = 0; timer < WAIT_FOR_WAKE_UP_MS; timer++) {
476 if (this->available() > 0) {
477 byte = this->read();
478
479 /* If the received byte is zero, the UART probably misinterpreted a raising edge on
480 * the RX pin due the power up as byte "zero" - I verified this behaviour using
481 * the esp32-arduino lib. So here we just ignore this fake byte.
482 */
483 if (byte != 0)
484 break;
485 }
486 delay(1);
487 }
488
489 /* Lets check if the received by is a HANDSHAKE_SIGN, otherwise log an error
490 * message and try to continue on the best effort.
491 */
492 if (byte == HANDSHAKE_SIGN) {
493 ESP_LOGD(TAG, "Sensor has woken up!");
494 } else if (byte == TIMEOUT) {
495 ESP_LOGE(TAG, "Timed out waiting for sensor wake-up");
496 } else {
497 ESP_LOGE(TAG, "Received wrong byte from the sensor during wake-up: 0x%.2X", byte);
498 }
499
500 /* Next step, we must authenticate with the password. We cannot call check_password_ here
501 * neither use data_ to store the command because it might be already in use by the caller
502 * of send_command_()
503 */
504 std::vector<uint8_t> buffer = {VERIFY_PASSWORD, (uint8_t) (this->password_ >> 24), (uint8_t) (this->password_ >> 16),
505 (uint8_t) (this->password_ >> 8), (uint8_t) (this->password_ & 0xFF)};
506
507 if (this->transfer_(buffer) != OK) {
508 ESP_LOGE(TAG, "Wrong password");
509 }
510}
511
513 // Immediately return if the power pin feature is not implemented
514 if (!this->has_power_pin_)
515 return;
516
517 this->sensor_power_pin_->digital_write(false);
518 this->is_sensor_awake_ = false;
519 ESP_LOGD(TAG, "Fingerprint sensor is now in sleep mode.");
520}
521
522void FingerprintGrowComponent::dump_config() {
523 char sensing_pin_buf[GPIO_SUMMARY_MAX_LEN];
524 char power_pin_buf[GPIO_SUMMARY_MAX_LEN];
525 if (this->has_sensing_pin_) {
526 this->sensing_pin_->dump_summary(sensing_pin_buf, sizeof(sensing_pin_buf));
527 }
528 if (this->has_power_pin_) {
529 this->sensor_power_pin_->dump_summary(power_pin_buf, sizeof(power_pin_buf));
530 }
531 ESP_LOGCONFIG(TAG,
532 "GROW_FINGERPRINT_READER:\n"
533 " System Identifier Code: 0x%.4X\n"
534 " Touch Sensing Pin: %s\n"
535 " Sensor Power Pin: %s",
536 this->system_identifier_code_, this->has_sensing_pin_ ? sensing_pin_buf : LOG_STR_LITERAL("None"),
537 this->has_power_pin_ ? power_pin_buf : LOG_STR_LITERAL("None"));
538 if (this->idle_period_to_sleep_ms_ < UINT32_MAX) {
539 ESP_LOGCONFIG(TAG, " Idle Period to Sleep: %" PRIu32 " ms", this->idle_period_to_sleep_ms_);
540 } else {
541 ESP_LOGCONFIG(TAG, " Idle Period to Sleep: Never");
542 }
543 LOG_UPDATE_INTERVAL(this);
544 if (this->fingerprint_count_sensor_) {
545 LOG_SENSOR(" ", "Fingerprint Count", this->fingerprint_count_sensor_);
546 ESP_LOGCONFIG(TAG, " Current Value: %u", (uint16_t) this->fingerprint_count_sensor_->get_state());
547 }
548 if (this->status_sensor_) {
549 LOG_SENSOR(" ", "Status", this->status_sensor_);
550 ESP_LOGCONFIG(TAG, " Current Value: %u", (uint8_t) this->status_sensor_->get_state());
551 }
552 if (this->capacity_sensor_) {
553 LOG_SENSOR(" ", "Capacity", this->capacity_sensor_);
554 ESP_LOGCONFIG(TAG, " Current Value: %u", (uint16_t) this->capacity_sensor_->get_state());
555 }
556 if (this->security_level_sensor_) {
557 LOG_SENSOR(" ", "Security Level", this->security_level_sensor_);
558 ESP_LOGCONFIG(TAG, " Current Value: %u", (uint8_t) this->security_level_sensor_->get_state());
559 }
560 if (this->last_finger_id_sensor_) {
561 LOG_SENSOR(" ", "Last Finger ID", this->last_finger_id_sensor_);
562 ESP_LOGCONFIG(TAG, " Current Value: %" PRIu32, (uint32_t) this->last_finger_id_sensor_->get_state());
563 }
564 if (this->last_confidence_sensor_) {
565 LOG_SENSOR(" ", "Last Confidence", this->last_confidence_sensor_);
566 ESP_LOGCONFIG(TAG, " Current Value: %" PRIu32, (uint32_t) this->last_confidence_sensor_->get_state());
567 }
568}
569
570} // namespace esphome::fingerprint_grow
void mark_failed()
Mark this component as failed.
virtual void setup()=0
virtual void digital_write(bool value)=0
virtual bool digital_read()=0
virtual size_t dump_summary(char *buffer, size_t len) const
Write a summary of this pin to the provided buffer.
Definition gpio_pin.h:126
virtual void update()=0
CallbackManager< void(uint16_t, uint16_t)> finger_scan_matched_callback_
uint8_t transfer_(std::vector< uint8_t > &data_buffer)
CallbackManager< void(uint16_t)> enrollment_done_callback_
CallbackManager< void(uint16_t)> enrollment_failed_callback_
CallbackManager< void(uint8_t, uint16_t)> enrollment_scan_callback_
void discard_available()
Read and drop every byte waiting in the receive buffer.
Definition uart.cpp:36
size_t write(uint8_t data)
Definition uart.h:105
int speed
Definition fan.h:3
bool state
Definition fan.h:2
unsigned count
Definition gif.cpp:51
uint32_t buffer
Definition gif.cpp:50
ESPHOME_LOG_TAG(TAG, "fingerprint_grow")
constexpr uint16_t encode_uint16(uint8_t msb, uint8_t lsb)
Encode a 16-bit value given the most and least significant byte.
Definition helpers.h:1043
constexpr size_t GPIO_SUMMARY_MAX_LEN
Maximum buffer size for dump_summary output.
Definition gpio_pin.h:14
void HOT delay(uint32_t ms)
Definition hal.cpp:85
uint32_t IRAM_ATTR HOT millis()
Definition hal.cpp:25
static void uint32_t