Control4 MCP Server

Un servidor MCP seguro por defecto que expone su automatización del hogar Control4 (luces, escenas, cerraduras, termostatos y medios) como herramientas estructuradas a través de HTTP y Claude Desktop STDIO para un control confiable impulsado por IA en su red local.

GitHub
3
Prueba este MCPPatrocinado

Documentación

c4-mcp

Convierte tu sistema Control4 en un conjunto de herramientas Model Context Protocol (MCP), para que cualquier cliente compatible con MCP (Claude Desktop, agentes personalizados, scripts) pueda consultar habitaciones/dispositivos y ejecutar automatizaciones de forma segura.

CI License: MIT

Por qué es interesante

  • Funciona con clientes MCP reales: transporte HTTP para desarrollo/scripts + STDIO JSON-RPC para clientes como Claude Desktop.
  • Un único punto de integración para muchos clientes: usa el mismo conjunto de herramientas desde Claude Desktop, scripts o tus propios agentes sin reescribir la lógica de Control4.
  • Esquemas de herramientas estructurados = menos errores: entradas/salidas explícitas (IDs de habitación/dispositivo, niveles, puntos de consigna, etc.) reducen la ambigüedad frente a automatizaciones basadas solo en prompts.
  • Controles seguros por defecto: protecciones de escritura opcionales, modo solo lectura y listas de permitidos/denegados para herramientas que cambian el estado.
  • Memoria de sesión para seguimientos: permite flujos naturales de varios pasos como "enciende las luces del sótano… ahora atenúa esas luces".
  • Semántica de "luces" más inteligente: las operaciones de iluminación basadas en habitaciones evitan apuntar accidentalmente a ventiladores/calefactores/enchufes.
  • Validación con un solo comando: un ejecutor de extremo a extremo ejercita HTTP + STDIO para que puedas publicar cambios con confianza.
  • Rendimiento ajustable: caché de inventario + timeouts configurables por variables de entorno para proyectos Control4 más lentos.
  • Las credenciales permanecen locales: mantén config.json en tu máquina (ignorado por git) y elige STDIO solo local o HTTP en LAN según tu tolerancia al riesgo.

Qué puedes hacer

  • Descubrir habitaciones/dispositivos por nombre, categoría y habitación (además de resolvedores para llamadas "de mejor esfuerzo" basadas en nombre).
  • Activar escenas, controlar persianas, consultar variables/comandos y (opcionalmente) cambiar el estado (luces/cerraduras/termostato/medios).
  • Usarlo como un "cerebro de automatización del hogar" local para chat + agentes sin codificar los IDs de dispositivos de tu proyecto.

Reglas innegociables

  1. c4-mcp debe permanecer desacoplado de cualquier aplicación cliente específica (incluido c4-mcp-app).

    • La integración es vía MCP sobre HTTP/STDIO únicamente.
    • Sin código compartido ni importaciones entre repos; los clientes deben tratar c4-mcp como una dependencia externa.

  2. El cliente (IA/aplicación) es dueño de la interpretación de comandos; c4-mcp es dueño de la ejecución + seguridad.

    • El cliente decide qué herramientas llamar y con qué argumentos (y en qué secuencia).
    • c4-mcp valida entradas, aplica protecciones, ejecuta llamadas a herramientas y devuelve resultados estructurados/ambigüedad.

Ejemplos de prompts (copiar/pegar)

Funcionan bien en clientes MCP como Claude Desktop (el cliente llamará a las herramientas internamente):

List all rooms.

Show me the lights in the Basement.

Turn on the basement lights.

Now dim those lights to 30%.

Activate the "Movie Time" scene in the Living Room.

Which doors are currently unlocked?

Prompts avanzados (difíciles en la UI estándar de la app Control4)

Estos son ejemplos del tipo de solicitudes entre dispositivos, condicionales y de varios pasos que son complicadas (o imposibles) de hacer puramente en la UI estándar de la app Control4 sin construir lógica de automatización personalizada en otro lugar.

Nota: los prompts que cambian el estado (luces/cerraduras/termostato/medios) requieren C4_WRITES_ENABLED=true. Los prompts de solo lectura (inventario/estado/informes) funcionan bien con el valor seguro por defecto C4_WRITES_ENABLED=false.

