Control4 MCP Server

Um servidor MCP seguro por padrão que expõe sua automação residencial Control4 (luzes, cenas, fechaduras, termostatos e mídia) como ferramentas estruturadas via HTTP e Claude Desktop STDIO para controle confiável com IA em sua rede local.

GitHub
3
Experimente este MCPPatrocinado

Documentação

c4-mcp

Transforme seu sistema Control4 em um conjunto de ferramentas Model Context Protocol (MCP), para que qualquer cliente compatível com MCP (Claude Desktop, agentes personalizados, scripts) possa consultar salas/dispositivos e executar automações com segurança.

CI License: MIT

Por que isso é interessante

  • Funciona com clientes MCP reais: transporte HTTP para desenvolvimento/scripts + STDIO JSON-RPC para clientes como Claude Desktop.
  • Um único ponto de integração para vários clientes: use o mesmo conjunto de ferramentas do Claude Desktop, scripts ou seus próprios agentes sem reescrever a lógica do Control4.
  • Esquemas de ferramentas estruturados = menos erros: entradas/saídas explícitas (IDs de sala/dispositivo, níveis, setpoints, etc.) reduzem ambiguidade em comparação com automações baseadas apenas em prompts.
  • Controles seguros por padrão: proteções opcionais de escrita, modo somente leitura e listas de permissão/negação para ferramentas que alteram estado.
  • Memória de sessão para acompanhamentos: permite fluxos naturais de múltiplas etapas como "acenda as luzes do porão... agora diminua essas luzes".
  • Semântica mais inteligente de "luzes": operações de iluminação baseadas em sala evitam atingir acidentalmente ventiladores/aquecedores/tomadas.
  • Validação com um comando: um executor de ponta a ponta exercita HTTP + STDIO para que você possa publicar alterações com confiança.
  • Desempenho ajustável: cache de inventário + timeouts configuráveis por ambiente para projetos Control4 mais lentos.
  • Credenciais permanecem locais: mantenha config.json na sua máquina (ignorado pelo git) e escolha STDIO somente local ou HTTP na LAN, conforme sua tolerância a risco.

O que você pode fazer

  • Descobrir salas/dispositivos por nome, categoria e sala (além de resolvedores para chamadas "melhor esforço" baseadas em nome).
  • Ativar cenas, controlar persianas, consultar variáveis/comandos e (opcionalmente) alterar estado (luzes/fechaduras/termostato/mídia).
  • Usar como um "cérebro de automação residencial" local para chat + agentes sem codificar os IDs de dispositivos do seu projeto.

Regras inegociáveis

  1. c4-mcp deve permanecer desacoplado de qualquer aplicativo cliente específico (incluindo c4-mcp-app).

    • A integração é via MCP sobre HTTP/STDIO apenas.
    • Sem código compartilhado ou imports entre repositórios; clientes devem tratar c4-mcp como uma dependência externa.

  2. O cliente (IA/aplicativo) é dono da interpretação de comandos; c4-mcp é dono da execução + segurança.

    • O cliente decide quais ferramentas chamar e com quais argumentos (e em qual sequência).
    • c4-mcp valida entradas, aplica proteções, executa chamadas de ferramentas e retorna resultados estruturados/ambiguidade.

Exemplos de prompts (copiar/colar)

Funcionam bem em clientes MCP como Claude Desktop (o cliente chamará as ferramentas nos bastidores):

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 avançados (difíceis na interface padrão do app Control4)

Estes são exemplos do tipo de solicitações entre dispositivos, condicionais e de múltiplas etapas que são complicadas (ou impossíveis) de fazer puramente na interface padrão do app Control4 sem construir lógica de automação personalizada em outro lugar.

Nota: prompts que alteram estado (luzes/fechaduras/termostato/mídia) exigem C4_WRITES_ENABLED=true. Prompts somente leitura (inventário/status/relatórios) funcionam bem com o padrão seguro 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.

Dica: se você executar com C4_WRITE_GUARDRAILS=true e C4_WRITES_ENABLED=false, terá uma experiência segura somente leitura até habilitar explicitamente escritas.

Ambiguidade e desambiguação (recomendado)

Ferramentas baseadas em nome podem legitimamente retornar múltiplas correspondências (ex.: "Porão" pode corresponder a várias salas). Nesse caso, c4-mcp retorna uma falha estruturada com um marcador ambíguo e uma lista de candidatos.

