Metadata-Version: 2.4
Name: openhotspot
Version: 1.0.1
Summary: A modern, production-ready Linux hotspot and network management toolkit
Project-URL: Homepage, https://github.com/joshisanidhya/openhotspot
Project-URL: Documentation, https://github.com/joshisanidhya/openhotspot#readme
Project-URL: Repository, https://github.com/joshisanidhya/openhotspot
Project-URL: Issues, https://github.com/joshisanidhya/openhotspot/issues
Project-URL: Changelog, https://github.com/joshisanidhya/openhotspot/blob/main/CHANGELOG.md
Author-email: OpenHotspot Maintainers <maintainers@openhotspot.org>
License: MIT
License-File: LICENSE
Keywords: cli,hotspot,linux,networking,networkmanager,nmcli,wifi
Classifier: Development Status :: 5 - Production/Stable
Classifier: Environment :: Console
Classifier: Intended Audience :: Developers
Classifier: Intended Audience :: System Administrators
Classifier: License :: OSI Approved :: MIT License
Classifier: Operating System :: POSIX :: Linux
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Networking
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.12
Requires-Dist: pillow>=10.0.0
Requires-Dist: psutil>=5.9.0
Requires-Dist: pyyaml>=6.0.1
Requires-Dist: qrcode[pil]>=7.4.2
Requires-Dist: rich>=13.7.0
Requires-Dist: typer>=0.12.0
Provides-Extra: dev
Requires-Dist: mypy>=1.9.0; extra == 'dev'
Requires-Dist: pytest-cov>=4.1.0; extra == 'dev'
Requires-Dist: pytest-mock>=3.12.0; extra == 'dev'
Requires-Dist: pytest>=8.0.0; extra == 'dev'
Requires-Dist: ruff>=0.3.0; extra == 'dev'
Requires-Dist: types-psutil>=5.9.0; extra == 'dev'
Requires-Dist: types-pyyaml>=6.0.12; extra == 'dev'
Description-Content-Type: text/markdown

# ⚡ OpenHotspot

> A modern open-source Wi-Fi hotspot and network management toolkit for Linux.

OpenHotspot makes it easy to **create, manage, diagnose, and share Wi-Fi hotspots on Linux** without having to remember complex networking commands.

Built around **NetworkManager (`nmcli`)**, OpenHotspot provides a clean CLI, system diagnostics, QR-code sharing, configuration management, and helpful troubleshooting.

> 🚀 **Current Release: OpenHotspot 1.0 — "Apex"**

