ESP32C6 with a Grow R503 fingerprint sensor

[Ma1ch]

I am trying to have the Grow R503 fingerprint sensor as a Zigbee end device, but having a hard time understanding how to do this in practice. The end goal is to have the R503 fingerprint sensor show up as a zigbee device in home assistant, and be able to trigger different automations depending on which finger is scanned on the fingerprint sensor. It is already working with esphome through wifi, but this is not as stable as zigbee.

This is the code I have gotten so far with chatgpt and previous experience (which is not much). This is the documentation for the R503: https://download.mikroe.com/documents/datasheets/R503_datasheet.pdf

Does anybody want to help me out and take on the challenge? Or is this impossible for some reason?

#include <stdio.h>
#include <string.h>
#include <stdbool.h>
#include "esp_log.h"
#include "nvs_flash.h"
#include "driver/uart.h"
#include "driver/gpio.h"
#include "freertos/FreeRTOS.h"
#include "freertos/task.h"

/* --- Zigbee SDK includes --- */
#include "esp_zigbee_core.h"
#include "zboss_api.h"            // For ZBOSS types (e.g. zb_af_simple_desc_t)
#include "zcl/esp_zigbee_zcl_common.h"  // For ZCL command IDs, etc.

/* --- R503 Fingerprint Sensor Command Definitions --- 
 * (Refer to the R503 datasheet:
 *  https://download.mikroe.com/documents/datasheets/R503_datasheet.pdf )
 */
#define R503_CMD_GET_IMAGE    0x01  // Capture fingerprint image
#define R503_CMD_IMAGE2TZ     0x02  // Convert image to template
#define R503_CMD_REG_MODEL    0x05  // Merge templates into a model
#define R503_CMD_STORE        0x06  // Store the model at a specified ID
#define R503_CMD_DELETE       0x0C  // Delete a model at a specified ID
#define R503_CMD_EMPTY        0x0D  // Delete all models
#define R503_CMD_CANCEL       0x30  // Cancel current operation

static const char *TAG = "FingerprintZB";

/* --- Hardware configuration --- */
#define UART_PORT               UART_NUM_1
#define UART_TX_PIN             17    // Adjust as needed for your board
#define UART_RX_PIN             16
#define UART_BUF_SIZE           2048
#define FINGERPRINT_SENSING_PIN 4     // Optional: if you use a GPIO to detect finger presence

/* --- Custom Zigbee Cluster Definitions --- */
#define ZB_FINGERPRINT_CLUSTER_ID 0xFC00  // Use a custom cluster ID for fingerprint commands

/* --- Command IDs for Zigbee Commands --- */
enum {
    CMD_ENROLL = 0x00,
    CMD_ENROLL_NEXT = 0x01,
    CMD_CANCEL_ENROLL = 0x02,
    CMD_DELETE = 0x03,
    CMD_DELETE_ALL = 0x04,
};

/* --- Command Payload Structures --- */
typedef struct {
    uint8_t finger_id;
    uint8_t num_scans;
} enroll_cmd_t;

typedef struct {
    uint8_t num_scans;
} enroll_next_cmd_t;

typedef struct {
    uint8_t finger_id;
} delete_cmd_t;

/* --- Global Fingerprint Status (for reporting via Zigbee attributes) --- */
static uint8_t fingerprint_count = 0;
static uint8_t last_finger_id   = 0;
static char fingerprint_status[32] = "Scan your finger";

/* --- LED Control --- 
 * (Implement according to your hardware—for example, control an RGB LED.)
 */
typedef enum {
    LED_STATE_FLASHING,
    LED_STATE_BREATHING,
    LED_STATE_ALWAYS_ON
} led_state_t;

typedef enum {
    LED_COLOR_BLUE,
    LED_COLOR_RED,
    LED_COLOR_PURPLE,
    LED_COLOR_GREEN
} led_color_t;

void aura_led_control(led_state_t state, uint16_t speed, led_color_t color, uint8_t count)
{
    ESP_LOGI(TAG, "LED control: state=%d, speed=%d, color=%d, count=%d", state, speed, color, count);
    // Insert hardware-specific LED control code here.
}

