hubble-ready-test

What this skill does

# Hubble Ready Testing Framework

## Overview

This testing framework provides comprehensive validation capabilities for Hubble Ready devices over Bluetooth Low Energy (BLE). It wraps the `hubblenetwork ready` CLI commands to enable systematic testing of device discovery, characteristic reads/writes, and the complete provisioning workflow.

The framework is designed for:
- **Device validation** - Verify BLE connectivity and device characteristics
- **Encryption testing** - Validate key writes and encryption mode detection
- **Configuration testing** - Test EID configuration updates
- **Time synchronization testing** - Verify device time reads/writes
- **Integration testing** - Execute and validate the complete provisioning flow
- **Debugging** - Diagnose BLE connection issues and ATT protocol errors

## Test Prerequisites

### BLE Adapter Requirements

- **macOS**: CoreBluetooth (must run in GUI session, not SSH)
- **Linux**: BlueZ stack (user must be in `bluetooth` group)
- **Windows**: Compatible BLE stack with Windows Runtime support

### Permissions

- **macOS**: Bluetooth permission granted to Terminal/iTerm
- **Linux**: User in `bluetooth` group: `sudo usermod -a -G bluetooth $USER`
- **Windows**: Administrator privileges may be required

### Environment Variables (for provisioning tests)

```bash
export HUBBLE_ORG_ID="your-org-id"
export HUBBLE_API_TOKEN="your-api-token"
```

These are only required for the `provision` command which registers devices with the Hubble backend.

## Available Test Commands

All test commands support `--format json` for structured output suitable for automated validation. Always use JSON format for testing to enable programmatic result verification.

### Discovery Tests

#### Test: Device Discovery (`scan`)

Scan for Hubble Ready devices advertising the 0xFCA7 service UUID.

**Command:**
```bash
hubblenetwork ready scan --format json [--timeout SECONDS]
```

**Parameters:**
- `--timeout` (optional): Scan duration in seconds (default: 10)
- `--format json`: Required for structured output

**Expected Output:**
```json
{
  "devices": [
    {
      "address": "AA:BB:CC:DD:EE:FF",
      "name": "Hubble Ready Device",
      "rssi": -65
    }
  ],
  "scan_duration": 10.2
}
```

**Validation:**
- Verify `devices` array is not empty
- Verify MAC addresses are valid format (XX:XX:XX:XX:XX:XX)
- Verify RSSI values are negative integers
- Verify scan_duration matches timeout parameter

**Common Test Failures:**
- Empty devices array: Device not in range or not advertising
- "Bluetooth adapter not found": BLE adapter not available
- Permission denied: Insufficient BLE permissions

---

#### Test: Device Information (`info`)

Read all characteristics from a connected Hubble Ready device.

**Command:**
```bash
hubblenetwork ready info --format json --address <MAC> [--timeout SECONDS]
```

**Parameters:**
- `--address` (required): Device MAC address from scan
- `--timeout` (optional): Connection timeout in seconds (default: 10)
- `--format json`: Required for structured output

**Expected Output:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "status": {
    "firmware_version": "1.2.3",
    "key_written": false,
    "config_written": false,
    "time_written": false
  },
  "key_info": {
    "encryption_mode": "AES-256-CTR"
  },
  "config": {
    "eid_type": "utc",
    "rotation_period_seconds": 900,
    "pool_size": 5
  },
  "time": {
    "unix_timestamp": 1709424000,
    "datetime": "2024-03-03T00:00:00Z"
  }
}
```

**Validation:**
- Verify all four characteristic groups present
- Verify firmware_version format (semantic version)
- Verify encryption_mode is "AES-128-CTR" or "AES-256-CTR"
- Verify eid_type is "utc" or "counter"
- Verify unix_timestamp is reasonable (not 0, not far future)

**Common Test Failures:**
- Connection timeout: Device out of range or BLE interference
- "Device not found": Invalid MAC address
- Incomplete characteristics: Device may not be fully provisioned

---

### Read Validation Tests

All read tests require the `--address` flag and support `--timeout`.

#### Test: Status Read (`read-status`)

Read firmware version and provisioning status flags.

**Command:**
```bash
hubblenetwork ready read-status --format json --address <MAC> [--timeout SECONDS]
```

**Expected Output:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "firmware_version": "1.2.3",
  "key_written": false,
  "config_written": false,
  "time_written": false
}
```

