Skip to content

Commit 4ef69e4

Browse files
ZontexZontex
committed
Update README.md
1 parent e6edaa2 commit 4ef69e4

File tree

1 file changed

+64
-132
lines changed

1 file changed

+64
-132
lines changed

‎README.md‎

Lines changed: 64 additions & 132 deletions
Original file line numberDiff line numberDiff line change
@@ -1,151 +1,83 @@
1-
# Python RC522 library
1+
# RC522-Python library
22

3+
This library is the combination of 2 legacy libraries that were developed by Mario Gomez and Ondřej Ondryáš.
4+
5+
The pirc522 library by Ondřej Ondryáš contained a full package that can be easily installed into the raspberry pi.
6+
7+
The MFRC522-Python script by Mario Gomez is another very nice code, written into MFRC522.py file that should be imported every time from the same directory.
8+
9+
The pirc522 library stopped working due to changes in the raspberry pi system but the MFRC522 kept on working perfectly well.
10+
We at STEMinds combined both libraries, the pirc522 easy package with the MFRC522-Python working code to create an update RC-522 library for the Raspbrrry Pi
311

412
## About MFRC522-python
513

614
A small class to interface with the NFC reader Module MFRC522 on the Raspberry Pi. This is a Python port of the example code for the NFC module MF522-AN.
15+
Git link for the official MFRC522 library: https://github.com/mxgxw/MFRC522-python
16+
17+
## About pirc522
18+
19+
pi-rc522 consists of two Python classes for controlling an SPI RFID module "RC522" using Raspberry Pi or Beaglebone Black. You can get this module on AliExpress or Ebay for $3.
20+
21+
pi-rc522 is based on [MFRC522-python](https://github.com/mxgxw/MFRC522-python/blob/master/README.md).
22+
23+
Note: begale-bone support removed at RC522-Python library.
724

825
## Requirements
926

1027
The software requires a version of SPI-Py, find it in the SPI-Py folder
1128
To install, from this folder run the following commands:
1229
Or get source code from Github:
30+
1331
```
1432
cd SPI-Py
1533
sudo python3 setup.py install
1634
```
17-
pi-rc522 consists of two Python classes for controlling an SPI RFID module "RC522" using Raspberry Pi or Beaglebone Black. You can get this module on AliExpress or Ebay for $3.
1835

19-
Based on [MFRC522-python](https://github.com/mxgxw/MFRC522-python/blob/master/README.md).
36+
The SPI-Py is not related to RC522-Python and includes separated license.
2037

21-
Install using pip:
22-
```
23-
pip install pi-rc522
24-
```
38+
## Examples
39+
This repository includes a couple of examples showing how to read, write, and dump data from a chip. They are thoroughly commented, and should be easy to understand.
2540

26-
Or get source code from Github:
27-
```
28-
git clone https://github.com/ondryaso/pi-rc522.git
29-
cd pi-rc522
30-
python setup.py install
31-
```
32-
You'll also need to install the [**spidev**](https://pypi.python.org/pypi/spidev) and [**RPi.GPIO**](https://pypi.python.org/pypi/RPi.GPIO) libraries on Raspberry PI, and [**Adafruit_BBIO**](https://github.com/adafruit/adafruit-beaglebone-io-python) on Beaglebone Black (which should be installed by default).
33-
34-
[MIFARE datasheet](https://www.nxp.com/docs/en/data-sheet/MF1S50YYX_V1.pdf) can be useful.
35-
36-
## Sectors? Blocks?
37-
Classic 1K MIFARE tag has **16 sectors**, each contains **4 blocks**. Each block has 16 bytes. All this stuff is indexed - you must count from zero. The library uses "**block addresses**", which are positions of blocks - so block address 5 is second block of second sector, thus it's block 1 of sector 1 (indexes). Block addresses 0, 1, 2, 3 are from the first sector - sector 0. Block addresses 4, 5, 6, 7 are from the second sector - sector 1, and so on. You should **not write** to first block - S0B0, because it contains manufacturer data. Each sector has it's **sector trailer**, which is located at it's last block - block 3. This block contains keys and access bits for corresponding sector. For more info, look at page 10 of the datasheet. You can use [this](http://www.proxmark.org/forum/viewtopic.php?id=1408) useful utility to calculate access bits.
38-
39-
## Connecting
40-
Connecting RC522 module to SPI is pretty easy. You can use [this neat website](http://pi.gadgetoid.com/pinout) for reference.
41-
42-
| Board pin name | Board pin | Physical RPi pin | RPi pin name | Beaglebone Black pin name |
43-
|----------------|-----------|------------------|--------------| --------------------------|
44-
| SDA | 1 | 24 | GPIO8, CE0 | P9\_17, SPI0\_CS0 |
45-
| SCK | 2 | 23 | GPIO11, SCKL | P9\_22, SPI0\_SCLK |
46-
| MOSI | 3 | 19 | GPIO10, MOSI | P9\_18, SPI0\_D1 |
47-
| MISO | 4 | 21 | GPIO9, MISO | P9\_21, SPI0\_D0 |
48-
| IRQ | 5 | 18 | GPIO24 | P9\_15, GPIO\_48 |
49-
| GND | 6 | 6, 9, 20, 25 | Ground | Ground |
50-
| RST | 7 | 22 | GPIO25 | P9\_23, GPIO\_49 |
51-
| 3.3V | 8 | 1,17 | 3V3 | VDD\_3V3 |
52-
53-
You can also connect the SDA pin to CE1 (GPIO7, pin #26) and call the RFID constructor with *bus=0, device=1*
54-
and you can connect RST pin to any other free GPIO pin and call the constructor with *pin_rst=__BOARD numbering pin__*.
55-
Furthermore, the IRQ pin is configurable by passing *pin_irq=__BOARD numbering pin__*.
56-
57-
__NOTE:__ For RPi A+/B+/2/3 with 40 pin connector, SPI1/2 is available on top of SPI0. Kernel 4.4.x or higher and *dtoverlay* configuration is required. For SPI1/2, *pin_ce=__BOARD numbering pin__* is required.
58-
59-
__NOTE:__ On Beaglebone Black, use pin names (e.g. `"P9_17"`).
60-
61-
__NOTE:__ On Beaglebone Black, generally you have to enable the SPI for the spidev device to show up; you can enable SPI0 by doing `echo BB-SPIDEV0 > /sys/devices/bone_capemgr.9/slots`. SPI1 is available *only if you disable HDMI*.
62-
63-
You may change BOARD pinout to BCM py passing *pin_mode=RPi.GPIO.BCM*. Please note, that you then have to define all pins (irq+rst, ce if neccessary). Otherwise they would default to perhaps wrong pins (rst to pin 15/GPIO22, irq to pin 12/GPIO18).
64-
65-
## Usage
66-
The library is split to two classes - **RFID** and **RFIDUtil**. You can use only RFID, RFIDUtil just makes life a little bit better.
67-
You basically want to start with *while True* loop and "poll" the tag state. That's done using *request* method. Most of the methods
68-
return error state, which is simple boolean - True is error, False is not error. The *request* method returns True if tag is **not**
69-
present. If request is successful, you should call *anticoll* method. It runs anti-collision algorithms and returns used tag UID, which
70-
you'll use for *select_tag* method. Now you can do whatever you want. Important methods are documented. You can also look at the Read and KeyChange examples for RFIDUtil usage.
71-
72-
```python
73-
from pirc522 import RFID
74-
rdr = RFID()
75-
76-
while True:
77-
rdr.wait_for_tag()
78-
(error, tag_type) = rdr.request()
79-
if not error:
80-
print("Tag detected")
81-
(error, uid) = rdr.anticoll()
82-
if not error:
83-
print("UID: " + str(uid))
84-
# Select Tag is required before Auth
85-
if not rdr.select_tag(uid):
86-
# Auth for block 10 (block 2 of sector 2) using default shipping key A
87-
if not rdr.card_auth(rdr.auth_a, 10, [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF], uid):
88-
# This will print something like (False, [0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0])
89-
print("Reading block 10: " + str(rdr.read(10)))
90-
# Always stop crypto1 when done working
91-
rdr.stop_crypto()
92-
93-
# Calls GPIO cleanup
94-
rdr.cleanup()
95-
```
41+
## Pins
42+
You can use [this](http://i.imgur.com/y7Fnvhq.png) image for reference.
9643

97-
### Util usage
98-
**RFIDUtil** contains a few useful methods for dealing with tags.
99-
100-
```python
101-
from pirc522 import RFID
102-
import signal
103-
import time
104-
105-
rdr = RFID()
106-
util = rdr.util()
107-
# Set util debug to true - it will print what's going on
108-
util.debug = True
109-
110-
while True:
111-
# Wait for tag
112-
rdr.wait_for_tag()
113-
114-
# Request tag
115-
(error, data) = rdr.request()
116-
if not error:
117-
print("\nDetected")
118-
119-
(error, uid) = rdr.anticoll()
120-
if not error:
121-
# Print UID
122-
print("Card read UID: "+str(uid[0])+","+str(uid[1])+","+str(uid[2])+","+str(uid[3]))
123-
124-
# Set tag as used in util. This will call RFID.select_tag(uid)
125-
util.set_tag(uid)
126-
# Save authorization info (key B) to util. It doesn't call RFID.card_auth(), that's called when needed
127-
util.auth(rdr.auth_b, [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF])
128-
# Print contents of block 4 in format "S1B0: [contents in decimal]". RFID.card_auth() will be called now
129-
util.read_out(4)
130-
# Print it again - now auth won't be called, because it doesn't have to be
131-
util.read_out(4)
132-
# Print contents of different block - S1B2 - RFID.card_auth() will be called again
133-
util.read_out(6)
134-
# We can change authorization info if you have different key in other sector
135-
util.auth(rdr.auth_a, [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF])
136-
#If you want to use methods from RFID itself, you can use this for authorization
137-
# This will authorize for block 1 of sector 2 -> block 9
138-
# This is once more called only if it's not already authorized for this block
139-
util.do_auth(util.block_addr(2, 1))
140-
# Now we can do some "lower-level" stuff with block 9
141-
rdr.write(9, [0x01, 0x23, 0x45, 0x67, 0x89, 0x98, 0x76, 0x54, 0x32, 0x10, 0x69, 0x27, 0x46, 0x66, 0x66, 0x64])
142-
# We can rewrite specific bytes in block using this method. None means "don't change this byte"
143-
# Note that this won't do authorization, because we've already called do_auth for block 9
144-
util.rewrite(9, [None, None, 0xAB, 0xCD, 0xEF])
145-
# This will write S2B1: [0x01, 0x23, 0xAB, 0xCD, 0xEF, 0x98, 0x76......] because we've rewritten third, fourth and fifth byte
146-
util.read_out(9)
147-
# Let's see what do we have in whole tag
148-
util.dump()
149-
# We must stop crypto
150-
util.deauth()
151-
```
44+
| Name | Pin # | Pin name |
45+
|:------:|:-------:|:------------:|
46+
| SDA | 24 | GPIO8 |
47+
| SCK | 23 | GPIO11 |
48+
| MOSI | 19 | GPIO10 |
49+
| MISO | 21 | GPIO9 |
50+
| IRQ | None | None |
51+
| GND | Any | Any Ground |
52+
| RST | 22 | GPIO25 |
53+
| 3.3V | 1 | 3V3 |
54+
55+
56+
## License
57+
58+
This Repository is licensed under GNU LESSER GENERAL PUBLIC LICENSE.
59+
The repository is based on pi-rc522 which is licensed under MIT and MFRC522-Python which is based on GNU.
60+
because pi-rc522 to begin with is based on MFRC522-Python which is licensed under GNU, this library will also be licensed under GNU.
61+
62+
Copyright 2014,2018 Mario Gomez <[email protected]> for MFRC522-Python
63+
Copyright (c) 2016 Ondřej Ondryáš {ondryaso} for pi-rc522
64+
Copyright (c) 2020 STEMinds for modifications and combining both libraries
65+
66+
This file contains parts from MFRC522-Python and pi-rc522
67+
MFRC522-Python and pi-rc522 is a simple Python implementation for
68+
the MFRC522 NFC Card Reader for the Raspberry Pi.
69+
70+
MFRC522-Python and pi-rc522 are free software: you can redistribute it and/or modify
71+
it under the terms of the GNU Lesser General Public License as published by
72+
the Free Software Foundation, either version 3 of the License, or (at your option) any later version.
73+
74+
MFRC522-Python and pi-rc522 is distributed in the hope that it will be useful,
75+
but WITHOUT ANY WARRANTY; without even the implied warranty of
76+
MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the
77+
GNU Lesser General Public License for more details.
78+
79+
You should have received a copy of the GNU Lesser General Public License
80+
along with MFRC522-Python and pi-rc522. If not, see <http://www.gnu.org/licenses/>.
81+
82+
Original git of MFRC522-Python: [MFRC522-python](https://github.com/mxgxw/MFRC522-python).
83+
Original git of pi-rc522: [pi-rc522](https://github.com/ondryaso/pi-rc522).

0 commit comments

Comments
 (0)