[![CI](https://github.com/joshisanidhya/openhotspot/actions/workflows/ci.yml/badge.svg)](https://github.com/joshisanidhya/openhotspot/actions/workflows/ci.yml)
[![PyPI](https://img.shields.io/pypi/v/openhotspot.svg)](https://pypi.org/project/openhotspot/)
[![Python](https://img.shields.io/badge/Python-3.12%2B-blue.svg)](https://www.python.org/)
[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](LICENSE)
[![Code Style: Ruff](https://img.shields.io/badge/code%20style-Ruff-000000.svg)](https://github.com/astral-sh/ruff)

---

## ✨ Why OpenHotspot?

Creating a hotspot on Linux is simple when everything works.

When it doesn't, troubleshooting can become frustrating due to Wi-Fi adapter limitations, driver capabilities, NetworkManager configuration, AP mode support, regulatory restrictions, and privilege management.

OpenHotspot wraps Linux networking tools in a user-friendly CLI while explaining **why an operation succeeded or failed and how to resolve issues**.

---

## 🌟 Core Features

- 📡 **Hotspot Management**: Easily start, stop, and restart Wi-Fi hotspots with custom SSID and WPA2-PSK security.
- 🔄 **Concurrent Wi-Fi + Hotspot (AP+STA)**: Connect to an upstream Wi-Fi network while simultaneously broadcasting a hotspot on compatible hardware.
- 🩺 **Doctor Diagnostics**: Run an automated suite of system, driver, hardware, and permission checks.
- 📱 **QR Code Sharing**: Render terminal ASCII QR codes or export PNG images for instant mobile connection.
- 👥 **Connected Client Detection**: Monitor active connected stations via kernel neighbor tables and station dumps.
- ⚙️ **Configuration Management**: Persist global defaults in `~/.config/openhotspot/config.yaml`.
- 📝 **Local Logging**: Retain rotating local logs for offline troubleshooting.
- 🔒 **Local-First & Private**: No cloud accounts, telemetry, or external API dependencies.
- 🛡️ **Targeted Privilege Security**: Runs in unprivileged user space; prompts for native OS authorization only when low-level wireless interface creation is required.

---

## 📊 Example Output

```text
📡 OpenHotspot Status

Hotspot State       ● RUNNING
SSID                MyHotspot
AP Interface        oh-ap0
Physical Adapter    wlp2s0
Driver              ath10k_pci
Security Protocol   WPA2-PSK
Hotspot Gateway IP  10.42.0.1
Frequency Band      5 GHz
Wi-Fi Channel       149
Sharing Mode        Wi-Fi → Wi-Fi
Upstream            Campus_WiFi
Upstream State      CONNECTED
Internet Sharing    ACTIVE
Existing Wi-Fi      PRESERVED ✓
```

---

## 🛠️ System Dependencies

OpenHotspot relies on standard Linux networking utilities:

- **NetworkManager** (`nmcli`) — Manages network profiles, DHCP, and IP routing.
- **`iw`** — Required for virtual AP interface operations, AP+STA capability inspection, and frequency regulatory checks.
- **`iproute2`** (`ip`) — Manages interface link states and IP addresses.

### Installing Dependencies

On Ubuntu / Debian:

```bash
sudo apt update
sudo apt install network-manager iw iproute2
```

---

## 🚀 Installation

### Preferred: Install via PyPI

```bash
pip install openhotspot
```

### Virtual Environment Installation (Recommended for modern Linux distros)

```bash
python3 -m venv .venv
source .venv/bin/activate
pip install openhotspot
```

### Install from Source

```bash
git clone https://github.com/joshisanidhya/openhotspot.git
cd openhotspot
python3 -m venv .venv
source .venv/bin/activate
pip install -e .
```

Verify installation:

```bash
openhotspot --version
```

---

## ⚡ Quick Start

### 1. Run Diagnostics

Check system compatibility and wireless capabilities:

```bash
openhotspot doctor
```

### 2. Start a Hotspot

```bash
openhotspot start --ssid "MyHotspot" --password "supersecret123"
```

> **Note on Administrative Authorization:**
> OpenHotspot runs as a normal unprivileged application. If low-level wireless interface operations require elevated privileges, OpenHotspot requests authorization via native `sudo`. Password input is handled directly by your operating system terminal; OpenHotspot never sees, stores, or logs your password.

### 3. Check Hotspot Status

```bash
openhotspot status
```

### 4. Display Wi-Fi QR Code

```bash
openhotspot qr
```

### 5. Stop the Hotspot

```bash
openhotspot stop
```

---

## 💻 CLI Reference

| Command | Description |
| --- | --- |
| `openhotspot start` | Start a Wi-Fi hotspot |
| `openhotspot stop` | Stop the active hotspot |
| `openhotspot restart` | Restart the active hotspot |
| `openhotspot status` | Show hotspot status and connected clients |
| `openhotspot doctor` | Run comprehensive system diagnostics |
| `openhotspot qr` | Generate terminal or PNG Wi-Fi QR codes |
| `openhotspot config` | View and modify persistent configuration |
| `openhotspot logs` | View application log entries |
| `openhotspot version` | Display version information |
| `openhotspot --help` | Display CLI help |

See [`docs/cli-reference.md`](docs/cli-reference.md) for detailed flag options.

---

## 📡 Wi-Fi + Hotspot Simultaneously (AP+STA)

OpenHotspot supports concurrent **AP + STA mode**, allowing your device to maintain an active Wi-Fi internet connection while broadcasting a hotspot.

- **STA (Station)**: Your computer's client connection to an existing Wi-Fi router.
- **AP (Access Point)**: The hotspot network broadcast by OpenHotspot.

### Single-Channel Concurrency & Regulatory Considerations

Many Wi-Fi adapters support AP+STA operation on a **single RF channel**. In single-channel mode:

- OpenHotspot automatically matches the hotspot frequency band and channel to your upstream Wi-Fi connection.
- Driver or regulatory restrictions (such as DFS or No-Initiating-Radiation flags) MAY prevent initiating Access Point broadcasts on specific channels. OpenHotspot inspects frequency capabilities during preflight checks prior to activation.

### Practical Alternatives

If concurrent AP+STA is unsupported by your hardware or restricted on your current channel:

- Connect upstream Wi-Fi to an AP-compatible non-DFS channel (e.g. 2.4 GHz or 5 GHz channels 36–48 / 149–165).
- Use Ethernet for internet upstream.
- Use a second USB Wi-Fi adapter.
- Run `openhotspot start` with `--allow-disconnect` to explicitly allow disconnecting existing Wi-Fi.

---

## 🩺 OpenHotspot Doctor Checks

`openhotspot doctor` performs the following diagnostic checks:

1. **Linux Distribution & OS**
2. **Kernel Version**
3. **Python Runtime**
4. **NetworkManager Daemon & `nmcli` Availability**
5. **Wi-Fi Adapter & Wireless Driver Detection**
6. **Access Point (AP) Hardware Capability**
7. **Concurrent AP + STA Support & Channel Limits**
8. **Current Wi-Fi Upstream Channel & Regulatory Usability**
9. **Internet Connectivity**
10. **System Privilege & Authorization Status**

See [`docs/doctor-diagnostics.md`](docs/doctor-diagnostics.md) for diagnostic details.

---

## 🛡️ Security & Privilege Architecture

OpenHotspot prioritizes security and privilege minimization:

- **Unprivileged Execution**: OpenHotspot runs inside your normal user environment. Running the entire application as root (`sudo openhotspot`) is not required.
- **Targeted Elevation**: Elevated privileges are requested only for narrow kernel interface commands (e.g. `iw`).
- **Native OS Credentials**: Authentication is handled directly by `sudo` on your controlling terminal. OpenHotspot never captures, pipes, logs, or stores administrative credentials.

---

## 🏗️ Architecture

```text
                    ┌─────────────────────────┐
                    │    Typer + Rich CLI     │
                    └────────────┬────────────┘
                                 │
                    ┌────────────▼────────────┐
                    │   Application Services  │
                    │ Hotspot │ Doctor │ QR   │
                    └───────┬──────────┬──────┘
                            │          │
                 ┌──────────▼───┐  ┌───▼──────────────┐
                 │NetworkManager│  │  Local Storage   │
                 │    nmcli     │  │  YAML / SQLite   │
                 └──────────────┘  └──────────────────┘
```

See [`docs/architecture.md`](docs/architecture.md) for detailed component documentation.

---

## 🗺️ Roadmap

### 🚀 Apex — v1.x (Current Release)
- Core hotspot lifecycle management
- AP+STA concurrent sharing
- System Doctor diagnostics
- QR code generation
- Configuration and local logging

### ⚡ Titan — v2.x (Planned)
- Wi-Fi network scanning
- Advanced connected-device management
- Bandwidth monitoring & speed tests
- Historical usage analytics

### 👑 Dominion — v3.x (Planned)
- Desktop GUI interface
- Hotspot automation rules
- Local REST API
- Plugin architecture

See [`ROADMAP.md`](ROADMAP.md) for details.

---

## 🤝 Contributing

Contributions are welcome! Please read [`CONTRIBUTING.md`](CONTRIBUTING.md) before submitting pull requests.

Community interaction is governed by our [`CODE_OF_CONDUCT.md`](CODE_OF_CONDUCT.md).

---

## 🔐 Security Policy

If you discover a potential security vulnerability, please refer to [`SECURITY.md`](SECURITY.md) to report it responsibly.

---

## 📜 License

Distributed under the [MIT License](LICENSE).

---

<p align="center">
  <b>⚡ OpenHotspot</b><br>
  Making Linux hotspot management simpler.
</p>