IP Camera QR Code Scanner

A comprehensive Python-based application that connects to IP cameras via RTSP protocol, detects and decodes QR codes in real-time, and saves the decoded information to files. Built with Object-Oriented Programming principles and designed for reliability and scalability.

Special Features

Elites Domain Base64 Extraction

Domain-Specific Processing: Automatically detects QR codes from elites.liupe.xyz domain
Base64 Code Extraction: Extracts base64 codes from URLs like https://elites.liupe.xyz/qr?code=MDY1NA==
Separate Storage: Saves extracted base64 codes to dedicated JSON file for easy access
Duplicate Prevention: Prevents saving duplicate base64 codes within timeout period

Features

Core Functionality

RTSP Protocol Support: Connect to multiple IP cameras using RTSP URLs
Real-time QR Detection: Advanced QR code detection using pyzbar with image preprocessing
Multi-Camera Support: Handle up to 4+ simultaneous camera streams
Duplicate Prevention: Configurable timeout to prevent duplicate QR code logging
Multiple Output Formats: Save data in JSON, CSV, or plain text formats
File Rotation: Automatic file rotation based on size and time limits

Advanced Features

Threaded Processing: Concurrent processing for optimal performance
Automatic Reconnection: Robust reconnection logic with exponential backoff
Secure Configuration: Encrypted storage of camera credentials
Modern Web Interface: User-friendly responsive web dashboard with Bootstrap 5
CLI/Headless Mode: Command-line operation for server deployments
Comprehensive Logging: Detailed logging with file rotation
Statistics Monitoring: Real-time performance and detection statistics

System Requirements

Hardware Requirements

Minimum RAM: 4GB (8GB recommended)
CPU: Multi-core processor (4+ cores recommended)
Network: Stable network connection for RTSP streams
Storage: 500MB for application + space for data files

Software Requirements

Python: 3.8 or higher
Operating System: Windows, Linux, macOS
Network Cameras: IP cameras with RTSP support

Installation

1. Clone the Repository

git clone https://github.com/sithulaka/ip_camera_qr_scanner.git
cd ip_camera_qr_scanner

2. Create Virtual Environment

python -m venv venv
source venv/bin/activate  # On Windows: venv\Scripts\activate

3. Install Dependencies

pip install -r requirements.txt

4. Install Additional System Dependencies

Ubuntu/Debian:

sudo apt-get update
sudo apt-get install python3-opencv libzbar0

CentOS/RHEL:

sudo yum install opencv-python zbar

Windows:

Dependencies are typically installed automatically with pip.

5. Install the Package

pip install -e .

Configuration

1. Basic Configuration

Edit the configuration file at config/default_config.ini:

[cameras]
camera_01 = rtsp://admin:password@192.168.1.100:554/stream
camera_02 = rtsp://admin:password@192.168.1.101:554/stream

[storage]
output_format = json
output_directory = ./qr_data
file_rotation_size_mb = 100

[processing]
fps_limit = 30
duplicate_timeout_seconds = 5
max_threads = 4

2. Camera URL Formats

Supported RTSP URL formats:

rtsp://username:password@ip_address:port/stream
rtsp://ip_address:port/stream
rtsp://username:password@hostname/path/to/stream

3. Security

Camera credentials are automatically encrypted
Configuration files use secure permission settings
No credentials are logged in plain text

Usage

Web UI Mode (Default)

# Run with modern web interface (either entry point works)
python3 main.py
# OR
python3 qr_scanner.py

# Opens web dashboard at: http://localhost:8000

CLI/Headless Mode

# Run without web interface (for servers)
python3 main.py --cli
# OR
python3 qr_scanner.py --cli

Command Line Options

python3 main.py --help

Options:
  --cli               Run in CLI/headless mode (no web interface)
  --config FILE       Use custom configuration file
  --test-cameras      Test camera connections and exit
  --version           Show version information

Testing Camera Connections

# Test all configured cameras
python3 main.py --test-cameras
# OR
python3 qr_scanner.py --test-cameras

# Test with custom config
python3 main.py --test-cameras --config my_config.ini

Elites Base64 Code Storage

When QR codes from elites.liupe.xyz domain are detected, the system automatically extracts the base64 code and saves it to a separate file:

Base64 Codes File Location

qr_data/elites_base64_codes.json

Base64 Data Format

[
  {
    "timestamp": "2025-08-05T16:29:15.872790",
    "base64_code": "MDY1NA==",
    "original_url": "https://elites.liupe.xyz/qr?code=MDY1NA==",
    "camera_id": "camera_01",
    "camera_ip": "192.168.1.100",
    "confidence": 1.0,
    "frame_number": 0
  }
]

Output Data Formats

JSON Format

{
  "timestamp": "2025-01-20T10:30:45.123Z",
  "camera_id": "camera_01",
  "camera_ip": "192.168.1.100",
  "qr_data": "https://example.com/data",
  "qr_type": "URL",
  "confidence": 0.95,
  "processing_time_ms": 25,
  "frame_number": 12345
}

CSV Format