Run a “Good Night” sweep: turn off all lights except Hallway (10%), lock all exterior doors, set Downstairs thermostat to 68°F, then report what succeeded/failed.

If any door is unlocked, lock it — but do NOT lock the Garage door.

Find anything in the Basement that is currently on (lights, outlets), list it, then turn off everything except the dehumidifier outlet.

I’m leaving: turn off all AV devices, activate the “Away” scene, and confirm the house is secured (all locks locked).

The Basement lights are on — tell me which specific loads are on and turn off only the ones that are above 50%.

Compare the Living Room lights vs. Kitchen lights: which room is brighter right now? Then set them to match.

Do a safety check: list any unlocked doors, any lights left on in the Basement, and the current thermostat setpoints for each zone.

Consejo: si ejecutas con C4_WRITE_GUARDRAILS=true y C4_WRITES_ENABLED=false, obtendrás una experiencia segura de solo lectura hasta que habilites explícitamente las escrituras.

Ambigüedad y desambiguación (recomendado)

Las herramientas basadas en nombre pueden legítimamente devolver múltiples coincidencias (por ejemplo, "Sótano" podría coincidir con varias habitaciones). En ese caso, c4-mcp devuelve un fallo estructurado con un marcador ambiguo y una lista de candidatos.

Patrón recomendado para el cliente:

  1. Llama a la herramienta basada en nombre con include_candidates=true (o acepta el valor por defecto si la herramienta siempre los incluye).
  2. Si la respuesta indica ambigüedad, muestra los candidatos al usuario y deja que elija.
  3. Vuelve a llamar a la herramienta con require_unique=true y un alcance más específico (por ejemplo, room_id / room_name, o el device_name exacto).

Así es como las aplicaciones de nivel superior pueden soportar comandos naturales como "enciende las luces del sótano" mientras siguen siendo deterministas y seguras.

Ejemplos HTTP directos (sin necesidad de cliente MCP)

Si aún no usas un cliente MCP, igualmente puedes llamar al servidor directamente.

Listar herramientas:

  • GET http://127.0.0.1:3333/mcp/list

Nota para Synology/Compose:

  • Dentro de Docker/Compose, c4-mcp normalmente escucha en :3333.
  • En el NAS/LAN, a menudo se publica como puerto del host :3334 → contenedor :3333.
    • Ejemplo: GET http://<NAS_IP>:3334/mcp/list

Llamar a una herramienta (ejemplo: listar habitaciones):

PowerShell:

$base = 'http://127.0.0.1:3333'  # or: http://<NAS_IP>:3334
Invoke-RestMethod -Method Post -Uri ($base + '/mcp/call') -ContentType 'application/json' -Body (
	@{ kind = 'tool'; name = 'c4_list_rooms'; args = @{} } | ConvertTo-Json -Depth 10
)

curl:

curl -s http://127.0.0.1:3333/mcp/call \
	-H "Content-Type: application/json" \
	-d '{"kind":"tool","name":"c4_list_rooms","args":{}}'

Consejos para PowerShell (Windows)

1) /mcp/list devuelve un mapa de herramientas (no un array).

En PowerShell, tools es un PSCustomObject donde cada nombre de propiedad es un nombre de herramienta.

$r = Invoke-RestMethod -Method Get -Uri 'http://127.0.0.1:3333/mcp/list' -TimeoutSec 10
$toolNames = $r.tools.PSObject.Properties.Name | Sort-Object
"tools_count=$($r.tools.PSObject.Properties.Count)"
$toolNames | Select-Object -First 25

2) Inicio/parada rápida en Windows (desacoplado, con registros capturados).

Esto evita confusiones con múltiples terminales / Ctrl+C y facilita la inspección de los registros del servidor.

# Safe-by-default: guardrails on, writes off
$env:C4_WRITE_GUARDRAILS='true'
$env:C4_WRITES_ENABLED='false'
$env:PYTHONUTF8='1'

