# 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

```bash
# 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
```bash
./meteor-edge-client status
```
Shows hardware ID, registration status, and configuration file location.

#### 2. Register Device
```bash
./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
```bash
./meteor-edge-client health [--api-url <URL>]
```
Verifies connectivity to the backend API.

#### 4. Version Information
```bash
./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:
   ```bash
   ./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

```toml
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:
```http
Authorization: Bearer <JWT_TOKEN>
Content-Type: application/json

{
  "hardwareId": "CPU_00000000a1b2c3d4"
}
```

### Response Format

Successful registration returns:
```json
{
  "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

```bash
# Run all unit tests
cargo test

# Run with output
cargo test -- --nocapture
```

### Integration Testing

```bash
# 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:

```ini
[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]