Padrão recomendado para o cliente:

  1. Chame a ferramenta baseada em nome com include_candidates=true (ou aceite o padrão se a ferramenta sempre os incluir).
  2. Se a resposta indicar ambiguidade, mostre os candidatos ao usuário e deixe-o escolher.
  3. Rechame a ferramenta com require_unique=true e um escopo mais específico (ex.: room_id / room_name, ou device_name exato).

É assim que aplicativos de nível superior podem suportar comandos naturais como "acenda as luzes do porão" enquanto ainda são determinísticos e seguros.

Exemplos HTTP diretos (sem cliente MCP necessário)

Se você ainda não usa um cliente MCP, ainda pode chamar o servidor diretamente.

Listar ferramentas:

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

Nota Synology/Compose:

  • Dentro do Docker/Compose, c4-mcp normalmente escuta em :3333.
  • No NAS/LAN, geralmente é publicado como porta do host :3334 → contêiner :3333.
    • Exemplo: GET http://<NAS_IP>:3334/mcp/list

Chamar uma ferramenta (exemplo: listar salas):

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":{}}'

Dicas para PowerShell (Windows)

1) /mcp/list retorna um mapa de ferramentas (não um array).

No PowerShell, tools é um PSCustomObject onde cada nome de propriedade é um nome de ferramenta.

$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) Início/parada rápida no Windows (destacado, logs capturados).

Isso evita confusão com múltiplos terminais / Ctrl+C e facilita a inspeção dos logs do 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

Para parar depois:

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

Se /mcp/list travar ou der erro, verifique logs/http_server_err.txt.

Hospedagem em um NAS (Synology) — apenas LAN

O servidor HTTP foi projetado para rodar localmente. Para executá-lo em um NAS e acessá-lo de outras máquinas na sua LAN:

  • Vincule a todas as interfaces com C4_BIND_HOST=0.0.0.0 (o padrão é somente localhost).
  • Mantenha-o apenas na LAN usando regras de firewall do Synology (recomendado) ou uma VPN (para acesso remoto posteriormente).

Docker (recomendado no Synology)

Este repositório inclui um Dockerfile e docker-compose.yml.

No Synology (Container Manager), execute um projeto compose que:

  • Publique a porta 3333 na sua LAN.
  • Monte seu config.json real (mantenha credenciais fora do git).
  • Mantenha escritas desativadas por padrão: C4_WRITES_ENABLED=false.

Antes de iniciar o projeto compose, crie seu arquivo de configuração local:

  • Copie config.example.json → config.json e preencha os valores (este repositório ignora config.json).

docker-compose.yml já define C4_BIND_HOST=0.0.0.0.

Nota apenas-LAN: não exponha a porta 3333 à internet. Use o Firewall do Synology para permitir apenas sua sub-rede LAN (ex.: 192.168.0.0/16) alcançar TCP 3333.

Solução de problemas de builds no Synology

Se o Container Manager falhar com um erro como:

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

Isso significa que o Docker não consegue encontrar ou acessar a pasta que você selecionou como contexto de build (a pasta que deve conter seu Dockerfile e código-fonte).

Correção:

  • Coloque os arquivos do repositório no NAS sob um caminho real de pasta compartilhada, ex.: /volume1/docker/c4-mcp/.
  • Garanta que essa pasta contenha pelo menos: Dockerfile, docker-compose.yml, requirements.txt, app.py e os módulos Python.
  • No Container Manager, crie o projeto Compose usando exatamente essa pasta como caminho do projeto (não aponte apenas para /volume1/docker/ a menos que os arquivos estejam realmente lá).
  • Se sua pasta compartilhada não estiver em volume1, use o volume correto (ex.: /volume2/...).

Variáveis de ambiente de host/porta

  • C4_BIND_HOST (padrão 127.0.0.1)
  • C4_PORT (padrão 3333)

Exemplo (LAN): C4_BIND_HOST=0.0.0.0 e C4_PORT=3333

Nota de segurança/publicação (leia isto)

Este projeto fala com seu sistema Control4 usando credenciais (e frequentemente um IP de controlador local).

  • Nunca commite credenciais reais. Mantenha config.json apenas local (é ignorado por .gitignore).
  • Se você acidentalmente comitou credenciais em algum momento, rotacione-as imediatamente e reescreva o histórico do git antes de tornar o repositório público.

Checklist para GitHub público (faça isto antes de publicar)

  • Garanta que config.json não esteja no histórico do git. No mínimo, não deve estar rastreado na sua árvore atual.
    • Verificação rápida: git ls-files config.json deve retornar nada.
    • Se foi commitado alguma vez: rotacione sua senha do Control4 e reescreva o histórico (ex.: git filter-repo), depois force-push.
  • Prefira C4_CONFIG_PATH (apontando para um arquivo fora do repositório) para a configuração mais segura.

