Metadata-Version: 2.4
Name: hyper-wireless
Version: 1.0.2
Summary: Hyper Wireless - Cloud Testing Platform for 3GPP 5G NR Conformance
Author-email: Hyper Wireless Team <dev@hyper-wireless.com>
Project-URL: Homepage, https://hyper-wireless.com
Project-URL: Dashboard, https://app.hyper-wireless.com
Project-URL: API, https://cloud-api.hyper-wireless.com
Classifier: Programming Language :: Python :: 3
Classifier: Topic :: Software Development :: Testing
Classifier: Topic :: System :: Networking
Requires-Python: >=3.8
Description-Content-Type: text/markdown
Requires-Dist: requests>=2.28.0
Requires-Dist: websockets>=12.0

# Hyper Wireless CLI (`hyper` / `hyper-wireless`)

[![PyPI version](https://img.shields.io/pypi/v/hyper-wireless.svg)](https://pypi.org/project/hyper-wireless/)
[![Python Versions](https://img.shields.io/pypi/pyversions/hyper-wireless.svg)](https://pypi.org/project/hyper-wireless/)
[![License](https://img.shields.io/badge/license-Proprietary-blue.svg)](https://hyper-wireless.com)
[![3GPP Standard](https://img.shields.io/badge/3GPP-Rel%2018%20(5G%20NR)-cyan.svg)](https://app.hyper-wireless.com)

The official command-line interface for the **Hyper Wireless Cloud Testing Platform**. 

Execute full 3GPP 5G NR conformance test suites in the cloud, test local or remote User Equipment (UE) stacks over high-speed WebSocket multiplex relays, and stream real-time logs directly to your terminal.

---

## Key Features

- **Blazing-Fast Execution**: Powered by dynamic timing control and link optimisations, completing full registration tests in **~130 seconds**.
- **Two Execution Modes** with full protocol compliance:
  - **Remote UE Mode**: Connect your local open-source or custom UE implementation to the cloud test network over a secure, low-latency  tunnel.
  - **Headless Cloud Mode**: Run both the 3GPP test suite and UE simulator entirely in the cloud with zero local compilation required.
- **Zero Root Required**: Operates completely in userspace.
- **Live Telemetry & Step Tracking**: Real-time RRC/NAS procedure logs streamed directly to your terminal.
- **Automated Artifact Collection**: Automatic downloads and extraction of compressed test artifacts, PCAP traces, and Message Sequence Charts (MSC).

---

## Installation

Install via `pip` or `pipx`:

```bash
pip install hyper-wireless
```

Or using [pipx](https://pypa.github.io/pipx/) to install globally in an isolated environment:

```bash
pipx install hyper-wireless
```

> Once installed, you can use either the short alias **`hyper`** or the full command **`hyper-wireless`**.

---

## Authentication

Generate your developer API key from the [Hyper Wireless Web Dashboard](https://app.hyper-wireless.com/account/api-keys), then set it in your environment:

```bash
export HYPER_WIRELESS_CLOUD_API_KEY="ttcn_live_YOUR_SECRET_KEY"
```

*(Alternatively, save it in a local `.env` file).*

---

## Quickstart

### 1. Check Cloud Runner Status
```bash
hyper health
```
*Output:*
```json
{
  "status": "healthy",
  "active_suite": "NR5GC_IWD_25wk50",
  "available_slots": 8,
  "max_slots": 8
}
```

### 2. Discover Available Test Suites
```bash
hyper suites
```

### 3. Run a Conformance Test with Local srsRAN UE (`--srsue`)
Bridge your locally compiled `ttcn3_dut` binary to the cloud network:

```bash
hyper run --tc TC_6_1_1_1_NR5GC --srsue
```

You can explicitly specify a custom UE binary path:
```bash
hyper run --tc TC_6_1_1_1_NR5GC --srsue --dut-binary /path/to/ttcn3_dut
```

### 4. Run in Pure Headless Cloud Mode (No Local UE Needed)
Ideal for CI/CD runners where C++ binaries are not compiled locally:

```bash
hyper run --tc TC_6_1_1_1_NR5GC
```

---

## Simulation Timing Options

The runner supports multiple simulation clock modes via the `--timer-mode` parameter:

| Mode | Max Step Size | Best For |
| :--- | :--- | :--- |
| **`adaptive`** *(default)* | Dynamic (100ms – 5000ms) | **Recommended**: Automatically scales clock leaps during idle waits. |
| **`accurate`** | 100ms | Strict lock-step timing inspection. |
| **`balanced`** | 500ms | Balanced local verification. |
| **`fast`** | 2000ms | Accelerated static runs. |

*Example:*
```bash
hyper run --tc TC_6_1_1_1_NR5GC --srsue --timer-mode adaptive
```

---

## CI/CD Pipeline Integration

### GitHub Actions
```yaml
name: 5G Conformance Regression
on: [push, pull_request]

jobs:
  test:
    runs-on: ubuntu-latest
    steps:
      - uses: actions/checkout@v4
      - uses: actions/setup-python@v5
        with:
          python-version: '3.11'
      
      - name: Install Hyper Wireless CLI
        run: pip install hyper-wireless

      - name: Execute 3GPP Test
        env:
          HYPER_WIRELESS_CLOUD_API_KEY: ${{ secrets.HYPER_WIRELESS_CLOUD_API_KEY }}
        run: |
          hyper run --tc TC_6_1_1_1_NR5GC
```

### Jenkins Pipeline
```groovy
stage('3GPP Cloud Conformance') {
    steps {
        withCredentials([string(credentialsId: 'HYPER_WIRELESS_CLOUD_API_KEY', variable: 'HYPER_WIRELESS_CLOUD_API_KEY')]) {
            sh '''
                pip install hyper-wireless
                hyper run --tc TC_6_1_1_1_NR5GC
            '''
        }
    }
}
```

---

## Command Reference

```text
usage: hyper [-h] [--endpoint ENDPOINT] [--token TOKEN]
             {suites,health,testcases,run} ...

positional arguments:
  suites                List available test suites in the cloud
  health                Check service health and slot concurrency
  testcases             List supported test cases for a suite
  run                   Execute a test case in the cloud

options:
  -h, --help            Show this help message and exit
  --endpoint ENDPOINT   Cloud service endpoint (default: https://cloud-api.hyper-wireless.com)
  --token TOKEN         API Bearer token (or via HYPER_WIRELESS_CLOUD_API_KEY)
```

---

## Web Portal & Documentation

- **Web Portal**: [https://app.hyper-wireless.com](https://app.hyper-wireless.com)
- **API Status**: [https://cloud-api.hyper-wireless.com/health](https://cloud-api.hyper-wireless.com/health)
- **Support**: [dev@hyper-wireless.com](mailto:dev@hyper-wireless.com)