New-Item -ItemType Directory -Force -Path logs | Out-Null
$p = Start-Process -FilePath .\.venv\Scripts\python.exe -ArgumentList @('app.py') -PassThru -WindowStyle Hidden `
  -RedirectStandardOutput 'logs\http_server_out.txt' -RedirectStandardError 'logs\http_server_err.txt'
$p.Id | Set-Content -Encoding ascii 'logs\http_server.pid'
"started_pid=$($p.Id)"

# Sanity check
Test-NetConnection 127.0.0.1 -Port 3333 | Select-Object TcpTestSucceeded

Detenerlo después:

Stop-Process -Id (Get-Content .\logs\http_server.pid)

Si /mcp/list se cuelga o da error, revisa logs/http_server_err.txt.

Alojamiento en un NAS (Synology) — solo LAN

El servidor HTTP está diseñado para ejecutarse localmente. Para ejecutarlo en un NAS y acceder desde otras máquinas de tu LAN:

  • Vincúlate a todas las interfaces con C4_BIND_HOST=0.0.0.0 (el valor por defecto es solo localhost).
  • Mantenlo solo en LAN usando reglas de firewall de Synology (recomendado) o una VPN (para acceso remoto posterior).

Docker (recomendado en Synology)

Este repositorio incluye un Dockerfile y un docker-compose.yml.

En Synology (Container Manager), ejecuta un proyecto compose que:

  • Publique el puerto 3333 a tu LAN.
  • Monte tu config.json real (mantén las credenciales fuera de git).
  • Mantenga las escrituras desactivadas por defecto: C4_WRITES_ENABLED=false.

Antes de iniciar el proyecto compose, crea tu archivo de configuración local:

  • Copia config.example.json → config.json y completa los valores (este repositorio ignora config.json).

docker-compose.yml ya establece C4_BIND_HOST=0.0.0.0.

Nota solo LAN: no expongas el puerto 3333 a internet. Usa el Firewall de Synology para permitir solo tu subred LAN (por ejemplo, 192.168.0.0/16) para acceder al TCP 3333.

Solución de problemas de compilaciones en Synology

Si Container Manager falla con un error como:

unable to prepare context: unable to evaluate symlinks in Dockerfile path: lstat /volume1/...

Eso significa que Docker no puede encontrar o acceder a la carpeta que seleccionaste como contexto de compilación (la carpeta que debería contener tu Dockerfile y el código fuente).

Solución:

  • Coloca los archivos del repositorio en el NAS bajo una ruta real de carpeta compartida, por ejemplo, /volume1/docker/c4-mcp/.
  • Asegúrate de que esa carpeta contenga al menos: Dockerfile, docker-compose.yml, requirements.txt, app.py y los módulos de Python.
  • En Container Manager, crea el proyecto Compose usando esa carpeta exacta como ruta del proyecto (no lo apuntes solo a /volume1/docker/ a menos que los archivos estén realmente allí).
  • Si tu carpeta compartida no está en volume1, usa el volumen correcto (por ejemplo, /volume2/...).

Variables de entorno de host/puerto

  • C4_BIND_HOST (valor por defecto 127.0.0.1)
  • C4_PORT (valor por defecto 3333)

Ejemplo (LAN): C4_BIND_HOST=0.0.0.0 y C4_PORT=3333

Nota de seguridad / publicación (léela)

Este proyecto se comunica con tu sistema Control4 usando credenciales (y a menudo una IP de controlador local).

  • Nunca confirmes credenciales reales. Mantén config.json solo local (está ignorado por .gitignore).
  • Si accidentalmente confirmaste credenciales en algún momento, rótalas inmediatamente y reescribe el historial de git antes de hacer público el repositorio.

Lista de verificación para GitHub público (haz esto antes de publicar)

  • Asegúrate de que config.json no esté en el historial de git. Como mínimo, no debería estar rastreado en tu árbol actual.
    • Verificación rápida: git ls-files config.json debería devolver nada.
    • Si alguna vez se confirmó: rota tu contraseña de Control4 y reescribe el historial (por ejemplo, git filter-repo), luego haz force-push.
  • Prefiere C4_CONFIG_PATH (apuntando a un archivo fuera del repositorio) para la configuración más segura.

Metadatos de registro

Esta sección está pensada para ser fácil de copiar/pegar para registros MCP y directorios de "listas de servidores".

  • Nombre: c4-mcp
  • Categoría: Automatización del Hogar / Control4
  • Repositorio: https://github.com/randybritsch/c4-mcp
  • Licencia: MIT
  • Transportes:
    • STDIO (JSON-RPC): claude_stdio_server.py (para Claude Desktop y otros clientes MCP basados en stdio)
      • HTTP: app.py (valor por defecto http://127.0.0.1:3333; anular con C4_BIND_HOST/C4_PORT; endpoints: /mcp/list, /mcp/call)
  • Configuración / secretos:
    • Recomendado: establece C4_CONFIG_PATH a un config.json local que contenga host, username, password (mantén este archivo ignorado por git)
    • Opcional: establece C4_HOST (no secreto) para anular host desde config.json
    • Opcional: establece C4_USERNAME/C4_PASSWORD (secreto) vía variables de entorno del SO (deben proporcionarse juntas)
  • Valores seguros por defecto (recomendados):
    • Para ejecuciones de solo lectura por defecto: C4_WRITE_GUARDRAILS=true + C4_WRITES_ENABLED=false
    • Filtros opcionales: C4_WRITE_ALLOWLIST / C4_WRITE_DENYLIST
      • Las escrituras del Agente de Programación están adicionalmente restringidas: c4_scheduler_set_enabled requiere C4_SCHEDULER_WRITES_ENABLED=true

Nota sobre la versión de Python (importante)

Este proyecto depende de flask-mcp-server, que a su vez depende de pydantic/pydantic-core. Al momento de escribir esto, Python 3.14 no funcionará de inmediato en Windows porque pydantic-core aún no incluye wheels para esa versión.

Usa Python 3.12 (recomendado) u otra versión con wheels de pydantic-core disponibles.

Instalación desde PyPI (recomendado para la mayoría de usuarios)

Si solo quieres usar el servidor (no modificar el repositorio), puedes instalarlo desde PyPI:

  • python -m pip install c4-mcp

Luego ejecuta cualquiera de los dos transportes:

  • STDIO (para Claude Desktop / clientes MCP stdio): c4-mcp
  • HTTP (para scripts / curl / desarrollo local): c4-mcp-http

Aún necesitas proporcionar la configuración de Control4 vía C4_CONFIG_PATH (recomendado) o C4_HOST/C4_USERNAME/C4_PASSWORD.

Instalación fácil (casi un solo comando)

Si tienes Node.js + npm instalados, puedes preparar el venv de Python + dependencias con un solo comando:

Luego:

  • Inicia el servidor HTTP: npm run start
  • Inicia el servidor STDIO (estilo Claude): npm run start:stdio
  • Ejecuta verificaciones de extremo a extremo: npm run e2e

Esto es solo un envoltorio de conveniencia alrededor de los pasos de configuración de Python existentes (crea .venv e instala requirements.txt).

Configuración

Este proyecto está pensado para funcionar con cualquier sistema Control4. Nada en el servidor está codificado para un hogar específico.

  1. Instala las dependencias (en un venv)

Este repositorio usa requirements.txt como fuente de verdad.

Windows (PowerShell):

  • python -m venv .venv
  • .\.venv\Scripts\Activate.ps1
  • python -m pip install -r requirements.txt

macOS / Linux (bash/zsh):

  • python3 -m venv .venv
  • source .venv/bin/activate
  • python -m pip install -r requirements.txt
  1. Proporciona la configuración de conexión a Control4 mediante:
  • Variables de entorno:
    • C4_HOST (IP o nombre de host del Director/Controlador; esquema opcional)
    • C4_USERNAME (correo de la cuenta Control4)
    • C4_PASSWORD (contraseña de la cuenta Control4)

o

  • Un archivo de configuración local (no confirmado): copia config.example.json a config.json y completa los valores.

Configuración de VS Code (recomendado)

  1. Instala las extensiones de VS Code
  • Python (ms-python.python)
  • Pylance (ms-python.vscode-pylance)
  1. Abre la carpeta del repositorio en VS Code
  • Archivo → Abrir carpeta… → selecciona este repositorio.
  1. Crea/selecciona un entorno virtual

Opción A (UI de VS Code):

  • Ctrl+Shift+P → Python: Create Environment → elige venv → selecciona tu intérprete de Python 3.12.

Opción B (terminal):

  • python -m venv .venv
  • Actívalo (consulta la sección de Configuración arriba)
  • Ctrl+Shift+P → Python: Select Interpreter → elige .venv
  1. Instala las dependencias
  • python -m pip install -r requirements.txt
  1. Proporciona la configuración de Control4 durante el desarrollo
  • Archivo de configuración: copia config.example.json → config.json (se mantiene solo local; ignorado por git)

o

  • Variables de entorno: establece C4_HOST, C4_USERNAME, C4_PASSWORD

Consejo (compatible con VS Code): crea un archivo .env local en la raíz del repositorio (ignorado por git) y úsalo desde una configuración de depuración.

  1. Ejecuta el servidor
  • Terminal de VS Code: python app.py
  1. Opcional: Depurar con F5

Crea un .vscode/launch.json local (este repositorio ignora .vscode/ por defecto) como:

{
	"version": "0.2.0",
	"configurations": [
		{
			"name": "c4-mcp (HTTP server)",
			"type": "python",
			"request": "launch",
			"program": "${workspaceFolder}/app.py",
			"console": "integratedTerminal",
			"justMyCode": true,
			"envFile": "${workspaceFolder}/.env"
		},
		{
			"name": "c4-mcp (STDIO server)",
			"type": "python",
			"request": "launch",
			"program": "${workspaceFolder}/claude_stdio_server.py",
			"console": "integratedTerminal",
			"justMyCode": true,
			"envFile": "${workspaceFolder}/.env"
		}
	]
}

Configuración inicial (recomendada)

Si estás configurando esto por primera vez y aún no conoces la IP de tu controlador, este es el flujo más rápido:

  1. Establece las credenciales para el descubrimiento y el inicio de sesión del servidor:

Windows (PowerShell):

  • $env:C4_USERNAME = "you@example.com"
  • $env:C4_PASSWORD = "your-password"

macOS / Linux (bash/zsh):

  • export C4_USERNAME="you@example.com"
  • export C4_PASSWORD="your-password"
  1. Descubre automáticamente la IP del controlador y escríbela en config.json:
  • python tools\discover_controller.py --write
  1. Inicia el servidor MCP:
  • python app.py
  1. Verifica que esté activo:
  • GET http://127.0.0.1:3333/mcp/list

Opcional: descubrir automáticamente la IP del controlador (compatible con Windows)

Si aún no conoces la IP del controlador, puedes ejecutar un escaneo de descubrimiento LAN de mejor esfuerzo y, opcionalmente, escribir la IP descubierta en config.json:

  • Ejecución de prueba (sin escrituras): python tools\discover_controller.py
  • Escribir host en config.json: python tools\discover_controller.py --write

Notas:

  • Escanea solo las subredes locales detectadas desde ipconfig (o usa --subnet 192.168.1.0/24).
  • Utiliza tiempos de espera limitados por host y límites de concurrencia.
  • Si config.json no existe, puedes configurar C4_USERNAME y C4_PASSWORD para que el script pueda crearlo.

Ejecutar

  • Iniciar servidor: python app.py
  • Verificar que MCP esté activo: GET http://127.0.0.1:3333/mcp/list

Validación de extremo a extremo (un solo comando)

Esto inicia el servidor HTTP en modo de protecciones de solo lectura, ejecuta la suite de validación HTTP, ejecuta ambos validadores STDIO y luego detiene el servidor.

Windows (PowerShell):

  • .\.venv\Scripts\python.exe tools\run_e2e.py

macOS / Linux (bash/zsh):

  • ./.venv/bin/python tools/run_e2e.py

Si ya tienes el servidor en ejecución y solo quieres ejecutar los validadores:

Windows (PowerShell):

  • .\.venv\Scripts\python.exe tools\run_e2e.py --no-server --base-url http://127.0.0.1:3333

macOS / Linux (bash/zsh):

  • ./.venv/bin/python tools/run_e2e.py --no-server --base-url http://127.0.0.1:3333

Configuración de Claude Desktop (MCP stdio) (Windows)

Claude Desktop inicia servidores MCP a través de STDIO (inicia un subproceso y habla JSON-RPC a través de stdin/stdout).

Claude Desktop utiliza la superficie de métodos oficial de MCP (initialize, tools/list, tools/call). Este repositorio incluye un pequeño adaptador, claude_stdio_server.py, que adapta la superficie de métodos de Claude al registro de herramientas Flask MCP existente.

  1. Crea tu venv usando Python 3.12 (recomendado; 3.13 también funciona):
  • py -3.12 -m venv .venv
  • .\.venv\Scripts\Activate.ps1
  • python -m pip install -r requirements.txt
  1. Edita la configuración de Claude Desktop:
  • Archivo: %APPDATA%\Claude\claude_desktop_config.json

Nota de seguridad: evita pegar tu contraseña de Control4 directamente en el archivo de configuración de Claude Desktop. Prefiere una de estas opciones más seguras:

  • Coloca las credenciales en un config.json local en este repositorio (ignorado por git), y mantén solo configuraciones no secretas en la configuración de Claude.
  • O establece C4_USERNAME / C4_PASSWORD como variables de entorno del sistema operativo, y omítelas en la configuración de Claude.

Configuración recomendada del lado de Claude: establece solo C4_CONFIG_PATH (apuntando a tu config.json local) y mantén todos los secretos fuera de Claude Desktop. Si estableces C4_USERNAME/C4_PASSWORD mediante variables de entorno, deben proporcionarse juntas.

Agrega una entrada de servidor MCP como esta (edita rutas y variables de entorno opcionales):

{
	"mcpServers": {
		"c4-mcp": {
			"command": "C:\\Users\\YOUR_USER\\c4-mcp\\.venv\\Scripts\\python.exe",
			"args": ["-u", "C:\\Users\\YOUR_USER\\c4-mcp\\claude_stdio_server.py"],
			"cwd": "C:\\Users\\YOUR_USER\\c4-mcp",
			"env": {
				"PYTHONUTF8": "1",
				"PYTHONIOENCODING": "utf-8",
				"C4_STDIO_TOOL_MODE": "compact",
				"C4_CONFIG_PATH": "C:\\Users\\YOUR_USER\\c4-mcp\\config.json",
				"C4_WRITE_GUARDRAILS": "true",
				"C4_WRITES_ENABLED": "false",
				"C4_DIRECTOR_TIMEOUT_S": "30",
				"C4_GET_ALL_ITEMS_TIMEOUT_S": "75"
			}
		}
	}
}

Notas:

  • -u se recomienda en Windows para que las respuestas JSON-RPC de STDIO no se almacenen en búfer.
  • C4_STDIO_TOOL_MODE=compact mantiene tools/list pequeño y evita que Claude Desktop se atasque con un catálogo de herramientas enorme. Configúralo en all para exponer todo.

Si Claude no puede iniciar el servidor y ves un error como:

python.exe: can't open file '...\\AnthropicClaude\\...\\mcp_cli.py': [Errno 2] No such file or directory

significa que Claude está intentando resolver una ruta relativa desde su propio directorio de instalación. Corrígelo usando rutas absolutas para los scripts en args y manteniendo cwd configurado en la raíz del repositorio.

Consejo: establece C4_STDIO_DEBUG=true en la configuración de Claude env para registrar cada solicitud/respuesta JSON-RPC en el registro MCP de Claude.

Si usas config.json para las credenciales, copia config.example.json a config.json y establece host, username y password allí.

Si Claude inicia el servidor pero las llamadas a herramientas fallan y ves un error como:

RuntimeError: Invalid config file '...\\config.json': username/password must be non-empty (or provide C4_USERNAME/C4_PASSWORD env vars)

entonces tu config.json tiene credenciales en blanco. Corrígelo completando username/password en config.json o estableciendo C4_USERNAME y C4_PASSWORD en la configuración de Claude env (deben proporcionarse juntas).

Variables de entorno opcionales (no secretas) que puedes agregar a la configuración de Claude si es necesario:

  • C4_CONFIG_PATH: apunta a un config.json almacenado en otro lugar

Para cambiar el host de Director, edita config.json (recomendado) o apunta C4_CONFIG_PATH a un archivo de configuración diferente.

  1. Reinicia Claude Desktop.

Si todo está conectado correctamente, Claude debería mostrar las herramientas c4-mcp como disponibles.

Notas:

  • Todo el registro no relacionado con protocolo debe ir a stderr; el registro de este repositorio usa stderr por defecto.
  • Si deseas habilitar herramientas de escritura, cambia C4_WRITES_ENABLED a true (las protecciones aún se aplican).

Solución de problemas de tiempos de espera

Si el listado de habitaciones/dispositivos agota el tiempo de espera en la primera ejecución, aumenta estos valores (configuración de Claude env o tu entorno de shell):

  • C4_DIRECTOR_TIMEOUT_S (tiempo de espera por solicitud a Director)
  • C4_GET_ALL_ITEMS_TIMEOUT_S (tiempo de espera general para la obtención del inventario)

Opcional: protecciones de escritura (recomendado por seguridad)

Por defecto, las herramientas que cambian el estado (cerraduras, luces, termostato, control remoto multimedia, etc.) están bloqueadas a menos que habilites explícitamente las escrituras. Si deseas una capa de seguridad adicional (recomendado), establece:

  • C4_WRITE_GUARDRAILS=true (activa la aplicación de reglas)
  • C4_WRITES_ENABLED=false (mantén las herramientas de escritura bloqueadas; cambia a true cuando realmente quieras escrituras)

Filtros opcionales (nombres de herramientas separados por comas):

  • C4_WRITE_ALLOWLIST=c4_light_set_level,c4_light_ramp (solo permite estas herramientas de escritura)
  • C4_WRITE_DENYLIST=c4_lock_unlock,c4_lock_lock (bloquea estas herramientas de escritura)

Ajustes de rendimiento

Algunas herramientas dependen de escaneos de inventario (get_all_items) para la resolución basada en nombres y el listado. Puedes acelerarlos con un pequeño caché en proceso:

  • C4_ITEMS_CACHE_TTL_S=5 (por defecto) almacena en caché el inventario durante 5 segundos
  • C4_ITEMS_CACHE_TTL_S=0 desactiva el caché

Descubrir IDs

Los IDs de dispositivos y habitaciones son específicos de tu proyecto Control4. Usa:

  • c4_list_rooms
  • c4_find_rooms / c4_resolve_room (búsqueda por nombre)
  • c4_list_devices (por categoría)
  • c4_list_devices categoría: shades (descubrimiento de mejor esfuerzo)
  • c4_list_devices categoría: scenes (de mejor esfuerzo; basado en botones de interfaz)
  • c4_find_devices / c4_resolve_device (búsqueda por nombre; filtros opcionales de categoría/habitación)
  • c4_resolve (resuelve habitación y dispositivo juntos; la resolución del dispositivo puede limitarse a la habitación resuelta)

Persianas / cortinas (de mejor esfuerzo)

Si tu proyecto tiene persianas/cortinas, prueba:

  • c4_shade_list
  • c4_shade_get_state (devuelve position 0-100 cuando está disponible)
  • c4_shade_open / c4_shade_close / c4_shade_stop
  • c4_shade_set_position

Solución de problemas:

  • Usa c4_item_commands(device_id) para ver los nombres exactos de comandos que expone tu controlador de persianas.
  • Usa c4_item_variables(device_id) para inspeccionar qué variable contiene la posición/nivel.

Luego pasa los IDs descubiertos a herramientas como c4_media_watch_launch_app o los scripts en tools/.

Si prefieres llamadas basadas en nombres (sin IDs), usa c4_media_watch_launch_app_by_name.

Escenas de iluminación (de mejor esfuerzo)

Las "escenas" de Control4 varían según el proyecto. En muchos proyectos aparecen como dispositivos de botones de interfaz.

Prueba:

  • c4_scene_list (alias de c4_uibutton_list)
  • c4_scene_activate(device_id) (alias de c4_uibutton_activate)
  • c4_scene_activate_by_name(scene_name, room_name=...) (resolvedor de mejor esfuerzo + activación)

Solución de problemas:

  • Usa c4_item_commands(device_id) para ver qué comando(s) admite una escena/botón determinado.
  • Validador de solo lectura: .\.venv\Scripts\python.exe tools\validate_scenes.py --show-commands