Metadados de registro

Esta seção deve ser amigável para copiar/colar em registros MCP e diretórios de "lista de servidores".

  • Nome: c4-mcp
  • Categoria: Automação Residencial / Control4
  • Repositório: https://github.com/randybritsch/c4-mcp
  • Licença: MIT
  • Transportes:
    • STDIO (JSON-RPC): claude_stdio_server.py (para Claude Desktop e outros clientes MCP baseados em stdio)
      • HTTP: app.py (padrão http://127.0.0.1:3333; sobrescreva com C4_BIND_HOST/C4_PORT; endpoints: /mcp/list, /mcp/call)
  • Configuração / segredos:
    • Recomendado: defina C4_CONFIG_PATH para um config.json local que contenha host, username, password (mantenha este arquivo ignorado pelo git)
    • Opcional: defina C4_HOST (não secreto) para sobrescrever host de config.json
    • Opcional: defina C4_USERNAME/C4_PASSWORD (secreto) via variáveis de ambiente do SO (devem ser fornecidas juntas)
  • Padrões de segurança (recomendados):
    • Para execuções somente leitura por padrão: C4_WRITE_GUARDRAILS=true + C4_WRITES_ENABLED=false
    • Filtros opcionais: C4_WRITE_ALLOWLIST / C4_WRITE_DENYLIST
      • Escritas do Agente de Agendamento são adicionalmente controladas: c4_scheduler_set_enabled exige C4_SCHEDULER_WRITES_ENABLED=true

Nota sobre versão do Python (importante)

Este projeto depende de flask-mcp-server, que por sua vez depende de pydantic/pydantic-core. No momento da escrita, Python 3.14 não funcionará imediatamente no Windows porque pydantic-core ainda não fornece wheels para ele.

Use Python 3.12 (recomendado) ou outra versão com wheels de pydantic-core disponíveis.

Instalar do PyPI (recomendado para a maioria dos usuários)

Se você só quer usar o servidor (não mexer no repositório), pode instalá-lo do PyPI:

  • python -m pip install c4-mcp

Depois execute qualquer transporte:

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

Você ainda precisa fornecer a configuração do Control4 via C4_CONFIG_PATH (recomendado) ou C4_HOST/C4_USERNAME/C4_PASSWORD.

Instalação fácil (quase um comando)

Se você tem Node.js + npm instalados, pode inicializar o venv Python + dependências com um comando:

Depois:

  • Inicie o servidor HTTP: npm run start
  • Inicie o servidor STDIO (estilo Claude): npm run start:stdio
  • Execute verificações de ponta a ponta: npm run e2e

Isso é apenas um wrapper de conveniência em torno das etapas existentes de configuração Python (cria .venv e instala requirements.txt).

Configuração

Este projeto foi feito para funcionar com qualquer sistema Control4. Nada no servidor é codificado para uma casa específica.

  1. Instale dependências (em um venv)

Este repositório usa requirements.txt como fonte da verdade.

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. Forneça a configuração de conexão do Control4 via:
  • Variáveis de ambiente:
    • C4_HOST (IP/hostname do Director/Controller; esquema opcional)
    • C4_USERNAME (email da conta Control4)
    • C4_PASSWORD (senha da conta Control4)

ou

  • Um arquivo de configuração local (não commitado): copie config.example.json para config.json e preencha os valores.

Configuração do VS Code (recomendado)

  1. Instale extensões do VS Code
  • Python (ms-python.python)
  • Pylance (ms-python.vscode-pylance)
  1. Abra a pasta do repositório no VS Code
  • Arquivo → Abrir Pasta… → selecione este repositório.
  1. Crie/selecione um ambiente virtual

Opção A (interface do VS Code):

  • Ctrl+Shift+P → Python: Create Environment → escolha venv → selecione seu interpretador Python 3.12.

Opção B (terminal):

  • python -m venv .venv
  • Ative-o (veja a seção Configuração acima)
  • Ctrl+Shift+P → Python: Select Interpreter → escolha .venv
  1. Instale dependências
  • python -m pip install -r requirements.txt
  1. Forneça a configuração do Control4 durante o desenvolvimento
  • Arquivo de configuração: copie config.example.json → config.json (mantido apenas local; ignorado pelo git)

ou

  • Variáveis de ambiente: defina C4_HOST, C4_USERNAME, C4_PASSWORD

Dica (amigável ao VS Code): crie um arquivo .env local na raiz do repositório (ignorado pelo git) e use-o a partir de uma configuração de depuração.

  1. Execute o servidor
  • Terminal do VS Code: python app.py
  1. Opcional: Depurar com F5

Crie um .vscode/launch.json local (este repositório ignora .vscode/ por padrão) 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"
		}
	]
}

