meteor_detection_system/meteor-edge-client/README.md

Meteor Edge Client

A Rust-based command-line client for registering and managing edge devices in the Meteor IoT platform.

Overview

The Meteor Edge Client enables edge devices (like Raspberry Pi) to securely register themselves with user accounts through JWT authentication. Once registered, devices can upload data to the platform and be managed remotely.

Features

• Hardware ID Detection: Automatically extracts unique hardware identifiers from /proc/cpuinfo, /etc/machine-id, or falls back to hostname+MAC address
• JWT Authentication: Secure registration using JWT tokens from the web interface
• Configuration Persistence: Stores registration state in TOML format
• Registration Prevention: Prevents duplicate registrations
• Health Checking: Validates backend connectivity
• Cross-platform: Works on Linux ARM systems (Raspberry Pi) and development machines

Installation

Prerequisites

• Rust 1.70+ (2021 edition)
• Network connectivity to the Meteor backend

Build from Source

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

# Build the application
cargo build --release

# The binary will be available at target/release/meteor-edge-client

Usage

Commands

1. Check Device Status

./meteor-edge-client status

Shows hardware ID, registration status, and configuration file location.

2. Register Device

./meteor-edge-client register <JWT_TOKEN>

Registers the device with the backend using a JWT token from the web interface.

Optional parameters:

• --api-url <URL>: Specify backend API URL (default: http://localhost:3000)

3. Health Check

./meteor-edge-client health [--api-url <URL>]

Verifies connectivity to the backend API.

4. Version Information

./meteor-edge-client version

Registration Workflow

1. User Authentication: User logs into the web interface
2. Token Generation: User obtains a JWT token from their profile
3. Device Registration: User SSHs into the edge device and runs:

   ./meteor-edge-client register <JWT_TOKEN>
   

4. Automatic Prevention: Subsequent registration attempts are blocked

Configuration

The client stores configuration in a TOML file at:

• Linux: /etc/meteor-client/config.toml (system-wide)
• User: ~/.config/meteor-client/config.toml (user-specific)
• Fallback: ./meteor-client-config.toml (local directory)

Configuration Format

registered = true
hardware_id = "CPU_00000000a1b2c3d4"
registered_at = "2023-07-30T12:00:00Z"
user_profile_id = "user-uuid-here"
device_id = "device-uuid-here"

Hardware ID Sources

The client attempts to extract hardware IDs in this order:

1. CPU Serial (from /proc/cpuinfo) - Most reliable on Raspberry Pi
2. Machine ID (from /etc/machine-id) - Systemd systems
3. Fallback (hostname + MAC address) - Last resort

API Integration

Backend Requirements

The client expects the backend to provide:

• GET /health - Health check endpoint
• POST /api/v1/devices/register - Device registration endpoint

Authentication

Requests to the registration endpoint include:

Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "hardwareId": "CPU_00000000a1b2c3d4"
}

Response Format

Successful registration returns:

{
  "message": "Device registered successfully",
  "device": {
    "id": "device-uuid",
    "userProfileId": "user-uuid",
    "hardwareId": "CPU_00000000a1b2c3d4",
    "status": "active",
    "registeredAt": "2023-07-30T12:00:00Z"
  }
}

Error Handling

The client handles various error scenarios:

• Invalid JWT tokens: Clear error messages about authentication failure
• Already registered devices: Prevents duplicate registration attempts
• Network connectivity: Timeout and connection error handling
• Missing backend: Health check failures with helpful diagnostics
• Permission issues: Configuration file write permission errors

Development

Running Tests

# Run all unit tests
cargo test

# Run with output
cargo test -- --nocapture

Integration Testing

# Run the demo integration test
./demo_integration_test.sh

Module Structure

• src/main.rs - CLI application and command handling
• src/hardware.rs - Hardware ID extraction logic
• src/api.rs - HTTP client for backend communication
• src/config.rs - Configuration file management

Production Deployment

System Service Setup

For production deployment, consider setting up a systemd service:

[Unit]
Description=Meteor Edge Client
After=network.target

[Service]
Type=oneshot
ExecStart=/usr/local/bin/meteor-edge-client status
User=meteor
Group=meteor

[Install]
WantedBy=multi-user.target

Permissions

The client may require elevated permissions to:

• Read hardware information from /proc/cpuinfo
• Write configuration files to /etc/meteor-client/

Security Considerations

• JWT tokens should be transmitted securely (HTTPS in production)
• Configuration files contain sensitive device information
• Network communications should use TLS in production environments

Troubleshooting

Common Issues

1. "Could not read hardware ID"

   • Ensure the device has accessible hardware identifiers
   • Check file permissions on /proc/cpuinfo and /etc/machine-id

2. "Failed to reach backend"

   • Verify network connectivity
   • Check backend URL and port
   • Ensure backend service is running

3. "Device already registered"

   • This is expected behavior after successful registration
   • Use status command to check current registration state

4. Configuration file errors

   • Check write permissions in the config directory
   • Verify disk space availability

Debug Mode

For additional debugging information, check the verbose output when running commands.

License

[Specify your license here]

Contributing

[Contribution guidelines if applicable]