/* --- Forward Declarations for Zigbee Command Handler Wrappers --- */
void zb_cmd_enroll_handler(const enroll_cmd_t *cmd);
void zb_cmd_enroll_next_handler(const enroll_next_cmd_t *cmd);
void zb_cmd_cancel_enroll_handler(void);
void zb_cmd_delete_handler(const delete_cmd_t *cmd);
void zb_cmd_delete_all_handler(void);

/* --- Grow R503 Driver Functions ---
 * These functions form a skeleton for communicating with the Grow R503 over UART.
 * (You must implement full packet formatting and checksum calculation per the datasheet.)
 */
static bool r503_send_command(uint8_t cmd, const uint8_t *params, uint8_t params_len)
{
    uint8_t packet[32] = {0};
    uint8_t pkt_len = 0;

    packet[pkt_len++] = 0xEF;  // Start code
    packet[pkt_len++] = 0x01;  // Device ID (example)
    packet[pkt_len++] = 0x01;  // Packet identifier (command)
    uint16_t length = 1 + params_len + 2; // Command + params + checksum
    packet[pkt_len++] = (length >> 8) & 0xFF;
    packet[pkt_len++] = length & 0xFF;
    packet[pkt_len++] = cmd;   // Command code

    if (params_len && params) {
        memcpy(&packet[pkt_len], params, params_len);
        pkt_len += params_len;
    }
    uint16_t checksum = 0;
    for (int i = 0; i < pkt_len; i++) {
        checksum += packet[i];
    }
    packet[pkt_len++] = (checksum >> 8) & 0xFF;
    packet[pkt_len++] = checksum & 0xFF;

    ESP_LOGD(TAG, "Sending R503 command 0x%02X, packet len=%d", cmd, pkt_len);
    int tx_bytes = uart_write_bytes(UART_PORT, (const char *)packet, pkt_len);
    if (tx_bytes != pkt_len) {
        ESP_LOGE(TAG, "UART write failed");
        return false;
    }
    return true;
}

static int r503_receive_response(uint8_t *buf, size_t buf_len, int timeout_ms)
{
    int rx_bytes = uart_read_bytes(UART_PORT, buf, buf_len, pdMS_TO_TICKS(timeout_ms));
    if (rx_bytes <= 0) {
        ESP_LOGE(TAG, "No response from R503");
        return -1;
    }
    // In a full implementation, verify the response header, length, and checksum.
    return rx_bytes;
}

/* --- Higher-Level R503 Functions ---
 * These functions combine commands for fingerprint enrollment and deletion.
 */
bool r503_capture_image(void)
{
    if (!r503_send_command(R503_CMD_GET_IMAGE, NULL, 0)) {
        return false;
    }
    uint8_t resp[32] = {0};
    int ret = r503_receive_response(resp, sizeof(resp), 1000);
    return (ret > 0 && resp[6] == 0x00);
}

bool r503_image2tz(void)
{
    if (!r503_send_command(R503_CMD_IMAGE2TZ, NULL, 0)) {
        return false;
    }
    uint8_t resp[32] = {0};
    int ret = r503_receive_response(resp, sizeof(resp), 1000);
    return (ret > 0 && resp[6] == 0x00);
}

bool r503_reg_model(void)
{
    if (!r503_send_command(R503_CMD_REG_MODEL, NULL, 0)) {
        return false;
    }
    uint8_t resp[32] = {0};
    int ret = r503_receive_response(resp, sizeof(resp), 1000);
    return (ret > 0 && resp[6] == 0x00);
}

bool r503_store_template(uint8_t finger_id)
{
    uint8_t params[2] = {0x01, finger_id}; // Buffer ID 1 and finger ID
    if (!r503_send_command(R503_CMD_STORE, params, sizeof(params))) {
        return false;
    }
    uint8_t resp[32] = {0};
    int ret = r503_receive_response(resp, sizeof(resp), 1000);
    return (ret > 0 && resp[6] == 0x00);
}