Configuração inicial (recomendado)

Se você está configurando isso pela primeira vez e ainda não sabe o IP do seu controlador, este é o fluxo mais rápido:

  1. Defina as credenciais para descoberta + login do 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. Descubra automaticamente o IP do controlador e grave-o em config.json:
  • python tools\discover_controller.py --write
  1. Inicie o servidor MCP:
  • python app.py
  1. Verifique se está ativo:
  • GET http://127.0.0.1:3333/mcp/list

Opcional: descobrir automaticamente o IP do controlador (compatível com Windows)

Se você ainda não sabe o IP do controlador, pode executar uma varredura de descoberta LAN de melhor esforço e, opcionalmente, gravar o IP descoberto em config.json:

  • Execução de teste (sem gravações): python tools\discover_controller.py
  • Grave host em config.json: python tools\discover_controller.py --write

Observações:

  • Verifica apenas as sub-redes locais detectadas a partir de ipconfig (ou use --subnet 192.168.1.0/24).
  • Usa timeouts limitados por host + limites de concorrência.
  • Se config.json não existir, você pode definir C4_USERNAME e C4_PASSWORD para que o script possa criá-lo.

Executar

  • Iniciar servidor: python app.py
  • Verificar se o MCP está ativo: GET http://127.0.0.1:3333/mcp/list

Validação de ponta a ponta (um comando)

Isso inicia o servidor HTTP no modo de proteção somente leitura, executa a suíte de validadores HTTP, executa ambos os validadores STDIO e, em seguida, para o servidor.

Windows (PowerShell):

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

macOS / Linux (bash/zsh):

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

Se você já tem o servidor em execução e só quer executar os 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

Configuração do Claude Desktop (MCP stdio) (Windows)

O Claude Desktop inicia servidores MCP via STDIO (ele inicia um subprocesso e fala JSON-RPC via stdin/stdout).

O Claude Desktop usa a superfície de métodos MCP oficial (initialize, tools/list, tools/call). Este repositório inclui um pequeno shim, claude_stdio_server.py, que adapta a superfície de métodos do Claude ao registro de ferramentas MCP Flask existente.

  1. Crie seu venv usando Python 3.12 (recomendado; 3.13 também funciona):
  • py -3.12 -m venv .venv
  • .\.venv\Scripts\Activate.ps1
  • python -m pip install -r requirements.txt
  1. Edite a configuração do Claude Desktop:
  • Arquivo: %APPDATA%\Claude\claude_desktop_config.json

Nota de segurança: evite colar sua senha do Control4 diretamente no arquivo de configuração do Claude Desktop. Prefira uma destas opções mais seguras:

  • Coloque as credenciais em um config.json local neste repositório (ignorado pelo git) e mantenha apenas configurações não secretas na configuração do Claude.
  • Ou defina C4_USERNAME / C4_PASSWORD como variáveis de ambiente do SO e omita-as da configuração do Claude.

Configuração recomendada no lado do Claude: defina apenas C4_CONFIG_PATH (apontando para seu config.json local) e mantenha todos os segredos fora do Claude Desktop. Se você definir C4_USERNAME/C4_PASSWORD via variáveis de ambiente, elas devem ser fornecidas juntas.

Adicione uma entrada de servidor MCP assim (edite caminhos + variáveis de ambiente opcionais):

{
	"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"
			}
		}
	}
}

Observações:

  • -u é recomendado no Windows para que as respostas JSON-RPC STDIO não sejam armazenadas em buffer.
  • C4_STDIO_TOOL_MODE=compact mantém tools/list pequeno e evita que o Claude Desktop engasgue com um catálogo enorme de ferramentas. Defina-o como all para expor tudo.

Se o Claude falhar ao iniciar o servidor e você vir um erro como:

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

isso significa que o Claude está tentando resolver um caminho relativo a partir do seu próprio diretório de instalação. Corrija usando caminhos absolutos para scripts em args e mantendo cwd definido como a raiz do repositório.

Dica: defina C4_STDIO_DEBUG=true na configuração do Claude env para registrar cada solicitação/resposta JSON-RPC no log MCP do Claude.

Se você usar config.json para credenciais, copie config.example.json para config.json e defina host, username e password lá.

