foscam-controller 0.1.0

Herramientas unificadas para gestionar cámaras Foscam: descubrir, configurar, visor y consola CGI

Foscam Controller

Herramientas unificadas para gestionar cámaras Foscam en la red: descubrimiento, configuración, visor en vivo y consola CGI. Compatible con la API CGI de la mayoría de modelos (FI98xx, C1, R2, etc.).

Instalación con pipx (recomendado)

pipx install .

Tras la instalación tendrás el comando foscam disponible globalmente. Para actualizar o desinstalar:

pipx upgrade foscam-controller
pipx uninstall foscam-controller   # desinstalar

Características

• Descubrimiento: Escaneo de la red local para encontrar cámaras Foscam (puertos 80, 88, 8080).
• Configuración: Exportar toda la configuración de una cámara a JSON y aplicarla a otras (con modo dry-run).
• Visor: GUI para ver el stream RTSP en vivo, control PTZ con flechas, snapshot, audio (PyAV o ffplay).
• Consola CGI: Terminal con autocompletado (Tab) para probar cualquier comando de la API.

Requisitos

• Python 3.7+
• Red local con cámaras Foscam (misma subred)

Para el visor con audio: av, sounddevice y opcionalmente ffplay (FFmpeg). Para decodificación por GPU: OpenCV con GStreamer y plugins nvcodec (NVIDIA).

Instalación desde código (desarrollo)

cd foscam_controller
python3 -m venv venv
source venv/bin/activate   # Windows: venv\Scripts\activate
pip install -e .

Uso

Con pipx (o tras pip install -e .), usa el comando foscam:

foscam discover
foscam config --ip 192.168.1.6 --user admin --password xxx --save cam.json
foscam view --ip 192.168.1.6 --user admin --password xxx

Desde el directorio del proyecto también puedes usar:

python -m foscam discover
python -m foscam view --ip ... --user ... --password ...

Descubrir cámaras

foscam discover
foscam discover --network 192.168.1.0/24 --workers 100

Obtener configuración

foscam config --ip 192.168.1.6 --user admin --password tu_password [--port 88] [--save cam.json]

Aplicar configuración desde JSON

# Vista previa (recomendado primero)
foscam apply --ip 192.168.1.7 --user admin --password xxx --file cam.json --dry-run
# Aplicar
foscam apply --ip 192.168.1.7 --user admin --password xxx --file cam.json

Visor en vivo

foscam view --ip 192.168.1.6 --user admin --password xxx [--port 88] [--sub] [--nvidia]

• Flechas: mover PTZ (mantener para mover, soltar para parar).
• 0: ir al preset por defecto (ptzReset).
• a / z: subir / bajar volumen de audio.
• Snapshot: guarda una captura.

También puedes ejecutar el visor como módulo:

python -m foscam.viewer --ip 192.168.1.6 --user admin --password xxx [--sub] [--audio-gate-db -38] [--nvidia]

Consola de comandos CGI

foscam console --ip 192.168.1.6 --user admin --password xxx [--port 88]

Dentro de la consola: help, list, doc <comando>, y cualquier comando CGI con parámetros clave=valor. Usa Tab para autocompletar.

Estructura del proyecto

foscam_controller/
├── pyproject.toml      # Metadatos y entry point para pip/pipx
├── requirements.txt
├── README.md
├── foscam/
│   ├── __init__.py
│   ├── __main__.py     # python -m foscam
│   ├── cli.py          # CLI principal (discover, config, apply, view, console)
│   ├── client.py       # Cliente HTTP para la API CGI (FoscamClient)
│   ├── discover.py    # Descubrimiento de cámaras en la red
│   ├── config_io.py   # Lectura/escritura de configuración (JSON)
│   ├── viewer.py       # Visor GUI (stream RTSP + PTZ + snapshot + audio)
│   └── cgi_console.py  # Consola interactiva para la API CGI
├── scripts/
│   └── publish_to_pypi.sh   # Publicar en PyPI (o Test PyPI con --test)
├── foscam_control_repo/    # Repo original (solo referencia)
└── configurador_foscam_repo/  # Repo original (solo referencia)

Uso como biblioteca

from foscam.client import FoscamClient
from foscam.discover import FoscamDiscoverer
from foscam.config_io import FoscamConfigReader, FoscamConfigWriter

# Cliente para una cámara
client = FoscamClient("192.168.1.6", "admin", "password", port=88)
print(client.get_dev_name())   # Información del dispositivo
client.ptz_move("Up")          # Mover arriba
client.ptz_stop()              # Parar

# Descubrir cámaras
disc = FoscamDiscoverer("192.168.1.0/24")
cameras = disc.discover(show_progress=True)

# Leer y guardar configuración
reader = FoscamConfigReader(client)
config = reader.get_all_config(show_progress=True)
reader.save_to_file("backup.json", config)

# Aplicar configuración
writer = FoscamConfigWriter(client)
writer.apply_from_file("backup.json", dry_run=False)

Seguridad

• No subas archivos JSON de configuración que contengan contraseñas.
• Usa --dry-run antes de aplicar configuración a producción.

Publicar en PyPI

Para publicar el paquete en PyPI (o en Test PyPI para pruebas):

1. Instalar herramientas: pip install build twine

2. Configurar token de PyPI (en https://pypi.org/manage/account/token/):

   export TWINE_USERNAME=__token__
   export TWINE_PASSWORD=pypi-xxxxxxxx
   

3. Publicar:

   ./scripts/publish_to_pypi.sh          # PyPI real
   ./scripts/publish_to_pypi.sh --test   # Test PyPI
   

Para Test PyPI usa el token de https://test.pypi.org/manage/account/token/

Referencias

• API CGI Foscam: documentación oficial del fabricante (Foscam IPCamera CGI User Guide).