bool r503_delete_template(uint8_t finger_id)
{
    uint8_t params[2] = {finger_id, 0x01}; // Finger ID and delete count = 1
    if (!r503_send_command(R503_CMD_DELETE, params, sizeof(params))) {
        return false;
    }
    uint8_t resp[32] = {0};
    int ret = r503_receive_response(resp, sizeof(resp), 1000);
    return (ret > 0 && resp[6] == 0x00);
}

esp_err_t r503_delete_all(void)
{
    if (!r503_send_command(R503_CMD_EMPTY, NULL, 0)) {
        return ESP_FAIL;
    }
    uint8_t resp[32] = {0};
    int ret = r503_receive_response(resp, sizeof(resp), 2000);
    return (ret > 0 && resp[6] == 0x00) ? ESP_OK : ESP_FAIL;
}

void r503_cancel_enroll(void)
{
    r503_send_command(R503_CMD_CANCEL, NULL, 0);
    // No response expected for cancel.
}

/* --- Enrollment Helper Functions ---
 * Perform one enrollment round (scan and conversion) and finalize enrollment.
 */
bool r503_enroll_scan(void)
{
    if (!r503_capture_image()) {
        ESP_LOGE(TAG, "Failed to capture image");
        return false;
    }
    if (!r503_image2tz()) {
        ESP_LOGE(TAG, "Failed to convert image to template");
        return false;
    }
    return true;
}

bool r503_enroll_finish(uint8_t finger_id)
{
    if (!r503_reg_model()) {
        ESP_LOGE(TAG, "Failed to generate model");
        return false;
    }
    if (!r503_store_template(finger_id)) {
        ESP_LOGE(TAG, "Failed to store template");
        return false;
    }
    return true;
}

/* --- Fingerprint Operation Functions ---
 * These functions are invoked by Zigbee command handlers.
 */
void enroll_fingerprint(uint8_t finger_id, uint8_t num_scans)
{
    ESP_LOGI(TAG, "Starting enrollment for finger_id %d with %d scans", finger_id, num_scans);
    aura_led_control(LED_STATE_FLASHING, 50, LED_COLOR_BLUE, 10);

    for (uint8_t i = 0; i < num_scans; i++) {
        if (r503_enroll_scan()) {
            ESP_LOGI(TAG, "Enrollment scan %d successful", i + 1);
        } else {
            ESP_LOGE(TAG, "Enrollment scan %d failed", i + 1);
            aura_led_control(LED_STATE_FLASHING, 25, LED_COLOR_RED, 4);
            strcpy(fingerprint_status, "Enrollment failed");
            return;
        }
        vTaskDelay(pdMS_TO_TICKS(1000));
    }
    if (r503_enroll_finish(finger_id)) {
        fingerprint_count = (finger_id > fingerprint_count) ? finger_id : fingerprint_count + 1;
        last_finger_id = finger_id;
        ESP_LOGI(TAG, "Fingerprint enrolled successfully");
        aura_led_control(LED_STATE_BREATHING, 100, LED_COLOR_GREEN, 3);
        strcpy(fingerprint_status, "Enrolled fingerprint");
    } else {
        aura_led_control(LED_STATE_FLASHING, 25, LED_COLOR_RED, 4);
        strcpy(fingerprint_status, "Enrollment failed");
    }
}

void enroll_next_fingerprint(uint8_t num_scans)
{
    uint8_t next_id = fingerprint_count + 1;
    enroll_fingerprint(next_id, num_scans);
}

void cancel_enrollment(void)
{
    ESP_LOGI(TAG, "Enrollment cancelled");
    aura_led_control(LED_STATE_ALWAYS_ON, 0, LED_COLOR_RED, 0);
    r503_cancel_enroll();
}

void delete_fingerprint(uint8_t finger_id)
{
    ESP_LOGI(TAG, "Deleting fingerprint with finger_id %d", finger_id);
    aura_led_control(LED_STATE_FLASHING, 50, LED_COLOR_PURPLE, 5);
    if (r503_delete_template(finger_id)) {
        if (fingerprint_count > 0) {
            fingerprint_count--;
        }
        strcpy(fingerprint_status, "Fingerprint deleted");
    } else {
        strcpy(fingerprint_status, "Delete failed");
    }
}

