{"id":14963835,"url":"https://github.com/esprfid/esp-rfid","last_synced_at":"2025-05-14T09:08:00.549Z","repository":{"id":38074990,"uuid":"90875549","full_name":"esprfid/esp-rfid","owner":"esprfid","description":"ESP8266 RFID (RC522, PN532, Wiegand, RDM6300) Access Control system featuring WebSocket, JSON, NTP Client, Javascript, SPIFFS","archived":false,"fork":false,"pushed_at":"2025-02-23T19:55:57.000Z","size":57840,"stargazers_count":1424,"open_issues_count":67,"forks_count":426,"subscribers_count":112,"default_branch":"stable","last_synced_at":"2025-05-14T09:07:49.573Z","etag":null,"topics":["access-control","access-management","board","esp-rfid","esp8266","esp8266-rfid","esp8266-websocket","flash","hacktoberfest","mfrc522","pn532","rc522","rdm6300","rfid-doorlock-application","rfid-hardware","rfid-rc522","rfid-reader","rfid-tags","websocket","wiegand"],"latest_commit_sha":null,"homepage":"","language":"C++","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"mit","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/esprfid.png","metadata":{"files":{"readme":"README-MQTT.md","changelog":"CHANGELOG.md","contributing":"CONTRIBUTING.md","funding":null,"license":"LICENSE","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":"2017-05-10T14:46:46.000Z","updated_at":"2025-05-13T11:45:02.000Z","dependencies_parsed_at":"2023-11-14T00:02:37.762Z","dependency_job_id":"cf7ae661-d9d4-4ab8-8856-2f03d6b88998","html_url":"https://github.com/esprfid/esp-rfid","commit_stats":{"total_commits":301,"total_committers":15,"mean_commits":"20.066666666666666","dds":0.3156146179401993,"last_synced_commit":"fef1d9b875c635790b4fdec8f81da74d830c6025"},"previous_names":[],"tags_count":28,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esprfid%2Fesp-rfid","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esprfid%2Fesp-rfid/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esprfid%2Fesp-rfid/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/esprfid%2Fesp-rfid/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/esprfid","download_url":"https://codeload.github.com/esprfid/esp-rfid/tar.gz/refs/heads/stable","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":254110374,"owners_count":22016391,"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":["access-control","access-management","board","esp-rfid","esp8266","esp8266-rfid","esp8266-websocket","flash","hacktoberfest","mfrc522","pn532","rc522","rdm6300","rfid-doorlock-application","rfid-hardware","rfid-rc522","rfid-reader","rfid-tags","websocket","wiegand"],"created_at":"2024-09-24T13:32:12.707Z","updated_at":"2025-05-14T09:08:00.496Z","avatar_url":"https://github.com/esprfid.png","language":"C++","funding_links":[],"categories":["Existing Projects"],"sub_categories":[],"readme":"# ESP RFID with extended MQTT Functions\n\nHardware:\n* Any esp-rfid board like esp-rfid-relay-board, marelab ESP-DOOR\n\nThis has been added so far:\n* Reading all user data over MQTT\n* Sending User data to RFID-DOOR/ESP-RFID over MQTT\n* Sending door open command over MQTT\n* Sending door status over MQTT as event\n* Sending Sync of a RFID-DOOR (IP/Hostname) over MQTT\n* Configure Sync interval over ESP-RFID GUI\n* Deleting all User of a ESP-RFID device over MQTT\n* Sending log event \u0026 access data over MQTT\n* Demo NODE-RED flow \u0026 GUI to centralize managment of ESP-RFID devices \u0026 users\n\n## Broker settings\nYou can add all the broker details in the web UI:\n\n![MQTT settings](./demo/mqtt-settings.png) \u003c- to update\n\n## Using MQTT Topics\nFor the MQTT communication some additional TOPICs have been added internally. The default Topic is configured in the web UI. If you use more then one device, every device should have the same `TOPIC` name configured. All MQTT communication is done with JSON Payload as MQTT Message.\n\nThis is the used Topic hierarchy:\n\n```\nTOPIC---+---/send\n        |\n        +---/cmd\n```\n\n  e.g. if you configure in the web UI `TOPIC` = \"/rfid\" these topic queues can be used:\n  * /rfid\n  * /rfid/send\n  * /rfid/cmd\n\n### Auto-topic\n\nIf auto-topic option is selected, esp-rfid will add the last 6 characters from the device MAC address to the MQTT topic.\n\nThis can be useful to deploy a batch of esp-rfid in one go. By knowing the MAC addresses in advance you can setup them all with a standard configuration and each one will talk on a separate topic.\n\n## Commands received by ESP-RFID\nThe message format is JSON.\n\nThe message has to include the IP of the device together with one of the supported commands.\n\nThe commands should be sent to the `TOPIC/cmd` and the responses will be sent on  the topic `TOPIC/send`.\n\n### Get all the users\nWhen sending the following command:\n```\n{\n   \"cmd\":\"getuserlist\",\n   \"doorip\":\"(The ESP-RFID IP address as String)\"\n}\n```\n\nA list of messages like the following will be sent, one for each user:\n```\n{\n    \"command\": \"userfile\",\n    \"uid\": \"1234\",\n    \"user\": \"User Name\",\n    \"acctype\": 1,\n    \"acctype2\": null,\n    \"acctype3\": null,\n    \"acctype4\": null,\n    \"validsince\": 0,\n    \"validuntil\": 1608336000\n}\n```\n\n### Open door\nOpens the Door/Magnetic Lock.\n\nCommand:\n```\n{\n    \"cmd\":\"opendoor\",\n    \"doorip\":\"(The ESP-RFID IP of the door to open as String)\"\n}\n```\n\nResponse will be a standard [Publish Access](#publish-access) message.\n\n### Delete user\nDelete a single user by UID.\n\nCommand:\n```\n{\n     \"cmd\":\"deletuid\",\n     \"doorip\":\"(The ESP-RFID IP address as String)\",\n     \"uid\":\"(The UID of the user to delete as String)\"\n}\n```\n\nResponse will be an acknowledgment to let the other party know that the message was processed:\n```\n{\n  \"type\":\"deletuid\",\n  \"ip\":\"192.168.1.xxx\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n### Delete all users\nDelete all user files.\n\nCommand:\n```\n{\n     \"cmd\":\"deletusers\",\n     \"doorip\":\"(The ESP-RFID IP address as String)\"\n}\n```\n\nResponse will be an acknowledgment to let the other party know that the message was processed:\n```\n{\n  \"type\":\"deletusers\",\n  \"ip\":\"192.168.1.xxx\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n### Add user\nAdds a user as a file to the device.\n\nCommand:\n```\n{\n     \"cmd\":\"adduser\",\n     \"doorip\":\"(The ESP-RFID IP address as String)\",\n     \"uid\": \"(The PIN as String)\",\n     \"user\": \"(User Name as String)\",\n     \"acctype\": \"1\",\n     \"validsince\": \"0\",\n     \"validuntil\": \"1608466200\"\n}\n```\n* _acctype_\n  * 0 = Disabled\n  * 1 = Always\n  * 99 = Admin\n\n* _validsince_\n  * User valid since date/time as Unix epoch timestamp\n  * Can send calculations based on now:\n    * ```validsince: {{ (as_timestamp(now()) + (2*24*3600)) }}```\n\n* _validuntil_\n  * Expiration date/time as Unix epoch timestamp\n  * Can send calculations based on now:\n    * ```validuntil: {{ (as_timestamp(now()) + (2*24*3600)) }}```\n\nResponse will be an acknowledgment to let the other party know that the message was processed:\n```\n{\n  \"type\":\"adduser\",\n  \"ip\":\"192.168.1.xxx\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n### Get configuration\nGet the global configuration.\n\nCommand:\n```\n{\n     \"cmd\":\"getconf\",\n     \"doorip\":\"(The ESP-RFID IP address as String)\"\n}\n```\n\nResponse will be an object with a `configfile` key which holds the entire configuration object. The same object that you can download from the \"Backup \u0026 Restore\" section.\n```\n{\n  \"type\":\"getconf\",\n  \"ip\":\"192.168.1.xxx\",\n  \"hostname\":\"your esp-rfid hostname\",\n  \"configfile\": {\n    // the entire configuration object\n  }\n}\n```\n\n### Update configuration\nUpdate the global configuration. You can pass a configuration object, which will be used as the new configuration. Then the system will restart to load the new configuration.\n\nCommand:\n```\n{\n     \"cmd\":\"updateconf\",\n     \"doorip\":\"(The ESP-RFID IP address as String)\",\n     \"configfile\": {\n      // the entire configuration object\n     }\n}\n```\n\nResponse will be an acknowledgment to let the other party know that the message was processed:\n```\n{\n  \"type\":\"updateconf\",\n  \"ip\":\"192.168.1.xxx\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nThen the system will automatically restart to use the new configuration.\n\n## Messages sent by ESP-RFID\nESP-RFID sends a set of MQTT messages for the most significant actions that it does, plus can be configured to send all the logs over MQTT, instead of keeping them locally.\n\nAll the messages are sent at the topic: `TOPIC/send`.\n\nFor Home Assistant, check the specific topics and messages below.\n\n### Base messages\n\n#### Boot\nOnce booted and connected to the WiFi, it sends this message.\n\n```\n{\n  \"type\":\"boot\",\n  \"time\":1605987212,\n  \"uptime\":0,\n  \"ip\":\"192.168.1.xxx\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n#### Heartbeat\nEvery X seconds ESP-RFID sends a heartbeat over MQTT. The interval can be customised in the web UI, the default is 180 seconds.\n\n```\n{\n  \"type\":\"heartbeat\",\n  \"time\":1605991375,\n  \"uptime\":999,\n  \"ip\":\"192.168.1.xxx\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n#### Publish Access\nWhen a RFID token is detected a set of messages can be sent, depending on the presence of the token UID in the database.\n\nIf the UID is in the users list, there can be a set of possible \"access\" configurations. It can be:\n\n* `Admin` for admin users\n* `Always` for access enabled\n* `Disabled` for access disabled\n* `Expired` for access expired\n\n```\n{\n  \"type\":\"access\",\n  \"time\":1605991375,\n  \"isKnown\":\"true\",\n  \"access\":\"the access state\",\n  \"username\":\"username\",\n  \"uid\":\"token UID\",\n  \"pincode\":\"user pincode\",\n  \"hostname\":\"your esp-rfid hostname\",\n  \"doorName\":\"your door name\"\n}\n```\nIf instead the UID is not present in the users list the message will be:\n\n```\n{\n  \"type\":\"access\",\n  \"time\":1605991375,\n  \"isKnown\":\"false\",\n  \"access\":\"Denied\",\n  \"username\":\"Unknown\",\n  \"uid\":\"token UID\",\n  \"pincode\":\"user pincode\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nIf the tag is unknown the message will be different:\n\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"rfid\",\n  \"desc\":\"Unknown rfid tag is scanned\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nIn case of multiple doors managed by one esp-rfid, you'll get an array for doorname and for access:\n\n```\n{\n  \"type\":\"access\",\n  \"time\":1605991375,\n  \"isKnown\":\"true\",\n  \"access\":[\"the access state door 1\", \"access state door 2\"],\n  \"username\":\"username\",\n  \"uid\":\"token UID\",\n  \"pincode\":\"user pincode\",\n  \"hostname\":\"your esp-rfid hostname\",\n  \"doorName\":[\"door 1\", \"door 2\"]\n}\n```\n\n### Log messages\nBesides the above messages, ESP-RFID can send all the logs via MQTT instead of storing those locally. If this is enabled via the web UI, also the following messages are sent.\n\n#### Door status\nIf the door sensor is enabled, two messages are sent, one when the door is opened:\n\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"door\",\n  \"desc\":\"Door Open\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nAnd one when the door is closed:\n\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"door\",\n  \"desc\":\"Door Closed\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n#### Doorbell\nIf the doorbell is enabled, a message is sent when it's ringing:\n\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"doorbell\",\n  \"desc\":\"Doorbell ringing\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n#### Tamper status\nIf the door is tampered, or open when it shouldn't be a message is sent:\n\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"tamper\",\n  \"desc\":\"Door was tampered!\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nAnd then if the open is not closed before the maximum allowed time:\n\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"tamper\",\n  \"desc\":\"Door wasn't closed within max open time!\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n#### WiFi status\nSome messages around WiFi handling are also sent.\n\nEnabling/disabling of WiFi:\n\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"wifi\",\n  \"desc\":\"WiFi is going to be disabled / Enabling WiFi\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n#### MQTT status\nMQTT connection or message handling related.\n\nOn connecting to the broker:\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"mqtt\",\n  \"desc\":\"Connected to MQTT Server\",\n  \"data\":\"Session Present\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nOn disconnecting from the broker:\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"mqtt\",\n  \"desc\":\"Disconnected from MQTT server\",\n  \"data\":\"reason of disconnection\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nWhen the ESP8266 cannot store in memory incoming messages due to low memory a message will be sent back:\n```\n{\n  \"type\":\"ERRO\",\n  \"src\":\"mqtt\",\n  \"desc\":\"Dropping MQTT message, out of memory\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\n#### System messages\nWhen the system configuration is done and the system is up and running\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"sys\",\n  \"desc\":\"System setup completed, running\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nBefore performing a requested reboot:\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"sys\",\n  \"desc\":\"System is going to reboot\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nBefore performing a scheduled reboot:\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"sys\",\n  \"desc\":\"Auto restarting...\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nOn a FS format:\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"sys\",\n  \"desc\":\"Filesystem formatted\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nWhen saving the configuration on SPIFFS:\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"sys\",\n  \"desc\":\"Config stored in the SPIFFS\",\n  \"data\":\"xxx bytes\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n```\n\nAfter deleting all the event logs:\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"sys\",\n  \"desc\":\"Event log cleared!\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n\nAfter deleting all the access logs:\n```\n{\n  \"type\":\"WARN\",\n  \"src\":\"sys\",\n  \"desc\":\"Latest Access log cleared!\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n\nWhen starting the firmware update:\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"updt\",\n  \"desc\":\"Firmware update started\",\n  \"data\":\"file name\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n\nIf there's no space to upload the firmware:\n```\n{\n  \"type\":\"ERRO\",\n  \"src\":\"updt\",\n  \"desc\":\"Not enough space to update\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n\nIf the firmware update failed because it's not possible to write on flash:\n```\n{\n  \"type\":\"ERRO\",\n  \"src\":\"updt\",\n  \"desc\":\"Writing to flash is failed\",\n  \"data\":\"file name\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n\nIf the firmware update successfully finished:\n```\n{\n  \"type\":\"INFO\",\n  \"src\":\"updt\",\n  \"desc\":\"Firmware update is finished\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n\nIf the firmware update failed:\n```\n{\n  \"type\":\"ERRO\",\n  \"src\":\"updt\",\n  \"desc\":\"Update is failed\",\n  \"data\":\"\",\n  \"time\":1605991375,\n  \"cmd\":\"event\",\n  \"hostname\":\"your esp-rfid hostname\"\n}\n\n### Home Assistant messages\n\n#### Boot sequence\nWhen esp-rfid finishes the boot sequence and connects to WiFi and MQTT broker sends HA-specific messages to setup: lock, door, doorbell, tag, user, door tamper, avty.\n\n#### IO messages\nDuring normal usage, esp-rfid sends to Home Assistant messages on the `/io/*` topics for the following:\n- door status, open/closed\n- door tamper\n- doorbell on/off\n- lock locked/unlocked\n\n\n#### Publish access\nSimilarly to what is published for the standard MQTT settings, when Home Assistant is setup, esp-rfid sends a set of messages when a rfid card is swiped.\n\nRead above for the possible cases, the significant part fo HA is that the topic to which the message is sent is different: `TOPIC/tag`.\n\nAnd the message looks like this:\n\n```\n{\n  \"uid\":\"token UID\",\n  \"username\":\"username\",\n  \"pincode\":\"user pincode\",\n  \"access\":\"the access state\",\n  \"time\":1605991375,\n }\n```\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesprfid%2Fesp-rfid","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fesprfid%2Fesp-rfid","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fesprfid%2Fesp-rfid/lists"}