meteor_detection_system/meteor-edge-client/README.md

# Meteor Edge Client

An autonomous meteor detection system for edge devices (Raspberry Pi) with event-driven architecture, real-time video processing, and cloud integration.

## Overview

The Meteor Edge Client is a sophisticated edge computing application that serves as the "eyes" and "frontline sentinel" of the distributed meteor monitoring network. It autonomously performs continuous sky monitoring, meteor event detection, data archiving, and cloud synchronization without human intervention.

## Core Features

### Event-Driven Architecture
- **Modular Design**: All components operate as independent modules communicating through a central Event Bus
- **Real-time Processing**: Frame-by-frame video analysis with configurable detection algorithms
- **Asynchronous Operations**: Non-blocking event handling for optimal performance

### Key Capabilities
- **Autonomous Operation**: Runs continuously without human intervention
- **Meteor Detection**: Real-time video analysis to identify meteor events
- **Event Recording**: Automatic video capture and archiving of detected events
- **Cloud Synchronization**: Secure upload of events to backend API
- **Device Registration**: JWT-based device registration and authentication
- **Structured Logging**: JSON-formatted logs with correlation IDs for observability
- **Hardware ID Detection**: Automatic extraction of unique device identifiers

## System Architecture

```mermaid
graph TD
    subgraph "Core"
        App[Application Coordinator]
        EventBus[Event Bus]
    end

    subgraph "Data Sources"
        Camera[Camera Controller]
        GPS[GPS Module - Future]
        Sensors[Environment Sensors - Future]
    end

    subgraph "Processing Pipeline"
        Detection[Detection Engine]
        Storage[Storage Manager]
        Communication[Cloud Communication]
    end

    App --> Camera
    App --> Detection
    App --> Storage
    App --> Communication
    
    Camera --FrameCapturedEvent--> EventBus
    EventBus --> Detection
    Detection --MeteorDetectedEvent--> EventBus
    EventBus --> Storage
    Storage --EventPackageArchivedEvent--> EventBus
    EventBus --> Communication
```

## Module Descriptions

### `app` - Application Coordinator
- Initializes and manages all modules
- Coordinates system lifecycle
- Handles graceful shutdown

### `events` - Event Bus
- Central message passing system
- Enables decoupled module communication
- Supports multiple event types

### `camera` - Camera Controller
- Real-time video frame capture
- Configurable FPS and resolution
- Publishes FrameCapturedEvent with timestamps

### `detection` - Detection Pipeline
- Subscribes to video frames
- Maintains frame buffer for analysis
- Runs pluggable detection algorithms
- Publishes MeteorDetectedEvent on detection

### `storage` - Storage Manager
- Archives detected events with metadata
- Manages local disk space
- Creates event packages for upload

### `communication` - Communication Manager
- Handles cloud API integration
- Uploads event packages
- Manages device heartbeat

### `logging` - Structured Logging
- JSON-formatted log output
- Correlation ID tracking
- Log rotation and upload

## Installation

### Prerequisites

- Rust 1.70+ (2021 edition)
- Network connectivity to Meteor backend
- Camera device (USB or CSI for Raspberry Pi)
- Sufficient disk space for event storage

### Build from Source

```bash
# Clone the repository
git clone <repository-url>
cd meteor-edge-client

# Build for native platform
cargo build --release

# Cross-compile for Raspberry Pi (ARM64)
./build.sh

# Binary location
target/release/meteor-edge-client
```

## Configuration

The application uses a unified TOML configuration file that includes both device registration and application settings.

### Configuration File Location
- Primary: `/etc/meteor-client/config.toml` (system-wide)
- User: `~/.config/meteor-client/config.toml` (user-specific)
- Fallback: `./meteor-client-config.toml` (current directory)

### Configuration Structure

```toml
# Device Registration Section
[device]
registered = true
hardware_id = "CPU_00000000a1b2c3d4"
device_id = "device-uuid-here"
user_profile_id = "user-uuid-here"
registered_at = "2023-07-30T12:00:00Z"
jwt_token = "eyJ..."

# API Configuration
[api]
base_url = "http://localhost:3000"
upload_endpoint = "/api/v1/events"
timeout_seconds = 30

# Camera Configuration
[camera]
source = "device"  # "device" or file path
device_index = 0
fps = 30.0
width = 640
height = 480

# Detection Configuration
[detection]
algorithm = "brightness_diff"  # Detection algorithm to use
threshold = 0.3
buffer_frames = 150  # 5 seconds at 30fps

# Storage Configuration
[storage]
base_path = "/var/meteor/events"
max_storage_gb = 10
retention_days = 30
pre_event_seconds = 2
post_event_seconds = 3

# Communication Configuration
[communication]
heartbeat_interval_seconds = 60
upload_batch_size = 5
retry_attempts = 3

# Logging Configuration
[logging]
level = "info"
directory = "/var/log/meteor"
max_file_size_mb = 100
max_files = 10
upload_enabled = true
```

