Metadata-Version: 2.4
Name: remotescout
Version: 1.0.0
Summary: Python library for managing IoT agents via MQTT — screenshots, commands, file transfers, tunnels, cameras
Project-URL: Homepage, https://github.com/Pedro77339/remotescout-mcp
Project-URL: Repository, https://github.com/Pedro77339/remotescoutapp
Author: Pedro Camacho
License: MIT
Keywords: agent,iot,mcp,mqtt,remote-management
Classifier: Development Status :: 4 - Beta
Classifier: Intended Audience :: Developers
Classifier: License :: OSI Approved :: MIT License
Classifier: Programming Language :: Python :: 3
Classifier: Programming Language :: Python :: 3.10
Classifier: Programming Language :: Python :: 3.11
Classifier: Programming Language :: Python :: 3.12
Classifier: Topic :: System :: Monitoring
Classifier: Topic :: System :: Systems Administration
Requires-Python: >=3.10
Requires-Dist: paho-mqtt>=1.6
Requires-Dist: pillow>=9.0
Requires-Dist: requests>=2.28
Description-Content-Type: text/markdown

# remotescout

Python library for managing IoT agents via MQTT. Provides a unified API for remote device management: screenshots, shell commands, file transfers, TCP tunnels, camera feeds, and OTA deployments.

Built for the [Remote Scout MCP Server](https://github.com/Pedro77339/remotescout-mcp) but can be used standalone.

## Installation

```bash
pip install remotescout
```

## Configuration

### Option 1: Environment variables

```bash
export RS_MQTT_GLOBAL_PASSWORD="your_global_password"
export RS_MQTT_ROUTER_PASSWORD="your_router_password"
```

### Option 2: settings.json

Create a `config/settings.json` in your base path:

```json
{
    "mqtt_router_host": "mrouter.ci24.com",
    "mqtt_router_port": 8001,
    "mqtt_router_user": "ci24",
    "mqtt_router_password": "YOUR_PASSWORD",
    "mqtt_global_host": "mgovernor.ci24.com",
    "mqtt_global_port": 1883,
    "mqtt_global_user": "ci24",
    "mqtt_global_password": "YOUR_PASSWORD"
}
```

> Contact the project admin for MQTT broker credentials.

## Quick start

```python
from remotescout import RemoteScoutAPI

api = RemoteScoutAPI(base_path="./my_base")
api.initialize()
api.connect()

# Login
api.login("your_username")

# List agents
agents = api.get_agents_by_domain("BLX")
for a in agents:
    print(f"{a.mac} - {a.id} ({a.status.value})")

# Execute command
result = api.execute_command("d83addc8721e", "uptime")
print(result.output)

# Screenshot
img_bytes = api.get_screenshot("d83addc8721e", ratio=3, timeout=10)
```

## Features

| Feature | Method |
|---------|--------|
| Agent discovery | `get_agents_by_domain()`, `get_agent()` |
| Shell commands | `execute_command()` |
| Screenshots | `get_screenshot()` |
| File browser | `list_directory()`, `get_file_bytes()` |
| File transfer | `download_file()` |
| TCP tunnels | `open_tunnel()`, `close_all_tunnels()` |
| Camera feeds | `discover_cameras()`, `get_camera_frame()` |
| OTA packages | `list_packages()`, `upload_package()` |
| OTP tokens | `get_otp()` |

## Requirements

- Python 3.10+
- Access to the MQTT broker (credentials from admin)
- User permissions file or governor-validated credentials
