Nokia / Airtel GPON Home Router API & Web Dashboard

Управляйте, автоматизируйте и администрируйте ваш Nokia G-2425G-A GPON Home Gateway (обычно предоставляемый Airtel Xstream Fiber и другими интернет-провайдерами) через Web Dashboard, MCP (Model Context Protocol), REST API и CLI — с постоянными псевдонимами устройств (SQLite) и без автоматизации браузера!

💡 Почему этот проект?

Проблема

Большинство домашних оптоволоконных роутеров (таких как Nokia GPON ONT от Airtel) не предоставляют официального API или интеграции для экосистем умного дома. Всякий раз, когда вы хотите:

• Проверить, какие устройства в данный момент подключены к вашей Wi-Fi сети,

• Назначить понятные псевдонимы (например, "Akanksha Phone", "Guestroom TV"),

• Заблокировать доступ в интернет для конкретного устройства (например, для контроля экранного времени детей),

• Или автоматизировать сетевые правила на основе времени или состояний умного дома...

...вам приходится вручную открывать браузер, перемещаться по медленному веб-порталу, вводить учетные данные и кликать через множество вложенных меню настроек.

Хуже того, из-за того, что веб-портал роутера использует сложную клиентскую гибридную схему шифрования (RSA-1024 + AES-128-CBC через пользовательский JavaScript SJCL), простые curl-скрипты или стандартные HTTP-запросы не работают. Большинство разработчиков прибегают к тяжелой и хрупкой автоматизации браузера (например, Selenium или Puppeteer).

Решение

Этот проект полностью восстанавливает криптографическое рукопожатие RSA + AES роутера на чистом Python.

Он взаимодействует напрямую с внутренними эндпоинтами роутера с временем отклика менее секунды и без накладных расходов на браузер. Он объединяет локальную базу данных SQLite для хранения постоянных метаданных устройств (псевдонимы, пользовательские заметки, первое/последнее появление) и оборачивает это ядро в четыре готовых к использованию интерфейса:

1. 🌐 Web Dashboard — элегантное тёмное веб-приложение в стиле glassmorphism с живым поиском, редактированием псевдонимов и переключателями блокировки/разблокировки в один клик.

2. 🤖 MCP Server — позволяет ИИ-агентам (таким как Antigravity, Claude, Cursor) управлять вашим Wi-Fi и блокировать/разблокировать устройства по понятным псевдонимам.

3. ⚡ REST API (FastAPI) — отлично подходит для Home Assistant, вебхуков и пользовательской автоматизации.

4. 🖥️ CLI — мгновенные команды в терминале и bash-скрипты.

Related MCP server: OpenWRT SSH MCP Server

🎯 Практические сценарии использования

1. 🤖 Голосовое и чат-управление через ИИ-агента (через MCP)

Подключите этот проект к любому MCP-совместимому ИИ-ассистенту (например, Claude Desktop, Antigravity IDE, Cursor). Вы можете просто сказать:

"Установи псевдоним 'Akanksha Phone' для устройства f6:cf:28:1c:bd:e5."
"Заблокируй доступ в интернет для Guestroom TV."
"Подключен ли сейчас Living Room TV к Wi-Fi?"
"Разблокируй Akanksha Phone."

ИИ-агент проверит ваши подключенные устройства, определит цель по псевдониму/имени хоста/IP/MAC и автоматически выполнит действие на вашем роутере.

2. 🌐 Визуальная веб-панель управления

Откройте http://localhost:8000/, чтобы отслеживать все подключенные устройства в адаптивном веб-интерфейсе:

• Живая панель статистики: общее количество устройств, активных онлайн, заблокированных и с пользовательскими псевдонимами.

• Мгновенный поиск и фильтрация: фильтрация по всем, онлайн, заблокированным или пользовательским псевдонимам.

• Встроенный редактор псевдонимов: назначайте понятные псевдонимы и заметки о местоположении любому устройству.

• Блокировка/разблокировка в один клик: переключайте доступ с мгновенными индикаторами загрузки и всплывающими уведомлениями.

3. 🏠 Интеграция с Home Assistant

Интегрируйте ваш роутер в Home Assistant с помощью REST API:

• Автоматизация перед сном: автоматически блокируйте детские планшеты и игровые консоли в 22:00 в учебные дни.

• Определение присутствия: запускайте автоматизации, когда определенные телефоны подключаются к сети или покидают её.

• Переключатели на панели управления: создавайте выделенные кнопки-переключатели «Блокировать / Разблокировать интернет» на панели Lovelace в Home Assistant.

✨ Возможности

• 🏷️ Постоянные псевдонимы устройств — хранятся в SQLite (data/router.db), поэтому вы можете ссылаться на устройства по понятным именам, например "Guestroom TV".

• 🎯 Умное разрешение нескольких целей — блокировка/разблокировка/запрос по псевдониму, имени хоста, IP-адресу или MAC-адресу (поддерживается частичное совпадение без учета регистра).

• 🔍 Список подключенных устройств — имя хоста, IP-адрес, MAC-адрес, статус онлайн и интерфейс подключения (Ethernet, 2.4GHz 802.11, 5GHz 802.11ac).

• 🚫 Блокировка устройств — блокируйте доступ в интернет 24/7 для любого устройства с помощью правил родительского контроля.

• ✅ Разблокировка устройств — мгновенно удаляйте правила блокировки.

• 📋 Список заблокированных политик — просматривайте все активные политики ограничения доступа и расписания.

• 🔄 Автосинхронизация и самовосстанавливающиеся сессии — автоматический повторный вход и восстановление сессии при истечении сессий роутера.