void delete_all_fingerprints(void)
{
    ESP_LOGI(TAG, "Deleting all fingerprints");
    aura_led_control(LED_STATE_FLASHING, 50, LED_COLOR_RED, 10);
    if (r503_delete_all() == ESP_OK) {
        fingerprint_count = 0;
        strcpy(fingerprint_status, "All fingerprints deleted");
    } else {
        strcpy(fingerprint_status, "Delete all failed");
    }
}

/* --- Zigbee Command Dispatcher ---
 * This callback is invoked when a command is received for our fingerprint cluster.
 */
void zb_fingerprint_cluster_command_handler(uint16_t command_id,
                                            const void *payload,
                                            uint16_t payload_len)
{
    switch (command_id) {
    case CMD_ENROLL:
        if (payload_len >= sizeof(enroll_cmd_t))
            zb_cmd_enroll_handler((const enroll_cmd_t *)payload);
        break;
    case CMD_ENROLL_NEXT:
        if (payload_len >= sizeof(enroll_next_cmd_t))
            zb_cmd_enroll_next_handler((const enroll_next_cmd_t *)payload);
        break;
    case CMD_CANCEL_ENROLL:
        zb_cmd_cancel_enroll_handler();
        break;
    case CMD_DELETE:
        if (payload_len >= sizeof(delete_cmd_t))
            zb_cmd_delete_handler((const delete_cmd_t *)payload);
        break;
    case CMD_DELETE_ALL:
        zb_cmd_delete_all_handler();
        break;
    default:
        ESP_LOGW(TAG, "Unknown Zigbee command: %d", command_id);
        break;
    }
}

/* --- Zigbee Command Handler Wrappers ---
 * These wrappers call our fingerprint operation functions.
 */
void zb_cmd_enroll_handler(const enroll_cmd_t *cmd)
{
    ESP_LOGI(TAG, "Zigbee enroll: finger_id=%d, num_scans=%d", cmd->finger_id, cmd->num_scans);
    aura_led_control(LED_STATE_FLASHING, 50, LED_COLOR_BLUE, 10);
    enroll_fingerprint(cmd->finger_id, cmd->num_scans);
}

void zb_cmd_enroll_next_handler(const enroll_next_cmd_t *cmd)
{
    ESP_LOGI(TAG, "Zigbee enroll next: num_scans=%d", cmd->num_scans);
    aura_led_control(LED_STATE_FLASHING, 50, LED_COLOR_BLUE, 10);
    enroll_next_fingerprint(cmd->num_scans);
}

void zb_cmd_cancel_enroll_handler(void)
{
    ESP_LOGI(TAG, "Zigbee cancel enroll");
    aura_led_control(LED_STATE_ALWAYS_ON, 0, LED_COLOR_RED, 0);
    cancel_enrollment();
}

void zb_cmd_delete_handler(const delete_cmd_t *cmd)
{
    ESP_LOGI(TAG, "Zigbee delete: finger_id=%d", cmd->finger_id);
    aura_led_control(LED_STATE_FLASHING, 50, LED_COLOR_PURPLE, 5);
    delete_fingerprint(cmd->finger_id);
}

void zb_cmd_delete_all_handler(void)
{
    ESP_LOGI(TAG, "Zigbee delete all");
    aura_led_control(LED_STATE_FLASHING, 50, LED_COLOR_RED, 10);
    delete_all_fingerprints();
}

/* --- Zigbee Endpoint & Cluster Registration ---
 * We adapt the customized switch example’s approach here.
 */
#define FINGERPRINT_ENDPOINT 1

