This is a firmware for arduino-like devices with integrated WIFI adapter, based on ESP8266 board, like the Wemos D1 Mini.
Connect one of these boards to a R503 Fingerprint capacitive sensor and you can send commands via MQTT protocol to an IoT hub.
This project is made with Home Assistant integration in mind, but it can be used to only interact with any MQTT broker (see below for some HA integration examples).
- Simple configuration via WIFI
- Detect different users and different user's fingerprints
- Detect fingerprint mismatch
- Add and delete fingerprints via MQTT
- Led color code feedback
Home Assistant can use messages to enable automations and trigger things like:
- Open a door using electric locks
- Enable/disable alarm system using different fingerprints
- Enable/disable access based on user and/or time
- Activate notifications on unknown fingerprint
- Home Assistant with MQTT broker running (or another MQTT broker running on your LAN)
- A fingerprint sensor model R503
- An ESP8266 board like the Wemos D1 mini
Interaction will be done sending/receiving MQTT messages to a broker. Most used broker is called Mosquitto and can be installed as Home Assistant integration.
- Red cable on 3.3 volt
- Black cable on ground
- Green cable on pin D5
- Yellow cable on pin D6
The other 2 sensor cables can be left unused.
This project is not made using standard Arduino IDE. It's a PlatformIO project.
Connect the Wemos to a usb port and:
- Linux (and maybe Mac): type
$ ./install_into_usb_connected_wemos_d1.sh(python3 and curl are needed) - Windows: I don't know. Follow PlatformIO docs to flash under Windows machines.
After flash and reboot, when no configuration is found the Wemos will turn on a WiFi network called "Fingerprint-Setup":
Use a mobile phone or PC to connect to that WiFi network. A configuration page will popup:
Fill in all required fields:
- SSID name of your WiFi network
- WiFi password
- MQTT host: broker hostname or IP (use Home Assistant address if you are using it's Mosquitto add-on)
- MQTT port: broker port (usually 1883)
- MQTT username (configure an user in Mosquitto or let it be got from Home Assistant users)
- MQTT password (the password)
- Gate name: the name of this sensor (to distinguish from other devices on the same broker)
NB: do NOT use any special chars in the gate name field: only letters and numbers, no spaces or other things.
After saving, Wemos will reboot and will try to connect to the WiFi network. On success, it will flash blue led on the sensor.
Everything will be controlled by sending and receiving MQTT messages. If you are using Home Assistant you can both send and receive messages in:
Configuration -> Integration -> MQTT - CONFIGURE
Then you can set a topic to send to json messages, and a topic to listen to for incoming messages.
Topics must include the given gate name, following this table:
| Topic | Direction | Purpose |
|---|---|---|
| /fingerprint/gate/learn | outgoing | Start the learning new fingerprint process |
| /fingerprint/gate/delete | outgoing | Delete a previous learned fingerprint |
| /fingerprint/gate/status | incoming | Current sensor status and messages |
For example, if gate is "main":
To initiate a learning process, send this message to the learn topic:
{
"fingerprintId": *number*
}
Where number is the fingerprint identification number, from 10 to 200. Suggested convention is to use intervals of 10 id's to match users. So, user 1 will have a fingerprint id from 10 to 19, user 2 from 20 to 29 and so on. Internally, a division by 10 will be done, so user calculation will be ready made.
The process requires a fingerprint snapshot and then a match. So, the steps will be:
- Wait for purple led flashing
- Put the finger on the sensor
- Wait until led turns off
- Remove finger
- Wait for purple led flashing again
- Put same finger on the sensor
- Wait until led turns off
- Remove finger
- If successful, a three times blue flash will confirm
To programmatically follow the learning process read the status topic messages.
Status topic will be used to both inform the user about the learning/deleting process and current fingerprint matching status.
At idle, the sensor will continuously look for a fingerprint. Result will be reported in a message like:
{
"message": "Waiting...",
"state": "wait",
"mode": "reading",
"match": false,
"fingerprintId": 0,
"userId": 0,
"confidence": 0,
"gate": "main"
}
| Field | Purpose |
|---|---|
| message | Human readable message, useful when learning |
| state | Current sensor state, see below for values |
| mode | If the sensor is reading, learning or deleting |
| match | True if a fingerprit has been recognized |
| fingerprintId | The recognized fingerprint |
| userId | The calculated userId, based on fingerprintId/10 convention |
| confidence | How much the recognition is reliable |
| gate | Current configured gate name |
State field can be:
- error: something is not working
- wrong: a wrong fingerprint has been detected, can be used as alarm trigger
- match: a recognized fingerprint has been detected
- wait: fingerprint sensor is waiting for a finger
Example, a matching message (slow blue led feedback):
{
"message": "Fingerprint match found.",
"state": "match",
"mode": "reading",
"match": true,
"fingerprintId": 10,
"userId": 1,
"confidence": 98,
"gate": "main"
}
A fingerprint has been detected but not recognized. An unknown hand to the sensor (red flashing led feedback):
{
"message": "Unknown fingerprint detected.",
"state": "wrong",
"mode": "reading",
"match": false,
"fingerprintId": 0,
"userId": 0,
"confidence": 8,
"gate": "main"
}
To delete a fingerprint, send this message to the delete topic:
{
"fingerprintId": *number*
}
Where number is the fingerprint identification number to delete. Resetting the device will not delete fingerprints because images are stored in the sensor itself and not in the ESP firmware.
Onboard blue led will signal when connection to MQTT broker is established: solid when connected, blink when connecting. Signalling is referred to MQTT, so even if network connection is ok but MQTT is broken the led will blink.
Also, every time the MQTT client connects to the broker the feedback led on the sensor will flash in blue.
If you mistyped config data or you want to reset device, do:
- turn on device
- wait 10 seconds
- press the reset button
- wait 5 seconds
- press again reset button
The device will reboot in config mode and Fingerprint-Setup WiFi network will come back again.
NB: reset will NOT reset any registered fingerprints on the sensor.
Some configuration examples for Home Assistant. You need to edit the "configuration.yaml" file inside HA filesystem. See official tutorial.
NB: change "main" in state_topic to match your gate name.
binary_sensor:
- platform: mqtt
name: "FingerprintOK"
state_topic: "/fingerprint/main/status"
payload_on: true
payload_off: false
value_template: "{{ value_json.match }}"
This is a "binary_sensor", eg. a two position element such as a switch, that turns on when any registered fingerprint is detected.
NB: change "main" in state_topic to match your gate name.
binary_sensor:
- platform: mqtt
name: "TriggerAlarm"
state_topic: "/fingerprint/main/status"
payload_on: "wrong"
payload_off: "wait"
value_template: "{{ value_json.state }}"
This is a "binary_sensor", eg. a two position element such as a switch, that turns on when an unknown fingerprint is detected.
NB: change "main" in state_topic to match your gate name.
binary_sensor:
- platform: mqtt
name: "OpenTheDoor"
state_topic: "/fingerprint/main/status"
value_template: "{% if finger.match and finger.userId | int == 1 %}ON{% else %}OFF{% endif %}"
This is a "binary_sensor", eg. a two position element such as a switch, that turns on when any fingerprint of user with id 1 is detected.
NB: change "main" in state_topic to match your gate name.
binary_sensor:
- platform: mqtt
name: "ActivateAlarm"
state_topic: "/fingerprint/main/status"
value_template: "{% if finger.match and finger.fingerprintId | int == 15 %}ON{% else %}OFF{% endif %}"
This is a "binary_sensor", eg. a two position element such as a switch, that turns on when a specifig fingerprint, the 5th, of user with id 1 is detected.
If you have suggestions or ideas, please use issues tab to contact me.