## Usage

### Commands

#### 1. Run Autonomous Detection System
```bash
# Start the main application (requires device registration)
./meteor-edge-client run
```
This launches the event-driven meteor detection system that will:
- Initialize camera and start capturing frames
- Run detection algorithms continuously
- Archive detected events
- Upload events to cloud backend

#### 2. Register Device
```bash
# Register device with user account using JWT token
./meteor-edge-client register <JWT_TOKEN> [--api-url <URL>]
```
One-time setup to link the device to a user account.

#### 3. Check Device Status
```bash
# Show hardware ID, registration status, and configuration
./meteor-edge-client status
```

#### 4. Health Check
```bash
# Verify backend connectivity
./meteor-edge-client health [--api-url <URL>]
```

#### 5. Version Information
```bash
./meteor-edge-client version
```

## Operational Workflow

### Initial Setup
1. User logs into web interface and obtains JWT token
2. SSH into edge device
3. Run registration command with token
4. Verify registration with status command

### Autonomous Operation
1. Start application with `run` command
2. System initializes all modules
3. Camera begins capturing frames
4. Detection algorithm analyzes frame stream
5. On meteor detection:
   - Event package created with video and metadata
   - Package archived to local storage
   - Package uploaded to cloud backend
6. Continuous operation with periodic health checks

## Event Processing Pipeline

### Data Flow
1. **Frame Capture**: Camera module captures video at configured FPS
2. **Event Detection**: Detection algorithm analyzes frame buffer
3. **Event Archiving**: Detected events saved with pre/post buffers
4. **Cloud Upload**: Compressed event packages sent to backend
5. **Local Cleanup**: Old events removed based on retention policy

### Event Package Structure
```
event_<timestamp>_<event_id>/
├── metadata.json       # Event metadata and detection info
├── video.mp4          # Event video with pre/post buffer
├── frames/            # Key frame images
│   ├── trigger.jpg    # Frame that triggered detection
│   └── ...
└── logs/              # Related log entries
```

## Development

### Running Tests
```bash
# Unit tests
cargo test

# Integration test
./demo_integration_test.sh

# With debug output
cargo test -- --nocapture
```

### Module Structure
- `src/main.rs` - CLI entry point and command handling
- `src/app.rs` - Application coordinator
- `src/events.rs` - Event bus and event types
- `src/camera.rs` - Camera control and frame capture
- `src/detection.rs` - Detection algorithms
- `src/storage.rs` - Event storage and archiving
- `src/communication.rs` - Cloud API client
- `src/config.rs` - Configuration management
- `src/hardware.rs` - Hardware ID extraction
- `src/logging.rs` - Structured logging
- `src/api.rs` - HTTP client utilities

## Production Deployment

### Systemd Service
```ini
[Unit]
Description=Meteor Edge Detection System
After=network.target

[Service]
Type=simple
ExecStart=/usr/local/bin/meteor-edge-client run
Restart=always
RestartSec=10
User=meteor
Group=meteor
Environment="RUST_LOG=info"

[Install]
WantedBy=multi-user.target
```

### Resource Requirements
- **CPU**: ARM Cortex-A53 or better
- **RAM**: 1GB minimum, 2GB recommended
- **Storage**: 16GB minimum for event buffering
- **Network**: Stable internet connection for cloud sync

### Monitoring
- Structured JSON logs in `/var/log/meteor/`
- Prometheus metrics endpoint (future)
- Health check endpoint for monitoring tools
- Correlation IDs for request tracing

## Troubleshooting

### Common Issues

1. **Camera not detected**
   - Check camera connection (USB or CSI)
   - Verify camera permissions
   - Test with `v4l2-ctl --list-devices`

2. **Detection not triggering**
   - Adjust detection threshold in config
   - Check camera exposure settings
   - Verify sufficient lighting contrast

3. **Upload failures**
   - Check network connectivity
   - Verify backend API health
   - Review JWT token expiration

4. **Storage issues**
   - Monitor disk space usage
   - Adjust retention policy
   - Check write permissions

### Debug Mode
```bash
# Run with debug logging
RUST_LOG=debug ./meteor-edge-client run

# Check logs
tail -f /var/log/meteor/meteor-edge-client.log
```

## Future Enhancements

- GPS integration for location tagging
- Environmental sensor support
- RTSP streaming server
- Advanced ML-based detection algorithms
- Multi-camera support
- Real-time web dashboard
- Edge-to-edge communication
- Offline operation mode with sync

## License

[Specify your license here]

## Contributing

[Contribution guidelines if applicable]