{"id":15723016,"url":"https://github.com/bkbilly/mqtt_fingerprint_pi","last_synced_at":"2025-07-09T16:04:42.554Z","repository":{"id":115516742,"uuid":"347252380","full_name":"bkbilly/mqtt_fingerprint_pi","owner":"bkbilly","description":"☝️ Read and write fingerprints through R503 sensor and send the result as MQTT messages.","archived":false,"fork":false,"pushed_at":"2024-12-07T13:03:52.000Z","size":43,"stargazers_count":3,"open_issues_count":0,"forks_count":3,"subscribers_count":1,"default_branch":"main","last_synced_at":"2025-05-13T04:44:37.245Z","etag":null,"topics":["home-assistant","iot","mqtt"],"latest_commit_sha":null,"homepage":"","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":null,"status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/bkbilly.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"funding":null,"license":null,"code_of_conduct":null,"threat_model":null,"audit":null,"citation":null,"codeowners":null,"security":null,"support":null,"governance":null,"roadmap":null,"authors":null,"dei":null,"publiccode":null,"codemeta":null,"zenodo":null}},"created_at":"2021-03-13T02:28:42.000Z","updated_at":"2024-12-07T13:03:56.000Z","dependencies_parsed_at":null,"dependency_job_id":"a53f980b-9a87-4498-911d-75adab81a924","html_url":"https://github.com/bkbilly/mqtt_fingerprint_pi","commit_stats":null,"previous_names":[],"tags_count":0,"template":false,"template_full_name":null,"purl":"pkg:github/bkbilly/mqtt_fingerprint_pi","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkbilly%2Fmqtt_fingerprint_pi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkbilly%2Fmqtt_fingerprint_pi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkbilly%2Fmqtt_fingerprint_pi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkbilly%2Fmqtt_fingerprint_pi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/bkbilly","download_url":"https://codeload.github.com/bkbilly/mqtt_fingerprint_pi/tar.gz/refs/heads/main","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/bkbilly%2Fmqtt_fingerprint_pi/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":264492480,"owners_count":23617030,"icon_url":"https://github.com/github.png","version":null,"created_at":"2022-05-30T11:31:42.601Z","updated_at":"2022-07-04T15:15:14.044Z","host_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub","repositories_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories","repository_names_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repository_names","owners_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners"}},"keywords":["home-assistant","iot","mqtt"],"created_at":"2024-10-03T22:09:59.374Z","updated_at":"2025-07-09T16:04:42.472Z","avatar_url":"https://github.com/bkbilly.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# MQTT Fingerprint PI\nExposes fingerprint sensor R503 to an MQTT broker to control it through Home Assistant. The main purpose is to be used with a smart lock. If you want to create your own, check out the one I created [here](https://community.home-assistant.io/t/smart-lock-with-gears).\n\n\n# Installation\nThis works with the GPIO of Raspberry PI or even a USB serial connected to PC. For Raspberry GPIO, you need to **Disable linux serial console** following the official guide [here](https://www.raspberrypi.org/documentation/configuration/uart.md), or with this command `sudo raspi-config nonint do_serial 2`.\n\n```bash\ngit clone https://github.com/bkbilly/mqtt_fingerprint_pi /opt/mqtt_fingerprint_pi\ncd /opt/mqtt_fingerprint_pi/\nvi config.yaml\n\nsudo pip install -r requirements.txt\nsudo cp mqtt_fingerprint_pi.service /etc/systemd/system/mqtt_fingerprint_pi.service\nsudo systemctl enable mqtt_fingerprint_pi.service\nsudo systemctl start mqtt_fingerprint_pi.service\n```\n\n## Connection diagram\n|     R503 Sensor      |     Raspberry PI     |\n| -------------------- | ------------------------- |\n| RED (Power 3V)       | [3.3V](https://pinout.xyz/pinout/3v3_power)  |\n| BLACK (GND)          | [Ground](https://pinout.xyz/pinout/ground)  |\n| YELLOW (TXD)         | [UART RX](https://pinout.xyz/pinout/pin10_gpio15)  |\n| GREEN (RXD)          | [UART TX](https://pinout.xyz/pinout/pin8_gpio14)  |\n| BLUE (Wakeup)        | Not connected  |\n| WHITE (3.3VT)        | Not connected  |\n\n\n# Configuration\nEdit the config.yaml file with the following info:\n```yaml\nserial: \"/dev/serial0\"  # Default serial for Raspberry\ntimeout: 0              # Expiration time for each fingerprint (0=deactivate)\nmqtt:\n  host: \"192.168.x.x\"   # MQTT Broker IP\n  user: \"myuser\"        # MQTT Username\n  pass: \"mypass\"        # MQTT Password\n```\n## Temporary fingerprints\nTo enable the temporary fingerprints, you will have to change the timeout to any integer value other than zero.\nEach fingerprint is stored on the `devices.yaml` file with the time they were enrolled.\nIf you change their **name**, they are considered **permanent** users, but if you don't change them, they will be considered **temporary**.\nThe user works normally until the timeout is reached which will show send a timeout on mqtt instance.\n\n# Home Assistant Integration\nThis automation will check the action of the finger and it will call the appropriate service of the lock.\n```yaml\nalias: Fingerprint scanned successfully\ntrigger:\n  - platform: mqtt\n    topic: fingerprint/finger\naction:\n  - choose:\n      - conditions:\n          - condition: template\n            value_template: '{{ trigger.payload_json.action == \"unlock\" }}'\n        sequence:\n          - service: lock.unlock\n            target:\n              entity_id: lock.frontdoor\n      - conditions:\n          - condition: template\n            value_template: '{{ trigger.payload_json.action == \"lock\" }}'\n        sequence:\n          - service: lock.lock\n            target:\n              entity_id: lock.frontdoor\n```\n\nYou can have a sensor to keep track of the fingeprint usage.\n```yaml\nsensor:\n  - platform: mqtt\n    name: \"Fingerprint\"\n    state_topic: \"fingerprint/finger\"\n    value_template: \"{{ value_json.name }}\"\n    json_attributes_topic: \"fingerprint/finger\"\n    json_attributes_template: \"{{ value_json | tojson }}\"\n```\n\n\n# MQTT Commands\n\n## fingerprint/finger\nThis is published when a finger is scanned by the sensor. It contains the following:\n```python\n{\n  \"id\": 0,             # The id in the fingerprint sensor. (-1 means unauthorized user)\n  \"action\": \"unlock\",  # Default action is unlock, but supports \"timeout, unauthorized, unlock, lock\"\n  \"name\": \"bkbilly\",   # The user defined in devices.yaml\n  \"confidence\": 76     # How close the finger is to the original scan\n}\n```\n\n## fingerprint/templates\nThis is published everytime a change is occured on the database like deleting or enrolling fingerprints.\nIt contains a list of each fingerprint.\n```python\n[\n  {\n    \"id\": 0,            # The id in the fingerprint sensor\n    \"name\": \"bkbilly\",  # The custom name of the finger, defaults to ID value\n    \"action\": \"unlock\", # The action to perform, defaults to \"unlock\"\n    \"time\": 1615721723  # The timestamp the finger was enrolled\n  }\n]\n```\n\n## fingerprint/mode\nThe default mode is scan which is constantly looking for new fingerprint inputs. It can support the following: \n  - enroll (scans finger twice and saves it into the fingerprint sensor)\n  - scan (look for new fingerprint inputs)\n  - delete (deletes a fingerprint based on it's ID)\n  - empty (deletes all fingerprints)\n\n## \"fingerprint/set/mode\"\nChanges the mode \"enroll, delete, empty, name_xx\". Most of them don't need any value, except delete which requires the id of the fingerprint.\n\n### Enroll\n```yaml\nservice: mqtt.publish\ndata:\n  topic: fingerprint/set/mode/enroll\n  payload: \"-1\"\n```\n\n### Rename\n```yaml\nservice: mqtt.publish\nmetadata: {}\ndata:\n  topic: fingerprint/set/mode/name_{{ finger_id }}\n  payload: \"{{ name }}\"\n```\n\n### Delete\n```yaml\nservice: mqtt.publish\ndata:\n  topic: fingerprint/set/mode/delete\n  payload: \"{{ finger_id }}\"\n```\n\n### Delete All\n```yaml\nservice: mqtt.publish\ndata:\n  topic: fingerprint/set/mode/empty\n```\n\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkbilly%2Fmqtt_fingerprint_pi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fbkbilly%2Fmqtt_fingerprint_pi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fbkbilly%2Fmqtt_fingerprint_pi/lists"}