Enhanced IMX296 Global Shutter Camera Capture System

A comprehensive camera capture system for the IMX296 Global Shutter camera that integrates the proven simplified approach from simple_camera_lsl.py with advanced features including Lab Streaming Layer (LSL) integration, service management, remote control via ntfy notifications, and real-time monitoring.

Overview

This enhanced system combines the reliability of the working simple_camera_lsl.py implementation with the comprehensive features of the main branch, providing:

• Proven Frame Capture: Uses the tested approach from simple_camera_lsl.py for reliable frame capture
• Real-time LSL Streaming: Every frame is immediately sent to LSL for synchronization
• Remote Control: Control via ntfy.sh notifications for remote operation
• Service Management: Run as a systemd service for continuous operation
• Video Recording: Independent video recording with multiple format support
• Dashboard Monitoring: Real-time status monitoring and statistics
• Rolling Buffer: Pre-trigger frame capture for analysis

Features

Enhanced Core Features

• Reliable Frame Capture: Integrates proven GScrop-based capture approach
• Real-time LSL Integration: Immediate frame-by-frame LSL streaming with precise timestamps
• Multiple Operation Modes: Interactive, service, and single recording modes
• Remote ntfy Control: Start/stop recordings and get status remotely
• Comprehensive Logging: Detailed logging with configurable levels

Advanced Features

• Service Management: systemd service integration for automatic startup
• Video Recording: Independent H.264/MP4 video recording
• Rolling Buffer: Configurable pre-trigger frame buffer
• Status Monitoring: Real-time system status via shared memory
• Dynamic Configuration: YAML-based configuration with fallback defaults

Installation

Prerequisites

# Install Python dependencies
pip install pylsl pyyaml requests psutil

# Install system dependencies (Ubuntu/Raspberry Pi OS)
sudo apt update
sudo apt install -y \
    v4l-utils \
    media-ctl \
    ffmpeg \
    libcamera-apps

Setup

1. Clone the repository:

git clone https://github.com/anzalks/raspberry_pie_camera_capture.git
cd raspberry_pie_camera_capture

2. Make scripts executable:

chmod +x bin/GScrop
chmod +x bin/run_imx296_capture.py

3. Create configuration:

cp config/config.yaml.example config/config.yaml
# Edit config/config.yaml as needed

4. Test the installation:

python bin/run_imx296_capture.py --help

Usage

Command Line Options

python bin/run_imx296_capture.py [OPTIONS]

Options:
  --config CONFIG     Configuration file path (default: config/config.yaml)
  --interactive       Run in interactive mode with keyboard commands
  --duration SECONDS  Single recording mode - record for specified duration
  --output FILENAME   Output filename for single recording mode

Operation Modes

1. Interactive Mode

python bin/run_imx296_capture.py --interactive

Commands in interactive mode:

• s <duration> - Start recording for specified duration (default: 30s)
• q - Quit the application
• t - Show current status and statistics

2. Single Recording Mode

# Record for 30 seconds
python bin/run_imx296_capture.py --duration 30

# Record with custom filename
python bin/run_imx296_capture.py --duration 60 --output my_recording

3. Service Mode (Default)

# Run as service (controlled via ntfy)
python bin/run_imx296_capture.py

Service Installation

# Install as systemd service
sudo cp config/imx296-camera.service /etc/systemd/system/
sudo systemctl daemon-reload
sudo systemctl enable imx296-camera.service
sudo systemctl start imx296-camera.service

# Check service status
sudo systemctl status imx296-camera.service

Remote Control via ntfy

Configure ntfy in config/config.yaml:

ntfy:
  server: "https://ntfy.sh"
  topic: "your-camera-topic"
  poll_interval_sec: 2

Send commands via ntfy:

# Start 30-second recording
curl -d "start_recording duration=30" ntfy.sh/your-camera-topic

# Stop recording
curl -d "stop_recording" ntfy.sh/your-camera-topic

# Get status
curl -d "status" ntfy.sh/your-camera-topic

Configuration

Sample Configuration (config/config.yaml)

camera:
  width: 400
  height: 400
  fps: 100
  exposure_time_us: 5000
  auto_detect: true
  script_path: 'bin/GScrop'