timestamp,camera_id,camera_ip,qr_data,qr_type,confidence,processing_time_ms,frame_number
2025-01-20T10:30:45.123Z,camera_01,192.168.1.100,https://example.com,URL,0.95,25,12345

Text Format

[2025-01-20 10:30:45] Camera: camera_01 | Type: URL | Data: https://example.com | Confidence: 0.95

QR Code Types Supported

The system automatically detects and categorizes QR codes:

URL: Web links (http://, https://, www.)
EMAIL: Email addresses
PHONE: Phone numbers
WIFI: WiFi configuration
SMS: SMS/text messages
CONTACT: vCard contact information
LOCATION: Geographic coordinates
NUMERIC: Pure numbers
TEXT: Plain text content

Web Dashboard Interface

Dashboard Components

Camera Grid: Live camera status with multiple view modes (2x2, 3x3, list)
Control Panel: Start/stop system, test cameras, access settings
Statistics Cards: Real-time metrics (cameras, QR codes, FPS, storage)
QR Detection Log: Live feed of detected QR codes with type indicators
System Logs: Real-time color-coded system messages

Settings Modal

Cameras Tab: Add/remove/configure cameras with RTSP URLs
Processing Tab: FPS limits, threads, confidence thresholds
Storage Tab: Output formats, file rotation, backup options
Real-time Updates: All changes applied instantly

Performance Optimization

Recommended Settings

FPS Limit: 15-30 FPS per camera
Max Threads: Number of CPU cores
Buffer Size: 10-20 frames
Confidence Threshold: 0.8 for high accuracy

Monitoring Performance

# Check system resources
htop

# Monitor network usage
iftop

# Check disk space
df -h

Troubleshooting

Common Issues

Camera Connection Problems

# Test individual camera
ffmpeg -i "rtsp://camera-url" -t 10 -f null -

# Check network connectivity
ping camera-ip-address

# Verify RTSP port
telnet camera-ip-address 554

QR Detection Issues

Ensure good lighting conditions
Check camera focus and positioning
Adjust confidence threshold in configuration
Verify QR code is not damaged or distorted

Performance Issues

Reduce FPS limit for multiple cameras
Increase processing threads if CPU allows
Enable hardware acceleration if available
Check network bandwidth usage

Log Files

Application logs are stored in:

logs/qr_scanner_YYYYMMDD.log
Log rotation occurs daily with 5-day retention

Debug Mode

# Enable verbose logging
python src/main.py --debug

Development

Project Structure

ip_camera_qr_scanner/
├── src/
│   ├── camera/          # Camera management
│   ├── processing/      # QR code detection
│   ├── storage/         # Data persistence
│   ├── ui/             # GUI components
│   ├── config/         # Configuration management
│   └── utils/          # Utilities and logging
├── tests/              # Unit and integration tests
├── config/             # Configuration files
└── docs/               # Documentation

Running Tests

# Install test dependencies
pip install -e .[dev]

# Run all tests
pytest

# Run with coverage
pytest --cov=src tests/

# Run specific test
pytest tests/test_qr_decoder.py

Code Quality

# Format code
black src/

# Lint code
flake8 src/

# Type checking
mypy src/

API Reference

Core Classes

CameraManager

from src.camera.camera_manager import CameraManager

manager = CameraManager(camera_settings)
manager.start_all_cameras()
manager.add_frame_callback(callback_function)

QRDecoder

from src.processing.qr_decoder import QRDecoder

decoder = QRDecoder(confidence_threshold=0.8)
qr_codes = decoder.decode_frame(frame, camera_id, camera_ip)

StorageManager

from src.storage.storage_manager import StorageManager

storage = StorageManager(storage_settings)
storage.store_qr_data(qr_data)

Contributing

Development Setup

Fork the repository
Create a feature branch
Make changes with tests
Run quality checks
Submit pull request

Guidelines

Follow PEP 8 style guidelines
Write comprehensive tests
Update documentation
Use type hints
Add logging for debugging

Author

Sithulaka

GitHub: github.com/sithulaka

License

This project is licensed under the MIT License - see the LICENSE file for details.

Support

Getting Help

Check the troubleshooting section
Review log files for errors
Test camera connections independently
Verify configuration settings

Reporting Issues

When reporting issues, please include:

Operating system and version
Python version
Camera model and RTSP URL format
Error messages and log excerpts
Steps to reproduce the problem

Changelog

Version 1.0.0

Initial release
Multi-camera RTSP support
Real-time QR code detection
GUI and headless modes
Comprehensive configuration system
File rotation and backup support
Performance monitoring and statistics

IP Camera QR Code Scanner - Built with Python for reliability and performance by Sithulaka.

Name		Name	Last commit message	Last commit date
Latest commit History 6 Commits
config		config
docs		docs
readmes		readmes
src		src
.gitignore		.gitignore
README.md		README.md
qr_scanner.py		qr_scanner.py
requirements.txt		requirements.txt
setup.py		setup.py

sithulaka/ip_camera_qr_scanner

Folders and files

Latest commit

History

Repository files navigation