{"id":16998512,"url":"https://github.com/amusarra/smartcard-contactless-raspberry-pi","last_synced_at":"2025-09-18T22:34:30.816Z","repository":{"id":144585951,"uuid":"463892456","full_name":"amusarra/smartcard-contactless-raspberry-pi","owner":"amusarra","description":"Smart Card Contactless Raspberry Pi. This project was born with the aim of providing a complete example (hardware and software) on how it is possible to create a simple access system using contactless Smart Cards with Mifare Classic 1k  and the Raspberry Pi.","archived":false,"fork":false,"pushed_at":"2024-07-15T09:44:05.000Z","size":40134,"stargazers_count":18,"open_issues_count":1,"forks_count":1,"subscribers_count":2,"default_branch":"master","last_synced_at":"2025-03-18T13:19:16.314Z","etag":null,"topics":["mifare-classic","mifare1k","pyscard","python","raspberry-pi","relay","relay-board","rfid","smartcard","smartcard-reader"],"latest_commit_sha":null,"homepage":"https://bit.ly/3pY0F80","language":"Python","has_issues":true,"has_wiki":null,"has_pages":null,"mirror_url":null,"source_name":null,"license":"other","status":null,"scm":"git","pull_requests_enabled":true,"icon_url":"https://github.com/amusarra.png","metadata":{"files":{"readme":"README.markdown","changelog":"CHANGELOG.md","contributing":null,"funding":null,"license":"LICENSE.markdown","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}},"created_at":"2022-02-26T15:34:53.000Z","updated_at":"2025-03-04T03:54:36.000Z","dependencies_parsed_at":null,"dependency_job_id":"e6ab8c9a-fc6e-4c78-a321-a4ed7da6ff46","html_url":"https://github.com/amusarra/smartcard-contactless-raspberry-pi","commit_stats":{"total_commits":47,"total_committers":3,"mean_commits":"15.666666666666666","dds":0.276595744680851,"last_synced_commit":"4ad2a43195bac1af5e300927a081000479c982a0"},"previous_names":[],"tags_count":5,"template":false,"template_full_name":null,"repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amusarra%2Fsmartcard-contactless-raspberry-pi","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amusarra%2Fsmartcard-contactless-raspberry-pi/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amusarra%2Fsmartcard-contactless-raspberry-pi/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/amusarra%2Fsmartcard-contactless-raspberry-pi/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/amusarra","download_url":"https://codeload.github.com/amusarra/smartcard-contactless-raspberry-pi/tar.gz/refs/heads/master","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":244978572,"owners_count":20541875,"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":["mifare-classic","mifare1k","pyscard","python","raspberry-pi","relay","relay-board","rfid","smartcard","smartcard-reader"],"created_at":"2024-10-14T04:05:28.407Z","updated_at":"2025-09-18T22:34:25.749Z","avatar_url":"https://github.com/amusarra.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# Smart Card Contactless Raspberry Pi\n[![Antonio Musarra's Blog](https://img.shields.io/badge/maintainer-Antonio_Musarra's_Blog-purple.svg?colorB=6e60cc)](https://www.dontesta.it)\n[![Twitter Follow](https://img.shields.io/twitter/follow/antonio_musarra.svg?style=social\u0026label=%40antonio_musarra%20on%20Twitter\u0026style=plastic)](https://twitter.com/antonio_musarra)\n\nThis is a project linked to an article [Raspberry Pi e Smart Card Mifare Classic 1K: Realizzare un sistema di accesso](https://bit.ly/3pY0F80) \npublish on my [blog](https://www.dontesta.it). What is described in this README should be enough to make you understand \nthe intentions of this project, I leave the rest to your curiosity.\n\nThis project was born with the aim of providing a complete example (hardware and software) on how it is possible to \ncreate a simple access system using contactless Smart Cards and the Raspberry Pi. The figure below shows the hardware \ndiagram of the Smart Card access solution.\n\nThe scenario I created is the one that each of us experiences almost every day, that is, with our hands a Smart Card \nto gain access to an opening, which could for example be a door to a hotel room.\n\n![Hardware diagram of the Smart Card access solution](docs/images/hardware_diagram_smartcard_access_raspberry_pi_1.jpg)\n\nFigure 1 - Hardware diagram of the Smart Card access solution (Smart Card icon from https://www.smartcardfocus.com/)\n\nThe [MIFARE Classic® 1K](https://www.nxp.com/docs/en/data-sheet/MF1S50YYX_V1.pdf) contactless is predicated on \n**NXP MF1 IC S50**, which is connected to a coil with a couple of turns then embedded into the plastic to make the \npassive contactless open-end credit. The communication layer (MIFARE RF Interface) complies with part 2 and three \nof the [ISO/IEC14443A](https://en.wikipedia.org/wiki/ISO/IEC_14443) standard. This type of card is a good choice for \nclassic applications such as public transport ticketing and can also be used for several other applications \n(door opening systems and the like). \n\nThe Smart Card Reader must be compliant with the standards indicated in the diagram in figure 1. In my case I used \nthe [Bit4id miniLector CIE](https://shop.bit4id.com/prodotto/minilector-cie/) reader connected to the Raspberry Pi via \nthe USB port. The technical name of the reader I used is: BIT4ID miniLector AIR NFC v3.\n\nA four-relay module managed through the [GPIO](https://en.wikipedia.org/wiki/General-purpose_input/output) ports is \nconnected to the Raspberry Pi. In our scenario, the relays represent the actuators necessary to open the doors of the \nhotel where we are guests.\n\nFigure 2 illustrates the simplified process (in [BPMN](https://www.bpmn.org/) notation) of what happens when a guest is \nreceived by the hotel staff. Of the whole process, only the service task (indicated in red) is the object of the \nsoftware implementation.\n\n![Guest Receiving Process](docs/images/guest_receiving_process.jpg)\n\nFigure 2 - Simplified process of receiving the guest at the hotel.\n\nThe process of figure 3 instead shows what happens when the guest asks to enter his room through the use of the \nelectronic key by placing it on the reader. Of the whole process, only the service task (indicated in red) is the \nobject of the software implementation.\n\n![Room access process](docs/images/room_access_process.jpg)\n\nFigure 3 - Room access process\n\nThe software of this project written in Python implements the service tasks indicated in the processes of figure 2 and \nfigure 3. In particular, the entry points are:\n\n1. `setup_smart_card.py`. Python script that implements the service task indicated in the process of figure 2. \nThis script receives a series of input data (number of identity document, room number, name and surname of the \nguest). Of the received data, some are stored on the Smart Card (identity document number) and others on the \ndatabase (in this case MongoDB).\n2. `access_via_smart_card.py`. Python script that implements the service task indicated in the process of \nfigure 3. This script extracts from the Smart Card the identification of the same and the number of the identity \ndocument, then uses this data to understand if the guest can have access to his room.\n\nTable 1 shows the data managed by the Smart Card. The UID is actually proper to the Smart Card, however, the \nIdentification Number attribute is written during the setup phase by the `setup_smart_card.py` script and read during the access \nrequest phase by the `access_via_smart_card.py` script.\n\n| Attribute Name        | Description                                                                      | Type     | \n|:----------------------|:---------------------------------------------------------------------------------|:---------| \n| UID                   | Smart Card ID assigned by the manufacturer. In this case we use the 4-byte NUID. | Byte(4)  |\n| Identification Number | Number (which can also be alphanumeric) of the guest's identity document.        | Byte(16) |\n\nTable 1 - Data that is stored on the Smart Card.\n\nTable 2 shows the data managed by the database (MondoDB). The scope column indicates which python script used (for \nreading or writing) the attribute, therefore, identifies on which process it is used (setup procedure or access \nprocedure).\n\nConsole 3 shows the document created on the database during the Smart Card setup phase. Console 5 shows the document \nupdated when requesting access via the Smart Card.\n\n| Attribute Name    | Scope                                         | Description                                                               | Type                                  | \n|:------------------|:----------------------------------------------|:--------------------------------------------------------------------------|:--------------------------------------| \n| createDate        | setup_smart_card.py                           | Date when document/record was registered on the system.                   | Date Time with Time Zone (ISO Format) |\n| modifiedDate      | access_via_smart_card.py                      | Date whose purpose is to track each document / record update.             | Date Time with Time Zone (ISO Format)                   |\n| firstAccess       | access_via_smart_card.py                      | Date representing the first access to the system via the Smart Card.      | Date Time with Time Zone (ISO Format)                         |\n| lastAccess        | access_via_smart_card.py                      | Date representing the last access to the system via the Smart Card.       | Date Time with Time Zone (ISO Format)                                |\n| smartCardInitDate | setup_smart_card.py                           | Date when the Smart Card was registered on the system.                    | Date Time with Time Zone (ISO Format)                                |\n| smartCardId       | setup_smart_card.py, access_via_smart_card.py | UID (4 byte) of the Smart Card                                            | String                                                               |\n| smartCardEnabled  | setup_smart_card.py, access_via_smart_card.py | Indicates if the Smart Card is enabled (true), false otherwise.           | Boolean                                                              |\n| documentId        | setup_smart_card.py, access_via_smart_card.py | Number (which can also be alphanumeric) of the guest's identity document. | String                                                               |\n| roomNumber        | setup_smart_card.py, access_via_smart_card.py | Number of the assigned room                                               | Int                                                                       |\n| countAccess       | setup_smart_card.py, access_via_smart_card.py | Number of successful accesses.                                            | Int                                                                       |\n| firstName         | setup_smart_card.py                           | Name of the guest to whom the Smart Card is assigned.                     | String                                                                    |\n| lastName          | setup_smart_card.py                           | Lastaname of the guest to whom the Smart Card is assigned.                | String                                                                    |\n\nTable 2 - Data that is stored on the database (MongoDB).\n\n\n## 1. Hardware Requirements\n\n1. [Raspberry Pi 4 Model B 8GByte RAM](https://www.melopero.com/shop/raspberry-pi/boards/raspberry-pi-4-model-b-8gb/?src=raspberrypi)\n2. [MicroSD Card (min 8GByte)](https://www.raspberrypi.com/documentation/computers/getting-started.html#sd-card-for-raspberry-pi)\n3. [Elegoo 4 Channel DC 5V Modulo Relay](https://amzn.to/3rkr4uw)\n4. [Bit4id miniLector CIE](https://shop.bit4id.com/prodotto/minilector-cie/)\n5. [Mifare Classic 1K](https://amzn.to/3vkAifZ)\n6. [Mifare Classic 1K RfId Tag](https://amzn.to/3BReSbF)\n\n## 2. Software Requirements\n\n1. [Raspberry Pi OS (64bit)](https://www.raspberrypi.com/documentation/computers/os.html#introduction)\n2. [Python 3.9.x](https://www.raspberrypi.com/documentation/computers/os.html#python)\n3. [Docker 20.10.12](https://docs.docker.com/engine/install/debian/)\n4. [Development Tools (make, gcc)](https://packages.debian.org/bullseye/build-essential) (install or update via `sudo apt install build-essential`)\n\n## 3. Wiring diagram of the solution\nFigure 4 shows the wiring diagram for connecting the four relay module to the GPIO pins of the Raspberry Pi 4. I \nremember that the Smart Card reader is connected via USB to the Raspberry Pi 4, for this reason it has not been \nincluded in the wiring diagram.\n\n![Wiring diagram Raspberry Pi and Relays Module](docs/images/schematic_smart_card_contactless_raspberry_pi.png)\n\nFigure 4 - Wiring diagram Raspberry Pi and Relays Module\n\n## 4. Quick-start\nThe fundamental steps to be able to try the solution immediately are indicated below.\n1. Login to your Raspberry Pi\n2. Clone project, install the python requirements and prepare MongoDB\n3. Smart Card Initialization\n4. Run the Smart Card Access Tool\n\nTo perform the reading and writing operations on the Smart Card, an authentication key is required, the default value \nis `FFFFFFFFFFFF`. This key must be passed to both Python scripts via the `-a` or `--authentication-key` option. For \ndetails on accepted options, use the `-h` or `--help` option.\n\n```bash\n# 1. Clone the repository\n$ git clone https://github.com/amusarra/smartcard-contactless-raspberry-pi.git\n$ cd smartcard-contactless-raspberry-pi\n\n# 2. Install the Python requirements\n$ make\n\n# 3. Docker pull and run MongoDB 4.4.12\n$ docker pull mongo:4.4.12\n$ docker run -d -p 27017-27019:27017-27019 --name mongodb mongo:4.4.12\n\n# 4. Check MongoDB logs and howto access to the MongoDB console (optional task)\n$ docker exec -it mongodb bash\n\n# Inside the MongoDB Docker Container\nroot@0d21da235b0d:/# mongo\n```\nConsole 1 - Clone project, install the python requirements and prepare MongoDB\n\n\n```bash\n# 1. Smart Card Initialization\n#   a) Store Identity document number (example: identity card, driving license, \n#      social security number, passport number) on Smart Card\n#   b) Association of the Smart Card to the specific person and assignment of the room.\n$ cd smartcard-contactless-raspberry-pi\n\n# Setup Smart Card for Antonio Musarra with identity card DA789876DF and assign room number one (1) \n$ ./setup_smart_card.py -a FFFFFFFFFFFF -i DA789876DF -s --firstname Antonio --lastname Musarra -r 1\n```\nConsole 2 - Smart Card Initialization\n\n\n![Smart Card Init Tool](docs/images/initialize_smart_card_1.png)\nFigure 1 - Run the Smart Card Init Tool to init the first Smart Card\n\n```bash\n# 1. Run the mongo console from Docker Container\nroot@0d21da235b0d:/# mongo\n\n# 2. Use the SmartCardAccessCrudDB and view the SmartCardAccess collection\n\u003e use SmartCardAccessCrudDB\n\u003e db.SmartCardAccess.find().pretty()\n{\n\t\"_id\" : ObjectId(\"62195fbf93c42ff88754734e\"),\n\t\"createDate\" : \"2022-02-25T23:01:19.682355Z\",\n\t\"firstname\" : \"Antonio\",\n\t\"lastname\" : \"Musarra\",\n\t\"documentId\" : \"DA789876DF\",\n\t\"smartCardEnabled\" : \"true\",\n\t\"smartCardId\" : \"B4 90 90 1E\",\n\t\"smartCardInitDate\" : \"2022-02-25T23:01:19.682582Z\",\n\t\"roomNumber\" : 1,\n\t\"countAccess\" : 0\n}\n```\nConsole 3 - Check entry on MongoDB\n\n```bash\n# 1. Start the Smart Card Access Tool\n#   a) Read the Identification Number from Smart Card\n#   b) Check on MongoDB if the Smart Card is paired and enabled\n#   c) If the association is valid then it opens the door of the room to \n#      which the card is associated. Opening corresponds to the activation \n#      of the relay which is deactivated after five seconds.\n$ cd smartcard-contactless-raspberry-pi\n\n# Run the Smart Card Access Tool\n$ ./access_via_smart_card.py -a FFFFFFFFFFFF\n```\nConsole 4 - Run the Smart Card Access Tool\n\n![Run Smart Card Access Tool](docs/images/run_smart_card_access_tool_1.png)\nFigure 2 - Run the Smart Card Access Tool\n\n```bash\n\u003e db.SmartCardAccess.find().pretty()\n{\n\t\"_id\" : ObjectId(\"62195fbf93c42ff88754734e\"),\n\t\"createDate\" : \"2022-02-25T23:01:19.682355Z\",\n\t\"firstname\" : \"Antonio\",\n\t\"lastname\" : \"Musarra\",\n\t\"documentId\" : \"DA789876DF\",\n\t\"smartCardEnabled\" : \"true\",\n\t\"smartCardId\" : \"B4 90 90 1E\",\n\t\"smartCardInitDate\" : \"2022-02-25T23:01:19.682582Z\",\n\t\"roomNumber\" : 1,\n\t\"countAccess\" : 5,\n\t\"firstAccess\" : \"2022-02-25T23:15:36.523275Z\",\n\t\"lastAccess\" : \"2022-02-25T23:27:33.645680Z\",\n\t\"modifiedDate\" : \"2022-02-25T23:27:33.645727Z\"\n}\n{\n\t\"_id\" : ObjectId(\"62196645c6b265cd472d58ca\"),\n\t\"createDate\" : \"2022-02-25T23:29:09.869289Z\",\n\t\"firstname\" : \"Valentina\",\n\t\"lastname\" : \"Musarra\",\n\t\"documentId\" : \"MU589876XD\",\n\t\"smartCardEnabled\" : \"true\",\n\t\"smartCardId\" : \"13 9E 55 73\",\n\t\"smartCardInitDate\" : \"2022-02-25T23:29:09.869317Z\",\n\t\"roomNumber\" : 2,\n\t\"countAccess\" : 3,\n\t\"firstAccess\" : \"2022-02-25T23:29:18.392172Z\",\n\t\"lastAccess\" : \"2022-02-25T23:29:40.846213Z\",\n\t\"modifiedDate\" : \"2022-02-25T23:29:40.846276Z\"\n}\n```\nConsole 5 - Data display to check for updates following accesses\n\nThe following two animations show the Smart Tool Init and the Smart Card Access Tool in action, making the operation and \nprocesses indicated above clearer.\n\n![Run Smart Card Init Tool](docs/images/gif/setup_mifare_classic_1k_smart_card_speed_x2.gif)\n\nAnimation 1 - Smart Card Init tool in action (on asciinema https://asciinema.org/a/475795)\n\n\n![Run Smart Card Access Tool](docs/images/gif/access_control_mifare_classic_1k_smart_card_speed_x2.gif)\n\nAnimation 2 - Smart Card Access tool in action (on asciiname https://asciinema.org/a/475797)\n\n## 5. Documentation\nThe documentation of the project is available in the `docs` folder. The documentation is written in Markdown format\nand can be read directly on GitHub pages at the following link: [Smart Card Contactless Raspberry Pi GitHub Pages](https://amusarra.github.io/smartcard-contactless-raspberry-pi/)\n\nAlso, the documentation is available in PDF format at the following link: [eBook - Smart Card Contactless Raspberry Pi](https://bit.ly/3LkpkOt).\nThe source code of the documentation is available in the `docs/asciidoc` folder of the project.\n\nThe GitHub Pages are generated using the [MkDocs](https://www.mkdocs.org/) tool and the \n[Material for MkDocs](https://squidfunk.github.io/mkdocs-material/) theme using the GitHub Actions workflow\ndefined in the `.github/workflows/publish_doc_to_gh_pages.yml` file.\n\nThe eBook is generated using the [Asciidoctor](https://asciidoctor.org/) tool and in particular the Asciidoctor PDF.\nThe requirement to generate the PDF is to have the Asciidoctor PDF; the instructions for installing this tool are\navailable at the following link: [Asciidoctor PDF](https://docs.asciidoctor.org/pdf-converter/latest/install/).\n\nThe command to generate the PDF is as follows:\n\n```bash\n# Generate the PDF. The command must be executed from the root of the project.\n# The output file is saved in the docs/asciidoc folder.\n# The \u003cebook-file-name.pdf\u003e must be replaced with the desired name of the PDF file.\nasciidoctor-pdf -o docs/asciidoc/\u003cebook-file-name.pdf\u003e docs/asciidoc/index.adoc\n```\nConsole 6 - Generate the PDF of the documentation\n\nAlso, exist the GitHub Actions workflow defined in the `.github/workflows/generate-pdf.yml` file that generates the PDF\nof the documentation and commits it to the repository in the `docs/asciidoc` folder.","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famusarra%2Fsmartcard-contactless-raspberry-pi","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Famusarra%2Fsmartcard-contactless-raspberry-pi","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Famusarra%2Fsmartcard-contactless-raspberry-pi/lists"}