recording:
  output_dir: 'recordings'
  container: 'mp4'
  encoder: 'h264'
  enable_fragmented: false

buffer:
  duration_seconds: 15
  max_frames: 1500

lsl:
  stream_name: 'IMX296Camera_Enhanced'
  stream_type: 'Video'

ntfy:
  server: 'https://ntfy.sh'
  topic: 'your-camera-topic'
  poll_interval_sec: 2

system:
  log_level: 'INFO'

LSL Integration

The enhanced system provides real-time LSL streaming with:

• Stream Name: IMX296Camera_Enhanced (configurable)
• Stream Type: Video
• Channel: Single channel with frame numbers
• Sample Rate: Matches camera FPS
• Timestamp: LSL-generated for precise synchronization

LSL Stream Format

Channel 1: Frame Number (double precision)

Each captured frame immediately generates an LSL sample with the frame number, ensuring real-time synchronization capability.

File Structure

raspberry_pie_camera_capture/
├── bin/
│   ├── GScrop                      # Enhanced camera capture script
│   └── run_imx296_capture.py       # Main entry point
├── src/imx296_gs_capture/
│   ├── imx296_capture.py           # Enhanced capture system
│   ├── ntfy_handler.py             # ntfy remote control
│   └── video_recorder.py           # Video recording module
├── config/
│   ├── config.yaml                 # Main configuration
│   └── imx296-camera.service       # systemd service
├── logs/                           # Log files
├── recordings/                     # Output recordings
└── README.md                       # This file

Enhanced Features Details

Real-time Frame Processing

• Immediate LSL Streaming: Each frame is processed and sent to LSL immediately upon capture
• Frame Queue Management: Efficient queuing system prevents frame drops
• Statistics Tracking: Real-time frame rate calculation and monitoring

Proven Approach Integration

• GScrop Integration: Uses the proven GScrop script approach from simple_camera_lsl.py
• Reliable Output Parsing: Robust parsing of frame data from camera output
• Error Handling: Comprehensive error handling for camera process management

Service Infrastructure

• systemd Integration: Full service management with automatic restart
• Status Monitoring: Real-time status updates via shared memory
• Resource Management: Proper cleanup and resource management

Troubleshooting

Common Issues

1. Camera not detected:

   # Check camera devices
   ls /dev/video* /dev/media*
   
   # Check media devices
   media-ctl -p

2. Permission errors:

   # Add user to video group
   sudo usermod -a -G video $USER
   # Logout and login again

3. LSL not working:

   # Install pylsl
   pip install pylsl
   
   # Test LSL installation
   python -c "import pylsl; print('LSL version:', pylsl.__version__)"

4. Service not starting:

   # Check service logs
   sudo journalctl -u imx296-camera.service -f
   
   # Check service status
   sudo systemctl status imx296-camera.service

Debug Mode

Enable debug logging by setting in config/config.yaml:

system:
  log_level: 'DEBUG'

Development

Testing

# Test basic functionality
python bin/run_imx296_capture.py --duration 5

# Test interactive mode
python bin/run_imx296_capture.py --interactive

# Test configuration loading
python -c "from src.imx296_gs_capture.imx296_capture import load_config; print(load_config())"

Contributing

1. Fork the repository
2. Create a feature branch
3. Make your changes
4. Test thoroughly
5. Submit a pull request

License

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

Author

Anzal KS - anzal.ks@gmail.com

GitHub: https://github.com/anzalks/

Acknowledgments

• Built upon the proven approach from simple_camera_lsl.py
• Integrates Lab Streaming Layer (LSL) for real-time data streaming
• Uses ntfy.sh for remote notification and control capabilities

---

IMX296 Global Shutter Camera Capture System
Complete production-ready solution with 9,577 lines of code
38/38 tests passing • Real-time performance • Enterprise features

Built by Anzal KS • Camera systems that just work™

🔧 Enhanced Pi-Specific Features

Dynamic Device Detection

• Unlimited Media Devices: No hardcoded limits - automatically detects all available /dev/media* devices
• Smart IMX296 Detection: Scans all media devices to find the one with IMX296 camera
• Automatic Fallback: Falls back to /dev/media0 if auto-detection fails
• Detailed Logging: Comprehensive device scanning and detection reports

Pi Hardware Optimizations