Placas de Relé — API
Visão Geral
Toda Placa de Relé MolSmart (de 2 a 32 canais) expõe a mesma superfície de controle aberta na rede local: um protocolo TCP em string bruta, uma interface HTTP GET (CGI), um socket UDP opcional e MQTT — assim qualquer hub, driver ou script consegue ligar/desligar relés e ler o estado deles sem precisar de conta na nuvem MolSmart.
| Transporte | Notas |
|---|---|
| TCP | Porta padrão 502 (alterável na página Integrations/Ports do módulo). Suporta tanto modo TCP client quanto TCP server. |
| HTTP | O módulo roda como seu próprio servidor HTTP; apenas requisições GET, sem corpo de requisição. |
| UDP | Sockets UDP1/UDP2 carregando o protocolo binário MolSmart — usados principalmente para comunicação módulo‑a‑módulo e polling por controladores. O formato do frame não está coberto pelo documento de API usado como fonte desta referência; ver nota 'a confirmar' em 1.6. |
| MQTT | Endereço do broker, tópicos e QoS são configurados por módulo na página Integrations/Ports da interface web — o módulo é um cliente MQTT, nunca um broker. |
Portas, credenciais/broker MQTT, HTTP Auth e CORS são todos configurados por unidade na própria página Integrations/Ports do módulo (interface web) — consulte o Manual do Usuário deste produto para a referência completa dos campos dessa página antes de montar uma integração.
Consulta de Status / KeepAlive
Abra uma conexão TCP simples com o módulo (porta padrão 502) e envie o código de comando de 2 caracteres abaixo como texto puro — não é necessário terminador de linha.
| Código de comando | Significado |
|---|---|
| 00 | Consulta de status — retorna a string completa de estado de relés + entradas descrita abaixo. |
[relay1][relay2]...[relayN] : [input1][input2]...[inputN] : [channel count] : last_updates_done_in_last_command_sent : [relay1][relay2]...[relayN] : [input1][input2]...[inputN]
A resposta repete o bloco de relés/entradas duas vezes, separado pelo campo last_updates_done_in_last_command_sent — reproduzido aqui exatamente como aparece no documento do fabricante; o significado do segundo bloco duplicado não foi reverificado de forma independente em uma unidade real.
0000:1111:4:0000:0000
00000000:11111111:8:00000000:00000000
0000000000000000:1111111111111111:16:0000000000000000:0000000000000000
00000000000000000000000000000000:11111111111111111111111111111111:32:00000000000000000000000000000000:00000000000000000000000000000000
Comando de Controle
Um comando de controle é formado concatenando até quatro campos: X + R + C + P. Envie como texto puro na mesma conexão TCP — de novo, sem necessidade de retorno/quebra de linha.
| Campo | Valores |
|---|---|
| X — ação | 1 = ON · 2 = OFF |
| R — relé | 1–32 = um relé específico · X = todos os relés |
| C — tipo de comando | omitido = ON/OFF simples · : = Delay · * = Jogging |
| P — parâmetro | valor exigido pelo tipo C escolhido (ver os exemplos do HTTP CGI em 1.4 para tempos concretos de delay/jogging) |
O documento do fabricante só mostra exemplos práticos de ON/OFF simples via TCP bruto. Os tipos de comando : (Delay) e * (Jogging) estão listados na tabela acima mas a sintaxe exata da string TCP não é detalhada — o mesmo comportamento de Delay/Jogging é documentado com parâmetros concretos via o endpoint HTTP CGI abaixo (1.4, type=1/type=2).
Ler Status dos Relés
A placa roda como servidor HTTP e aceita requisições HTTP GET simples — os exemplos do fabricante abaixo não mostram parâmetros de autenticação, mas veja a nota sobre HTTP Auth em 1.6. O sufixo do arquivo CGI é intercambiável — .cgi, .php e .cs funcionam igualmente.
/relay_cgi_load.cgi| Campo | Valor | Significado |
|---|---|---|
| result | 0 | 0 = ok, qualquer outro valor = falha |
| relay count | 2 / 4 / 8 / 16 / 24 / 32 | número de canais desta placa |
| relay 1…32 status | 0 / 1 | 0 = desligado, 1 = ligado (só retorna a quantidade de campos igual a relay count) |
http://192.168.1.100/relay_cgi_load.cgi
&0&4&1&0&1&0&
Comandar Relé
/relay_cgi.cgi| Parâmetro | Valores | Significado |
|---|---|---|
| type | 0 / 1 / 2 | 0 = on/off · 1 = jogging · 2 = delay |
| relay | 0–31 | 0 = relé 1, 1 = relé 2, … 31 = relé 32 |
| on | 0 / 1 | 0 = desligar, 1 = ligar |
| time | 0 · 1–255 · 1–65535 | significado depende do type — ver abaixo |
| pwd | 0–9999 | senha configurada no dispositivo (Relay Password em Integrations/Ports); 0 desativa a checagem |
| Type | Significado do campo time |
|---|---|
| type=0 (on/off) | time é ignorado (enviar 0) |
| type=1 (jogging) | time em unidades de 100 ms, faixa 1–255 (ex.: 5 = 500 ms) |
| type=2 (delay) | time em segundos inteiros, faixa 1–65535 |
A resposta espelha os campos da requisição: result, type, relay, on, time.
http://192.168.1.100/relay_cgi.cgi?type=0&relay=0&on=1&time=0&pwd=0&
&0&0&0&1&0&
http://192.168.1.100/relay_cgi.cgi?type=0&relay=0&on=0&time=0&pwd=0&
&0&0&0&0&0&
http://192.168.1.100/relay_cgi.cgi?type=1&relay=1&on=1&time=5&pwd=4660&
&0&1&1&1&5&
http://192.168.1.100/relay_cgi.cgi?type=1&relay=1&on=0&time=5&pwd=4660&
&0&1&1&0&5&
http://192.168.1.100/relay_cgi.cgi?type=2&relay=1&on=1&time=10&pwd=4660&
&0&2&1&1&10&
http://192.168.1.100/relay_cgi.cgi?type=2&relay=1&on=0&time=10&pwd=4660&
&0&2&1&0&10&
Ler Status das Entradas
/input.cgi| Campo | Valor | Significado |
|---|---|---|
| result | 0 | 0 = ok, qualquer outro valor = falha |
| input start position | 0 | padrão 0 |
| input count | 2 / 4 / 8 / 16 / 24 / 32 | número de entradas digitais desta placa |
| input 1…32 status | 0 / 1 | 0 = low, 1 = high |
http://192.168.1.100/input.cgi
&0&0&4&1&0&1&0&
Tópicos & Payloads
O documento de API do fabricante usado para a família de Placas de Relé não lista nomes de tópicos MQTT explícitos, diferente dos documentos do Dimmer TRIAC e Dimmer 0‑10V (que listam — ver essas páginas). As Placas de Relé compartilham o mesmo bloco de configuração MQTT (endereço do broker, QoS, Retain, HA Discover etc. — Integrations/Ports > MQTT) e é bem provável que sigam o mesmo padrão de tópico /molsmart/<device><serial>/in/… usado pela família Dimmer, mas isso não foi confirmado de forma independente para as Placas de Relé. Confirme os nomes exatos de tópico em uma unidade real (ex.: com o MQTT Explorer) antes de montar uma integração sobre esse canal.
Notas & Pendências
| Pendência | Detalhe |
|---|---|
| Formato de frame UDP1/UDP2 | Referenciado genericamente como 'o protocolo binário MolSmart' em Integrations/Ports; o layout exato de bytes não está coberto pelo documento-fonte usado nesta referência. |
| HTTP Auth / Session ID | A interface web expõe uma chave HTTP Auth e um token 'Session ID' mágico para acesso via script (ver Manual do Usuário do produto, página Config) — se/como isso restringe os endpoints CGI acima (além do parâmetro pwd em relay_cgi.cgi) não foi confirmado na fonte revisada. |
| Revisão da doc. de API | O documento do fabricante usado nesta página está identificado como V1.9.8 — firmwares mais recentes podem estender ou alterar esses endpoints. |
Para a referência completa dos campos das páginas da interface web de onde esses protocolos partem (Integrations/Ports, Config, MQTT etc.), consulte o Manual do Usuário deste produto.