| Name | razrc522 JSON |
| Version |
1.0.0
JSON |
| download |
| home_page | None |
| Summary | Modern Python library for RC522 RFID reader - updated for current Python and kernel versions 6+ |
| upload_time | 2025-08-17 21:15:21 |
| maintainer | None |
| docs_url | None |
| author | None |
| requires_python | >=3.7 |
| license | MIT |
| keywords |
gpio
raspberry-pi
rc522
rfid
spi
|
| VCS |
 |
| bugtrack_url |
|
| requirements |
No requirements were recorded.
|
| Travis-CI |
No Travis.
|
| coveralls test coverage |
No coveralls.
|
# razrc522
Modern Python library for RC522 RFID reader - updated for current Python and kernel versions 6+
## About
This is a modernized repository of the original [pi-rc522](https://github.com/ondryaso/pi-rc522) library with significant improvements:
- **Modern GPIO handling** - Rewritten to use current `gpiozero` and `lgpio` libraries instead of deprecated RPi.GPIO
- **Simplified API** - Easy-to-use `EasyRFID` wrapper class for common operations
- **Multiple UID formats** - Support for various UID output modes (HEX, decimal, binary, base64, etc.)
- **IRQ support** - Optimized for RC522 modules with interrupt pin for efficient tag detection
- **Python 3.7+ compatibility** - Updated for modern Python versions
- **Kernel 6+ support** - Works with latest Raspberry Pi OS releases and Compute Module 4/5
- **Better error handling** - Simple boolean returns instead of complex error tuples like original's `(error, data, length)`
- **Production ready** - Designed for real-world applications, not just prototypes
## Hardware Compatibility
This library is specifically designed for RC522 RFID modules with IRQ pin support.
### Recommended Hardware
**[Compute Module 4/5 Production Base Board with RFID](https://shop.razniewski.eu/products/compute-module-4-5-production-base-board-with-rfid-hdmi-usb-rtc)** - Professional development board specifically designed for RFID applications:
**Hardware Features:**
- **Dedicated SPI RFID connector** - TE Connectivity 3-640621-8 with all required lines (MISO, MOSI, SCK, SDA, IRQ, RST, 3V3, GND)
- **No wiring required** - Direct plug-and-play compatibility with RC522 modules
- **Production-grade components** - 100Mb/s Ethernet, USB-C power, HDMI output, RTC with battery backup
- **Compact design** - 64.5×92.6×15.2mm, perfect for enclosure mounting
- **Built-in signaling** - Buzzer and programmable GPIO for status indication
**Software Integration:**
- **Perfect pin mapping** - Default configuration matches this library exactly
- **Sample applications included** - REST API software for immediate deployment
- **CM4/5 eMMC support** - Industrial-grade storage for production applications
**Ideal Use Cases:**
- Access control and time registration systems
- IoT devices with RFID authentication
- Industrial terminals and kiosks
- Prototype-to-production development
*While this library works with any RC522 setup, the above board eliminates wiring complexity and provides a complete hardware platform for professional RFID applications.*
### Default Pin Configuration
- RST: GPIO 22
- CE: GPIO 0 (CE0)
- IRQ: GPIO 18
- SPI: Default SPI0 (MOSI=GPIO 10, MISO=GPIO 9, SCLK=GPIO 11)
## Installation
```bash
pip install razrc522
```
## Quick Start
### Simple UID Reading
```python
from razrc522.rfid import RFID
from razrc522.easyrfid import EasyRFID, EasyRFIDUIDMode
# Initialize reader
reader = RFID()
easy_rfid = EasyRFID(reader, mode=EasyRFIDUIDMode.HEX)
# Read UID in different formats
while True:
uid = easy_rfid.wait_and_read_uid()
print(f"Card UID: {uid}")
```
### Reading and Writing Data
```python
from razrc522.rfid import RFID
from razrc522.easyrfid import EasyRFID, EasyRFIDUIDMode, EasyRFIDAuth
reader = RFID(antenna_gain=7)
easy_rfid = EasyRFID(reader, mode=EasyRFIDUIDMode.HEX)
while True:
# Wait for card and select it
uid, raw_uid = easy_rfid.wait_and_select()
print(f"Selected card: {uid}")
# Authorize with default MIFARE key
block = 8
if easy_rfid.authorize(EasyRFIDAuth.AuthB, [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF], raw_uid, block):
# Read block
data = easy_rfid.read_block(block)
if data:
text = easy_rfid.bytes_to_uid(data, EasyRFIDUIDMode.STRING)
print(f"Block {block} contains: {text}")
# Write data (16 bytes required)
message = b"Hello RFID World!"[:16].ljust(16, b'\x00')
if easy_rfid.write_block(block, message):
print("Write successful!")
```
## UID Output Modes
The `EasyRFIDUIDMode` enum supports various output formats:
- `HEX` - Hexadecimal string (e.g., "a1b2c3d4")
- `HEX_BACKWARD` - Reversed hexadecimal
- `DECIMAL` - Decimal string
- `BINARY` - Binary string
- `BASE64` - Base64 encoded
- `INT_LIST` - List of integers (default)
- `STRING` - ASCII string representation
- `RAW` - Raw bytes object
```python
# Switch between modes dynamically
easy_rfid.set_new_mode(EasyRFIDUIDMode.DECIMAL)
uid_decimal = easy_rfid.wait_and_read_uid()
# Or convert existing data
hex_uid = easy_rfid.bytes_to_uid([161, 178, 195, 212], EasyRFIDUIDMode.HEX)
```
## Advanced Configuration
### Custom Pin Setup
```python
reader = RFID(
bus=0, # SPI bus
device=0, # SPI device
speed=1000000, # SPI speed
pin_rst=22, # Reset pin
pin_ce=0, # Chip enable pin
pin_irq=18, # Interrupt pin
antenna_gain=7, # Antenna gain (0-7)
logger=None # Custom logger
)
```
### Antenna Gain Settings
The antenna gain affects the reading range:
- 0: 18 dB
- 1: 23 dB
- 2: 18 dB
- 3: 23 dB
- 4: 33 dB (default)
- 5: 38 dB
- 6: 43 dB
- 7: 48 dB (maximum range)
## Examples
See the `examples/` directory for complete working examples:
- `read_uid_modes.py` - Demonstrates all UID output modes
- `read_full_0.py` - Reading card data with authentication
- `write.py` - Writing data to cards with random content
## Requirements
- Python 3.7+
- Raspberry Pi with SPI enabled
- RC522 RFID module with IRQ pin connected
- Linux kernel 6+ (for modern GPIO support)
## Dependencies
- `gpiozero==2.0.1` - Modern GPIO control
- `spidev==3.7` - SPI communication
- `lgpio==0.2.2.0` - Low-level GPIO access
## License
MIT License - see LICENSE file for details.
## Contributing
Issues and pull requests welcome! This library aims to provide a simple, modern interface for RC522 RFID operations on Raspberry Pi.
## Credits
- Original [pi-rc522](https://github.com/ondryaso/pi-rc522) by Ondřej Ondryáš
- Modernized and extended by Adam Raźniewski
---
*For more hardware solutions and Raspberry Pi accessories, visit [razniewski.eu](https://shop.razniewski.eu)*
Raw data
{
"_id": null,
"home_page": null,
"name": "razrc522",
"maintainer": null,
"docs_url": null,
"requires_python": ">=3.7",
"maintainer_email": null,
"keywords": "gpio, raspberry-pi, rc522, rfid, spi",
"author": null,
"author_email": "Adam Ra\u017aniewski <adam@razniewski.eu>, Ond\u0159ej Ondry\u00e1\u0161 <ondryaso@ondryaso.eu>",
"download_url": "https://files.pythonhosted.org/packages/1d/11/a40be43f7f1386c483bb20d961728abf3cf22764036cb57e3b4efcad9b0e/razrc522-1.0.0.tar.gz",
"platform": null,
"description": "# razrc522\n\nModern Python library for RC522 RFID reader - updated for current Python and kernel versions 6+\n\n## About\n\nThis is a modernized repository of the original [pi-rc522](https://github.com/ondryaso/pi-rc522) library with significant improvements:\n\n- **Modern GPIO handling** - Rewritten to use current `gpiozero` and `lgpio` libraries instead of deprecated RPi.GPIO\n- **Simplified API** - Easy-to-use `EasyRFID` wrapper class for common operations\n- **Multiple UID formats** - Support for various UID output modes (HEX, decimal, binary, base64, etc.)\n- **IRQ support** - Optimized for RC522 modules with interrupt pin for efficient tag detection\n- **Python 3.7+ compatibility** - Updated for modern Python versions\n- **Kernel 6+ support** - Works with latest Raspberry Pi OS releases and Compute Module 4/5\n- **Better error handling** - Simple boolean returns instead of complex error tuples like original's `(error, data, length)`\n- **Production ready** - Designed for real-world applications, not just prototypes \n\n## Hardware Compatibility\n\nThis library is specifically designed for RC522 RFID modules with IRQ pin support. \n\n### Recommended Hardware\n\n**[Compute Module 4/5 Production Base Board with RFID](https://shop.razniewski.eu/products/compute-module-4-5-production-base-board-with-rfid-hdmi-usb-rtc)** - Professional development board specifically designed for RFID applications:\n\n**Hardware Features:**\n- **Dedicated SPI RFID connector** - TE Connectivity 3-640621-8 with all required lines (MISO, MOSI, SCK, SDA, IRQ, RST, 3V3, GND)\n- **No wiring required** - Direct plug-and-play compatibility with RC522 modules\n- **Production-grade components** - 100Mb/s Ethernet, USB-C power, HDMI output, RTC with battery backup\n- **Compact design** - 64.5\u00d792.6\u00d715.2mm, perfect for enclosure mounting\n- **Built-in signaling** - Buzzer and programmable GPIO for status indication\n\n**Software Integration:**\n- **Perfect pin mapping** - Default configuration matches this library exactly\n- **Sample applications included** - REST API software for immediate deployment\n- **CM4/5 eMMC support** - Industrial-grade storage for production applications\n\n**Ideal Use Cases:**\n- Access control and time registration systems\n- IoT devices with RFID authentication\n- Industrial terminals and kiosks\n- Prototype-to-production development\n\n*While this library works with any RC522 setup, the above board eliminates wiring complexity and provides a complete hardware platform for professional RFID applications.*\n\n### Default Pin Configuration\n- RST: GPIO 22\n- CE: GPIO 0 (CE0)\n- IRQ: GPIO 18\n- SPI: Default SPI0 (MOSI=GPIO 10, MISO=GPIO 9, SCLK=GPIO 11)\n\n## Installation\n\n```bash\npip install razrc522\n```\n\n## Quick Start\n\n### Simple UID Reading\n\n```python\nfrom razrc522.rfid import RFID\nfrom razrc522.easyrfid import EasyRFID, EasyRFIDUIDMode\n\n# Initialize reader\nreader = RFID()\neasy_rfid = EasyRFID(reader, mode=EasyRFIDUIDMode.HEX)\n\n# Read UID in different formats\nwhile True:\n uid = easy_rfid.wait_and_read_uid()\n print(f\"Card UID: {uid}\")\n```\n\n### Reading and Writing Data\n\n```python\nfrom razrc522.rfid import RFID\nfrom razrc522.easyrfid import EasyRFID, EasyRFIDUIDMode, EasyRFIDAuth\n\nreader = RFID(antenna_gain=7)\neasy_rfid = EasyRFID(reader, mode=EasyRFIDUIDMode.HEX)\n\nwhile True:\n # Wait for card and select it\n uid, raw_uid = easy_rfid.wait_and_select()\n print(f\"Selected card: {uid}\")\n \n # Authorize with default MIFARE key\n block = 8\n if easy_rfid.authorize(EasyRFIDAuth.AuthB, [0xFF, 0xFF, 0xFF, 0xFF, 0xFF, 0xFF], raw_uid, block):\n # Read block\n data = easy_rfid.read_block(block)\n if data:\n text = easy_rfid.bytes_to_uid(data, EasyRFIDUIDMode.STRING)\n print(f\"Block {block} contains: {text}\")\n \n # Write data (16 bytes required)\n message = b\"Hello RFID World!\"[:16].ljust(16, b'\\x00')\n if easy_rfid.write_block(block, message):\n print(\"Write successful!\")\n```\n\n## UID Output Modes\n\nThe `EasyRFIDUIDMode` enum supports various output formats:\n\n- `HEX` - Hexadecimal string (e.g., \"a1b2c3d4\")\n- `HEX_BACKWARD` - Reversed hexadecimal\n- `DECIMAL` - Decimal string\n- `BINARY` - Binary string\n- `BASE64` - Base64 encoded\n- `INT_LIST` - List of integers (default)\n- `STRING` - ASCII string representation\n- `RAW` - Raw bytes object\n\n```python\n# Switch between modes dynamically\neasy_rfid.set_new_mode(EasyRFIDUIDMode.DECIMAL)\nuid_decimal = easy_rfid.wait_and_read_uid()\n\n# Or convert existing data\nhex_uid = easy_rfid.bytes_to_uid([161, 178, 195, 212], EasyRFIDUIDMode.HEX)\n```\n\n## Advanced Configuration\n\n### Custom Pin Setup\n\n```python\nreader = RFID(\n bus=0, # SPI bus\n device=0, # SPI device\n speed=1000000, # SPI speed\n pin_rst=22, # Reset pin\n pin_ce=0, # Chip enable pin\n pin_irq=18, # Interrupt pin\n antenna_gain=7, # Antenna gain (0-7)\n logger=None # Custom logger\n)\n```\n\n### Antenna Gain Settings\n\nThe antenna gain affects the reading range:\n\n- 0: 18 dB\n- 1: 23 dB\n- 2: 18 dB\n- 3: 23 dB\n- 4: 33 dB (default)\n- 5: 38 dB\n- 6: 43 dB\n- 7: 48 dB (maximum range)\n\n## Examples\n\nSee the `examples/` directory for complete working examples:\n\n- `read_uid_modes.py` - Demonstrates all UID output modes\n- `read_full_0.py` - Reading card data with authentication\n- `write.py` - Writing data to cards with random content\n\n## Requirements\n\n- Python 3.7+\n- Raspberry Pi with SPI enabled\n- RC522 RFID module with IRQ pin connected\n- Linux kernel 6+ (for modern GPIO support)\n\n## Dependencies\n\n- `gpiozero==2.0.1` - Modern GPIO control\n- `spidev==3.7` - SPI communication\n- `lgpio==0.2.2.0` - Low-level GPIO access\n\n## License\n\nMIT License - see LICENSE file for details.\n\n## Contributing\n\nIssues and pull requests welcome! This library aims to provide a simple, modern interface for RC522 RFID operations on Raspberry Pi.\n\n## Credits\n\n- Original [pi-rc522](https://github.com/ondryaso/pi-rc522) by Ond\u0159ej Ondry\u00e1\u0161\n- Modernized and extended by Adam Ra\u017aniewski\n\n---\n\n*For more hardware solutions and Raspberry Pi accessories, visit [razniewski.eu](https://shop.razniewski.eu)*",
"bugtrack_url": null,
"license": "MIT",
"summary": "Modern Python library for RC522 RFID reader - updated for current Python and kernel versions 6+",
"version": "1.0.0",
"project_urls": {
"Documentation": "https://github.com/Razikus/razrc522#readme",
"Homepage": "https://github.com/Razikus/razrc522",
"Issues": "https://github.com/Razikus/razrc522/issues",
"Repository": "https://github.com/Razikus/razrc522.git"
},
"split_keywords": [
"gpio",
" raspberry-pi",
" rc522",
" rfid",
" spi"
],
"urls": [
{
"comment_text": null,
"digests": {
"blake2b_256": "a985f46307539a23e2e412ba818ba96c6ae934c80d9c823f3c41562a551d32bc",
"md5": "d3d07d56eab17cab97689b8edb09c8b5",
"sha256": "a9b22cfa70dfd21745084ae54583c5281c7fb2de8c2c1674b3db388b9c255137"
},
"downloads": -1,
"filename": "razrc522-1.0.0-py3-none-any.whl",
"has_sig": false,
"md5_digest": "d3d07d56eab17cab97689b8edb09c8b5",
"packagetype": "bdist_wheel",
"python_version": "py3",
"requires_python": ">=3.7",
"size": 8877,
"upload_time": "2025-08-17T21:15:20",
"upload_time_iso_8601": "2025-08-17T21:15:20.473849Z",
"url": "https://files.pythonhosted.org/packages/a9/85/f46307539a23e2e412ba818ba96c6ae934c80d9c823f3c41562a551d32bc/razrc522-1.0.0-py3-none-any.whl",
"yanked": false,
"yanked_reason": null
},
{
"comment_text": null,
"digests": {
"blake2b_256": "1d11a40be43f7f1386c483bb20d961728abf3cf22764036cb57e3b4efcad9b0e",
"md5": "b7ab07b84c64c4c45f6bab6dcf831b82",
"sha256": "4e45a41ff520f599f1f02d3b9c4b1132154b9f1e1f3643c0a9a3255d49853e56"
},
"downloads": -1,
"filename": "razrc522-1.0.0.tar.gz",
"has_sig": false,
"md5_digest": "b7ab07b84c64c4c45f6bab6dcf831b82",
"packagetype": "sdist",
"python_version": "source",
"requires_python": ">=3.7",
"size": 7857,
"upload_time": "2025-08-17T21:15:21",
"upload_time_iso_8601": "2025-08-17T21:15:21.487514Z",
"url": "https://files.pythonhosted.org/packages/1d/11/a40be43f7f1386c483bb20d961728abf3cf22764036cb57e3b4efcad9b0e/razrc522-1.0.0.tar.gz",
"yanked": false,
"yanked_reason": null
}
],
"upload_time": "2025-08-17 21:15:21",
"github": true,
"gitlab": false,
"bitbucket": false,
"codeberg": false,
"github_user": "Razikus",
"github_project": "razrc522#readme",
"travis_ci": false,
"coveralls": false,
"github_actions": false,
"lcname": "razrc522"
}