static void zigbee_init(void)
{
    ESP_LOGI(TAG, "Initializing Zigbee stack...");

    /* Use the default Zigbee End Device configuration */
    esp_zb_cfg_t zb_cfg = ESP_ZB_ZED_CONFIG();
    esp_zb_init(&zb_cfg);

    /* Create a cluster list and add our custom fingerprint cluster.
     * (Assuming the helper function below exists; if not, you can create your cluster list manually.)
     */
    esp_zb_cluster_list_t *cluster_list = esp_zb_zcl_cluster_list_create();
    esp_zb_cluster_list_add_custom_cluster(cluster_list, ZB_FINGERPRINT_CLUSTER_ID, ESP_ZB_ZCL_CLUSTER_SERVER_ROLE);

    /* Create an endpoint list and add our endpoint.
     * Use the Home Automation profile.
     */
    esp_zb_ep_list_t *ep_list = esp_zb_ep_list_create();
    esp_zb_endpoint_config_t endpoint_config = {
        .endpoint = FINGERPRINT_ENDPOINT,
        .app_profile_id = ESP_ZB_AF_HA_PROFILE_ID,
        .app_device_id = 0x0100,         // Custom device ID; adjust as needed
        .app_device_version = 1,
    };
    esp_zb_ep_list_add_ep(ep_list, cluster_list, endpoint_config);

    /* Register our endpoint with the Zigbee stack */
    esp_err_t err = esp_zb_device_register(ep_list);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "Failed to register endpoint: %d", err);
    }

    /* Register our command callback for our custom fingerprint cluster */
    esp_zb_register_cmd_callback(FINGERPRINT_ENDPOINT, ZB_FINGERPRINT_CLUSTER_ID, zb_fingerprint_cluster_command_handler);

    /* Start the Zigbee network (autostart enabled) */
    err = esp_zb_start(true);
    if (err != ESP_OK) {
        ESP_LOGE(TAG, "Failed to start Zigbee stack: %d", err);
    } else {
        ESP_LOGI(TAG, "Zigbee stack started");
    }
}

/* --- Main Application Entry Point --- */
void app_main(void)
{
    esp_err_t ret = nvs_flash_init();
    if (ret != ESP_OK) {
        ESP_LOGE(TAG, "NVS init failed");
        return;
    }

    /* Configure UART for the Grow R503 sensor */
    uart_config_t uart_config = {
        .baud_rate = 57600,
        .data_bits = UART_DATA_8_BITS,
        .parity    = UART_PARITY_DISABLE,
        .stop_bits = UART_STOP_BITS_1,
        .flow_ctrl = UART_HW_FLOWCTRL_DISABLE
    };
    uart_param_config(UART_PORT, &uart_config);
    uart_set_pin(UART_PORT, UART_TX_PIN, UART_RX_PIN, UART_PIN_NO_CHANGE, UART_PIN_NO_CHANGE);
    uart_driver_install(UART_PORT, UART_BUF_SIZE, 0, 0, NULL, 0);

    /* Optionally configure a GPIO for finger sensing */
    gpio_reset_pin(FINGERPRINT_SENSING_PIN);
    gpio_set_direction(FINGERPRINT_SENSING_PIN, GPIO_MODE_INPUT);

    ESP_LOGI(TAG, "Initializing Grow R503 fingerprint sensor");
    // (Insert additional sensor initialization if required.)

    /* Initialize Zigbee */
    zigbee_init();

    /* Main loop */
    while (1) {
        /* In a full application, poll for sensor events (e.g., periodic fingerprint search)
           or update status attributes as needed. */
        vTaskDelay(pdMS_TO_TICKS(100));
    }
}

[xieqinan]

The above code looks strange and does not involve the esp-zigbee-sdk API. Could you try using the simple [HA_ON_OFF_Light(https://github.com/espressif/esp-zigbee-sdk/tree/main/examples/esp_zigbee_HA_sample/HA_on_off_light) example to communicate with Home Assistant first? This will help you better understand how to use the esp-zigbee-sdk. After that, it will be easy to implement the fingerprint sensor.

[Ma1ch]

It's understandable that the above code is strange.

Thank you for the initial advice and reply. I will start from there 👍 let's see what I get done. I have already gotten it to communicate with home assistant, but I will approach it by modifying the example code rather than creating new unusable code.

Also it's great that I now know that there are no obvious obstacles.

[Ma1ch]

i got started on this, and got the zigbee paired without issues to HA. Got stuck really fast on interfacing with the grow r503. Is there a driver or a header for the grow r503 with the esp32c6? or would I have to start developing one?

I appreciate the help.

[Ma1ch]

Maybe this could be used?

https://esphome.io/api/fingerprint__grow_8h_source