**Validation:**
- Verify firmware_version is non-empty string
- Verify all boolean flags are present
- Use flags to determine provisioning state

**Test Scenarios:**
- Fresh device: All flags false
- Partially provisioned: Some flags true
- Fully provisioned: All flags true

---

#### Test: Key Info Read (`read-key-info`)

Read encryption mode to determine required key size.

**Command:**
```bash
hubblenetwork ready read-key-info --format json --address <MAC> [--timeout SECONDS]
```

**Expected Output:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "encryption_mode": "AES-256-CTR"
}
```

**Validation:**
- Verify encryption_mode is either "AES-128-CTR" or "AES-256-CTR"
- Use this to determine key size for write-key tests (16 or 32 bytes)

**Test Note:**
Always read key info before testing key writes to ensure correct key size.

---

#### Test: Config Read (`read-config`)

Read EID configuration parameters.

**Command:**
```bash
hubblenetwork ready read-config --format json --address <MAC> [--timeout SECONDS]
```

**Expected Output:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "eid_type": "utc",
  "rotation_period_seconds": 900,
  "pool_size": 5
}
```

**Validation:**
- Verify eid_type is "utc" or "counter"
- Verify rotation_period_seconds > 0
- Verify pool_size >= 1
- Default values: eid_type="utc", rotation_period=900, pool_size=5

---

#### Test: Time Read (`read-time`)

Read device's current Unix timestamp.

**Command:**
```bash
hubblenetwork ready read-time --format json --address <MAC> [--timeout SECONDS]
```

**Expected Output:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "unix_timestamp": 1709424000,
  "datetime": "2024-03-03T00:00:00Z"
}
```

**Validation:**
- Verify unix_timestamp is positive integer
- Verify unix_timestamp is reasonable (after 2020, before far future)
- Calculate drift: `abs(device_time - system_time)`
- If drift > 60 seconds, consider time sync test

---

### Write Validation Tests

All write tests require the `--address` flag and return success confirmation.

#### Test: Key Write (`write-key`)

Write base64-encoded encryption key to device.

**Command:**
```bash
hubblenetwork ready write-key --format json --address <MAC> --key <BASE64_KEY> [--timeout SECONDS]
```

**Parameters:**
- `--address` (required): Device MAC address
- `--key` (required): Base64-encoded key (16 bytes for AES-128, 32 bytes for AES-256)
- `--timeout` (optional): Connection timeout in seconds (default: 10)

**Expected Output:**
```json
{
  "address": "AA:BB:CC:DD:EE:FF",
  "success": true,
  "message": "Encryption key written successfully"
}
```

**Test Workflow:**
1. Read encryption mode: `read-key-info`
2. Generate key with correct size (16 or 32 bytes)
3. Base64 encode key
4. Write key
5. Verify: Read status and check `key_written` flag

**Key Generation Example:**
```bash
# For AES-128-CTR (16 bytes)
KEY=$(openssl rand -base64 16)

# For AES-256-CTR (32 bytes)
KEY=$(openssl rand -base64 32)

hubblenetwork ready write-key --format json --address <MAC> --key "$KEY"
```

**Common Test Failures:**
- ATT error 0x0D (Invalid Attribute Value Length): Wrong key size
- ATT error 0x0E (Unlikely Error): Device rejected write
- "Invalid base64": Key not properly encoded

---

#### Test: Config Write (`write-config`)

Write EID configuration to device.

**Command:**
```bash
hubblenetwork ready write-config --format json --address <MAC> --eid-type <TYPE> --pool-size <SIZE> [--timeout SECONDS]
```

**Parameters:**
- `--address` (required): Device MAC address
- `--eid-type` (require