• 🔐 Ноль накладных расходов на браузер — чистая криптографическая аутентификация через pycryptodome и requests.

🏗️ Архитектура: четыре способа взаимодействия

📦 Установка

# Clone the repository
git clone https://github.com/surajnai567/airtel-router-api.git
cd airtel-router-api

# Install dependencies
pip install -r requirements.txt

Зависимости: requests, pycryptodome, python-dotenv, fastapi, uvicorn, mcp

⚙️ Конфигурация

Создайте файл .env в корневом каталоге (или скопируйте из .env.example):

ROUTER_IP=192.168.1.1
ROUTER_USERNAME=admin
ROUTER_PASSWORD=your_router_password

# Optional: REST API & Dashboard settings
API_HOST=0.0.0.0
API_PORT=8000

🔒 Примечание по безопасности: файлы .env и data/*.db включены в .gitignore, поэтому ваши учетные данные роутера и локальная база данных никогда не попадут в коммиты.

🌐 1. Web Dashboard и REST API

Запустите сервер:

python -m api.server

• Откройте http://localhost:8000/ в вашем браузере, чтобы просмотреть Web Dashboard.

• Откройте http://localhost:8000/docs для интерактивной документации Swagger API.

REST-эндпоинты

🤖 2. Использование MCP-сервера (для ИИ-агентов)

Предоставьте инструменты роутера напрямую ИИ-агентам с помощью Model Context Protocol (MCP).

Доступные MCP-инструменты

• list_devices() — возвращает отформатированную таблицу с Nickname, Hostname, IP, MAC, Active, Blocked и Interface.

• set_device_nickname(target, nickname, notes=None) — устанавливает или обновляет понятный псевдоним устройства.

• block_device(target, policy_name=None) — блокирует устройство по псевдониму (например, "Guestroom TV"), имени хоста, IP или MAC.

• unblock_device(target) — разблокирует устройство по псевдониму, имени хоста, IP или MAC.

• list_blocked_devices() — возвращает активные заблокированные устройства с их псевдонимами и политиками.

Конфигурация MCP

Добавьте этот сервер в конфигурацию вашего MCP-клиента (например, claude_desktop_config.json или mcp_config.json):

{
  "mcpServers": {
    "home_router": {
      "command": "python",
      "args": ["-m", "mcp_server.server"],
      "cwd": "d:/project/routerapi"
    }
  }
}

🖥️ 3. Использование CLI

# List all connected/known devices (with nicknames)
python -m cli.main list

# List all currently blocked devices
python -m cli.main blocked

# Block a device by MAC address or Nickname
python -m cli.main block AA:BB:CC:DD:EE:FF

# Block a device with a custom policy name
python -m cli.main block AA:BB:CC:DD:EE:FF --name "Kid_Tablet_Block"

# Unblock a device by MAC address
python -m cli.main unblock AA:BB:CC:DD:EE:FF

🐍 4. Использование Python-библиотеки

from core import RouterAPI

# Initialize and authenticate
router = RouterAPI(ip_address="192.168.1.1", username="admin", password="admin_password")
if router.login():
    # 1. Set a friendly nickname
    router.set_nickname("f6:cf:28:1c:bd:e5", "Akanksha Phone")

    # 2. Get all devices (auto-synced with SQLite)
    devices = router.list_devices()
    for d in devices:
        print(f"[{'ONLINE' if d['active'] else 'OFFLINE'}] {d['nickname'] or d['hostname']} ({d['ip']}) - {d['mac']}")

    # 3. Block directly by nickname!
    router.block_device("Akanksha Phone")

    # 4. Unblock by nickname!
    router.unblock_device("Akanksha Phone")

    # Clean up session
    router.logout()

📁 Структура проекта

routerapi/
├── core/                      # Core business logic (the engine)
│   ├── __init__.py            # Re-exports RouterAPI, DB helpers, and crypto
│   ├── client.py              # RouterAPI client class with smart target resolution
│   ├── crypto.py              # AES-CBC + RSA encryption implementation
│   └── db.py                  # SQLite database layer for persistent nicknames
│
├── api/                       # REST API & Web Dashboard
│   ├── __init__.py
│   ├── server.py              # FastAPI server with CORS, static routes, & models
│   └── static/                # Web Dashboard assets
│       ├── index.html         # Dashboard HTML template
│       ├── style.css          # Dark glassmorphism stylesheet
│       └── app.js             # Frontend state management & async API calls
│
├── mcp_server/                # Model Context Protocol interface
│   ├── __init__.py
│   └── server.py              # MCP server exposing router tools to AI
│
├── cli/                       # Terminal interface
│   ├── __init__.py
│   └── main.py                # Argparse CLI entry point
│
├── data/                      # Local SQLite storage (git-ignored)
│   └── router.db              # Persistent device metadata & nicknames
│
├── .env                       # Credentials (git-ignored)
├── .env.example               # Template environment configuration
├── .gitignore
├── requirements.txt           # Project dependencies
└── Readme.md                  # Project documentation

⚠️ Примечания и отказ от ответственности

• Истечение сессии и самовосстановление: сессии роутера естественным образом истекают после неактивности. API и MCP-серверы автоматически управляют повторной аутентификацией при последующих вызовах.

• Совместимость с родительским контролем: поддерживает как новую прошивку (групповой контроль доступа NPCProfileList), так и старую прошивку (политики доступа pc_config).

• Протестированное оборудование: протестировано на Nokia G-2425G-A GPON Home Gateway (Airtel Xstream Fiber).

📄 Лицензия

Этот проект лицензирован под лицензией MIT — подробнее см. в файле LICENSE.