meteor_detection_system/meteor-edge-client

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

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

# 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

# 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

# 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

# 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

# Show hardware ID, registration status, and configuration
./meteor-edge-client status

4. Health Check

# Verify backend connectivity
./meteor-edge-client health [--api-url <URL>]

5. Version Information

./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

# 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

[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

# 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]