{"id":29821096,"url":"https://github.com/debugger22/rfid-reader","last_synced_at":"2025-07-28T23:40:19.858Z","repository":{"id":304015560,"uuid":"1017389234","full_name":"debugger22/rfid-reader","owner":"debugger22","description":"Reads RDIF cards and sends a request to the configured webhook","archived":false,"fork":false,"pushed_at":"2025-07-11T07:50:44.000Z","size":41,"stargazers_count":0,"open_issues_count":0,"forks_count":0,"subscribers_count":0,"default_branch":"master","last_synced_at":"2025-07-18T09:09:13.756Z","etag":null,"topics":[],"latest_commit_sha":null,"homepage":null,"language":"Python","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/debugger22.png","metadata":{"files":{"readme":"README.md","changelog":null,"contributing":null,"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":"2025-07-10T13:08:38.000Z","updated_at":"2025-07-10T17:07:41.000Z","dependencies_parsed_at":"2025-07-10T22:58:02.406Z","dependency_job_id":"a3de31f1-9179-4693-ab5c-3ed958f69bea","html_url":"https://github.com/debugger22/rfid-reader","commit_stats":null,"previous_names":["debugger22/rfid-reader"],"tags_count":1,"template":false,"template_full_name":null,"purl":"pkg:github/debugger22/rfid-reader","repository_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debugger22%2Frfid-reader","tags_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debugger22%2Frfid-reader/tags","releases_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debugger22%2Frfid-reader/releases","manifests_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debugger22%2Frfid-reader/manifests","owner_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/owners/debugger22","download_url":"https://codeload.github.com/debugger22/rfid-reader/tar.gz/refs/heads/master","sbom_url":"https://repos.ecosyste.ms/api/v1/hosts/GitHub/repositories/debugger22%2Frfid-reader/sbom","host":{"name":"GitHub","url":"https://github.com","kind":"github","repositories_count":267604819,"owners_count":24114558,"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","status":"online","status_checked_at":"2025-07-28T02:00:09.689Z","response_time":68,"last_error":null,"robots_txt_status":"success","robots_txt_updated_at":"2025-07-24T06:49:26.215Z","robots_txt_url":"https://github.com/robots.txt","online":true,"can_crawl_api":true,"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":[],"created_at":"2025-07-28T23:40:18.839Z","updated_at":"2025-07-28T23:40:19.853Z","avatar_url":"https://github.com/debugger22.png","language":"Python","funding_links":[],"categories":[],"sub_categories":[],"readme":"# RFID Reader for Raspberry Pi\n\nA Python-based RFID reader service for Raspberry Pi that reads RFID cards using the RC522 module and sends data to a webhook endpoint.\n\n## Features\n\n- **RFID Card Reading**: Continuously reads RFID cards using the RC522 module\n- **Webhook Integration**: Sends card data to a configurable webhook URL\n- **Local Database Storage**: SQLite database for storing all card reads with timestamps\n- **Offline Resilience**: Stores events locally when offline and syncs when connection is restored\n- **Retry Logic**: Exponential backoff retry system with up to 1 week persistence\n- **Write-Through Architecture**: All card reads are immediately stored in database\n- **Device ID Management**: Auto-generates unique device IDs or uses configured ones\n- **Background Service**: Runs as a systemd service that starts on boot\n- **Logging**: Comprehensive logging to both file and system journal\n- **Error Handling**: Robust error handling with automatic service restart\n- **Raspbian Compatible**: Designed specifically for Raspberry Pi running Raspbian OS\n\n## Hardware Requirements\n\n- Raspberry Pi (any model)\n- RC522 RFID Reader Module\n- RFID cards/tags\n\n## Wiring Diagram\n\nConnect the RC522 module to your Raspberry Pi as follows:\n\n| RC522 Pin | Raspberry Pi GPIO |\n|-----------|-------------------|\n| SDA       | GPIO 8 (Pin 24)  |\n| SCK       | GPIO 11 (Pin 23) |\n| MOSI      | GPIO 10 (Pin 19) |\n| MISO      | GPIO 9 (Pin 21)  |\n| RST       | GPIO 25 (Pin 22) |\n| VCC       | 3.3V             |\n| GND       | GND              |\n\n## Installation\n\n### Quick Install\n\n1. Clone this repository:\n   ```bash\n   git clone \u003crepository-url\u003e\n   cd rfid-reader\n   ```\n\n2. Run the installation script:\n   ```bash\n   sudo chmod +x install.sh\n   sudo ./install.sh\n   ```\n\n### Manual Installation\n\n1. Install system dependencies:\n   ```bash\n   sudo apt-get update\n   sudo apt-get install python3-pip python3-dev python3-venv\n   ```\n\n2. Create virtual environment and install dependencies:\n   ```bash\n   sudo mkdir -p /opt/rfid_reader\n   sudo python3 -m venv /opt/rfid_reader/venv\n   sudo /opt/rfid_reader/venv/bin/pip install -r requirements.txt\n   ```\n\n3. Copy files to system locations:\n   ```bash\n   sudo mkdir -p /etc/rfid_reader\n   sudo cp rfid_reader.py /usr/local/bin/\n   sudo cp db_manager.py /usr/local/bin/\n   sudo cp config.toml /etc/rfid_reader/\n   sudo cp rfid-reader.service /etc/systemd/system/\n   sudo chmod +x /usr/local/bin/rfid_reader.py\n   sudo chmod +x /usr/local/bin/db_manager.py\n   \n   # Update shebang to use virtual environment\n   sudo sed -i '1s|#!/usr/bin/env python3|#!/opt/rfid_reader/venv/bin/python|' /usr/local/bin/rfid_reader.py\n   sudo sed -i '1s|#!/usr/bin/env python3|#!/opt/rfid_reader/venv/bin/python|' /usr/local/bin/db_manager.py\n   ```\n\n4. Enable SPI interface:\n   ```bash\n   echo \"dtparam=spi=on\" | sudo tee -a /boot/config.txt\n   ```\n\n5. Enable and start the service:\n   ```bash\n   sudo systemctl daemon-reload\n   sudo systemctl enable rfid-reader.service\n   sudo systemctl start rfid-reader.service\n   ```\n\n## Configuration\n\nEdit the configuration file at `/etc/rfid_reader/config.toml`:\n\n```toml\n# Device ID (auto-generated if not set)\n# device_id = \"your_device_id_here\"\n\n# Webhook URL to send RFID data\nwebhook_url = \"https://your-webhook-endpoint.com/rfid\"\n\n# API Key for webhook authentication (optional)\n# api_key = \"your_api_key_here\"\n\n# Optional: GPIO pins for RC522 (default values)\n# sda_pin = 8\n# sck_pin = 11\n# mosi_pin = 10\n# miso_pin = 9\n# rst_pin = 25\n\n# Optional: Logging level\n# log_level = \"INFO\"\n```\n\n### Configuration Options\n\n- **device_id**: Unique identifier for this device. If not set, a unique ID will be generated based on hardware information.\n- **webhook_url**: URL where RFID data will be sent via POST requests.\n- **api_key**: API key for webhook authentication. If set, will be included as `x-api-key` header.\n- **GPIO pins**: Customize the GPIO pins used for the RC522 module (optional).\n- **log_level**: Set logging verbosity (DEBUG, INFO, WARNING, ERROR).\n\n## Webhook Data Format\n\nThe service sends POST requests to your webhook URL with the following JSON payload:\n\n```json\n{\n  \"device_id\": \"abc123def456\",\n  \"card_id\": \"123456789\",\n  \"card_value\": \"John Doe\"\n}\n```\n\n### Headers\n- **Content-Type**: `application/json`\n- **x-api-key**: `your_api_key` (if api_key is configured in config.toml)\n\n### Payload Fields\n- **device_id**: The unique identifier for this RFID reader device\n- **card_id**: The RFID card ID (unique hardware identifier)\n- **card_value**: The text content stored on the RFID card (can be empty if no data is written)\n\n## Service Management\n\n### Start the service:\n```bash\nsudo systemctl start rfid-reader.service\n```\n\n### Stop the service:\n```bash\nsudo systemctl stop rfid-reader.service\n```\n\n### Check service status:\n```bash\nsudo systemctl status rfid-reader.service\n```\n\n### View logs:\n```bash\n# View systemd logs\nsudo journalctl -u rfid-reader -f\n\n# View application logs\nsudo tail -f /var/log/rfid_reader.log\n```\n\n### Restart the service:\n```bash\nsudo systemctl restart rfid-reader.service\n```\n\n## Database Management\n\nThe RFID reader uses SQLite to store all card reads locally. The database is located at `/var/lib/rfid_reader/card_reads.db`.\n\n### View database statistics:\n```bash\nsudo db_manager.py stats\n```\n\n### View recent card reads:\n```bash\nsudo db_manager.py recent --limit 50\n```\n\n### View pending syncs:\n```bash\nsudo db_manager.py pending\n```\n\n### Force retry of failed syncs:\n```bash\nsudo db_manager.py retry\n```\n\n### Clean up old successful records:\n```bash\nsudo db_manager.py cleanup --days 30\n```\n\n### Export data to CSV:\n```bash\nsudo db_manager.py export /tmp/rfid_data.csv\n```\n\n## Troubleshooting\n\n### Service won't start\n\n1. Check if SPI is enabled:\n   ```bash\n   grep spi /boot/config.txt\n   ```\n\n2. Check if SPI module is loaded:\n   ```bash\n   lsmod | grep spi\n   ```\n\n3. View service logs:\n   ```bash\n   sudo journalctl -u rfid-reader -n 50\n   ```\n\n### RFID cards not being read\n\n1. Verify wiring connections\n2. Check if the RC522 module is properly powered\n3. Ensure RFID cards are compatible with RC522\n4. Check GPIO pin configuration in config file\n\n### Webhook not receiving data\n\n1. Verify webhook URL is correct and accessible\n2. Check network connectivity\n3. View application logs for webhook errors:\n   ```bash\n   sudo tail -f /var/log/rfid_reader.log\n   ```\n\n### Service failing to start\n\nIf the service is failing to start, run the diagnostic tool:\n\n```bash\nsudo diagnose.py\n```\n\nThis will check:\n- Python environment and dependencies\n- File permissions and existence\n- SPI interface configuration\n- Database access\n- Network connectivity\n- Configuration file validity\n\n### SPI Interface Issues\n\nIf you see errors like `[Errno 2] No such file or directory` related to SPI, run the SPI fix script:\n\n```bash\nsudo fix_spi.sh\n```\n\nThis script will:\n- Enable SPI in `/boot/config.txt` if not already enabled\n- Load the SPI kernel module\n- Check for SPI device files\n- Test GPIO access\n\nCommon issues and solutions:\n\n1. **SPI not enabled**: Run `sudo fix_spi.sh` or add `dtparam=spi=on` to `/boot/config.txt` and reboot\n2. **SPI module not loaded**: Run `sudo fix_spi.sh` or reboot the system\n3. **Missing dependencies**: Reinstall with `sudo ./install.sh`\n4. **Permission issues**: Check file permissions and ownership\n5. **Database directory**: Ensure `/var/lib/rfid_reader` exists and is writable\n\n## Development\n\n### Running in development mode\n\n1. Install dependencies:\n   ```bash\n   pip3 install -r requirements.txt\n   ```\n\n2. Create a local config file:\n   ```bash\n   cp config.toml local_config.toml\n   # Edit local_config.toml with your settings\n   ```\n\n3. Run the script directly:\n   ```bash\n   python3 rfid_reader.py\n   ```\n\n### Testing without hardware\n\nYou can test the webhook functionality by modifying the `read_card()` method to return a test card ID:\n\n```python\ndef read_card(self) -\u003e Optional[str]:\n    # For testing without hardware\n    time.sleep(5)  # Simulate card reading delay\n    return \"test_card_123\"\n```\n\n### Testing with API key authentication\n\nTo test the webhook server with API key authentication:\n\n```bash\n# Start test server with API key\npython3 test_webhook_server.py --api-key \"your_test_api_key\"\n\n# In another terminal, test with curl\ncurl -X POST http://localhost:8080 \\\n  -H \"Content-Type: application/json\" \\\n  -H \"x-api-key: your_test_api_key\" \\\n  -d '{\"device_id\":\"test123\",\"card_id\":\"123456789\",\"card_value\":\"John Doe\"}'\n```\n\n## License\n\nThis project is licensed under the MIT License - see the LICENSE file for details.\n\n## Contributing\n\n1. Fork the repository\n2. Create a feature branch\n3. Make your changes\n4. Test thoroughly on Raspberry Pi\n5. Submit a pull request\n\n## Support\n\nFor issues and questions:\n1. Check the troubleshooting section above\n2. View the logs for error messages\n3. Create an issue in the repository\n","project_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebugger22%2Frfid-reader","html_url":"https://awesome.ecosyste.ms/projects/github.com%2Fdebugger22%2Frfid-reader","lists_url":"https://awesome.ecosyste.ms/api/v1/projects/github.com%2Fdebugger22%2Frfid-reader/lists"}