Se o Claude iniciar o servidor, mas as chamadas de ferramenta falharem e você vir um erro como:

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

então seu config.json tem credenciais em branco. Corrija preenchendo username/password em config.json ou definindo C4_USERNAME e C4_PASSWORD na configuração do Claude env (elas devem ser fornecidas juntas).

Variáveis de ambiente opcionais (não secretas) que você pode adicionar à configuração do Claude, se necessário:

  • C4_CONFIG_PATH: aponte para um config.json armazenado em outro lugar

Para alterar o host do Director, edite config.json (recomendado) ou aponte C4_CONFIG_PATH para um arquivo de configuração diferente.

  1. Reinicie o Claude Desktop.

Se tudo estiver configurado corretamente, o Claude deve mostrar as ferramentas c4-mcp como disponíveis.

Observações:

  • Todo registro não relacionado ao protocolo deve ir para stderr; o registro deste repositório usa stderr por padrão.
  • Se você quiser habilitar ferramentas de gravação, alterne C4_WRITES_ENABLED para true (as proteções ainda se aplicam).

Solução de problemas de timeouts

Se a listagem de salas/dispositivos expirar na primeira execução, aumente estes valores (configuração do Claude env ou ambiente do seu shell):

  • C4_DIRECTOR_TIMEOUT_S (timeout por solicitação ao Director)
  • C4_GET_ALL_ITEMS_TIMEOUT_S (timeout geral de busca de inventário)

Opcional: proteções de gravação (recomendado para segurança)

Por padrão, ferramentas que alteram o estado (fechaduras, luzes, termostato, controle remoto de mídia, etc.) são bloqueadas a menos que você habilite explicitamente as gravações. Se você quiser uma camada extra de segurança (recomendado), defina:

  • C4_WRITE_GUARDRAILS=true (ativa a aplicação das regras)
  • C4_WRITES_ENABLED=false (mantém as ferramentas de gravação bloqueadas; alterne para true quando quiser realmente gravações)

Filtros opcionais (nomes de ferramentas separados por vírgula):

  • C4_WRITE_ALLOWLIST=c4_light_set_level,c4_light_ramp (permitir apenas estas ferramentas de gravação)
  • C4_WRITE_DENYLIST=c4_lock_unlock,c4_lock_lock (bloquear estas ferramentas de gravação)

Ajustes de desempenho

Algumas ferramentas dependem de varreduras de inventário (get_all_items) para resolução por nome e listagem. Você pode acelerá-las com um pequeno cache em processo:

  • C4_ITEMS_CACHE_TTL_S=5 (padrão) armazena o inventário em cache por 5 segundos
  • C4_ITEMS_CACHE_TTL_S=0 desativa o cache

Descobrir IDs

Os IDs de dispositivos e salas são específicos do seu projeto Control4. Use:

  • c4_list_rooms
  • c4_find_rooms / c4_resolve_room (buscar por nome)
  • c4_list_devices (por categoria)
  • Categoria c4_list_devices: shades (descoberta de melhor esforço)
  • Categoria c4_list_devices: scenes (melhor esforço; baseado em botões de UI)
  • c4_find_devices / c4_resolve_device (buscar por nome; filtros opcionais de categoria/sala)
  • c4_resolve (resolve sala + dispositivo juntos; a resolução do dispositivo pode ser limitada à sala resolvida)

Persianas / cortinas (melhor esforço)

Se o seu projeto tiver persianas/cortinas, tente:

  • c4_shade_list
  • c4_shade_get_state (retorna position 0-100 quando disponível)
  • c4_shade_open / c4_shade_close / c4_shade_stop
  • c4_shade_set_position

Solução de problemas:

  • Use c4_item_commands(device_id) para ver os nomes exatos dos comandos que seu driver de persiana expõe.
  • Use c4_item_variables(device_id) para inspecionar qual variável contém posição/nível.

Em seguida, passe os IDs descobertos para ferramentas como c4_media_watch_launch_app ou os scripts em tools/.

Se você preferir chamadas baseadas em nome (sem IDs), use c4_media_watch_launch_app_by_name.

Cenas de iluminação (melhor esforço)

As "cenas" do Control4 variam por projeto. Em muitos projetos, elas aparecem como dispositivos de botão de UI.

Tente:

  • 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 melhor esforço + ativação)

Solução de problemas:

  • Use c4_item_commands(device_id) para ver qual(is) comando(s) uma determinada cena/botão suporta.
  • Validador somente leitura: .\.venv\Scripts\python.exe tools\validate_scenes.py --show-commands