Interfacciare SlimLine a un termostato Shelly

L'integrazione tra dispositivi di automazione domestica è fondamentale per migliorare il comfort, l'efficienza energetica e il controllo degli impianti.

L'integrazione tra un controllore programmabile come SlimLine e i termostati Shelly permette di monitorare e regolare la temperatura degli ambienti in tempo reale, oltre a implementare logiche di controllo avanzate.

Ad esempio, il PLC può decidere automaticamente quali zone riscaldare o raffrescare in base a orari programmati, presenza negli ambienti, temperatura esterna o scenari predefiniti.

SlimLine e LogicLab

Il sistema SlimLine di Elsist è un PLC (Programmable Logic Controller) compatto e versatile, progettato per l'automazione di impianti civili e industriali. Grazie alla sua modularità e alla possibilità di programmare logiche complesse, consente il controllo affidabile e personalizzabile di sistemi elettrici, termici e meccanici.

L'ambiente di sviluppo gratuito LogicLab permette di programmare il PLC nei cinque linguaggi, grafici e testuali, definiti dalla norma IEC 61131-3.

Termostato Shelly

Il termostato Shelly è un dispositivo smart progettato per il controllo automatico dei sistemi di riscaldamento e raffrescamento. Grazie alla connettività integrata e alla compatibilità con i protocolli di automazione supportati dal dispositivo, consente una gestione avanzata della temperatura ambiente.

Comunicazione tramite API HTTP e RPC

L'integrazione viene realizzata utilizzando chiamate HTTP REST API dallo SlimLine, tramite il blocco funzione HTTPClient, in accordo con il protocollo RPC di Shelly.

Il formato JSON rende la comunicazione flessibile e scalabile. È possibile aggiungere nuovi dispositivi alla rete senza modificare sostanzialmente la logica di controllo.

I blocchi funzione JSONEncoder e JSONDecoder consentono di interpretare i dati ricevuti, elaborare i comandi e inviare istruzioni ai dispositivi Shelly.

In questo articolo vedremo come realizzare una semplice applicazione pratica.

1. Configurazione del termostato

La prima operazione consiste nel configurare il termostato Shelly.

Sui dispositivi Gen2/Gen3 descritti in questo esempio, la connessione alla rete Wi-Fi può essere configurata dal display:

1. Accedere al menu delle impostazioni.
2. Abilitare il Wi-Fi.
3. Selezionare la rete desiderata.
4. Inserire la password di accesso.

Una volta connesso alla rete, il dispositivo mostrerà l'indirizzo IP assegnato. Da un browser è quindi possibile accedere alla relativa interfaccia di configurazione.

Verifica della comunicazione RPC

Per verificare lo stato del dispositivo, inserire nel browser il seguente indirizzo, sostituendo IP_SHELLY con l'indirizzo IP effettivo:

http://IP_SHELLY/status

Il dispositivo restituisce un messaggio JSON con le informazioni di stato.

Le richieste RPC vengono invece inviate all'indirizzo:

http://IP_SHELLY/rpc

Esempi di messaggi RPC

Gli esempi seguenti illustrano alcune operazioni disponibili. I metodi e i parametri effettivamente supportati dipendono dal modello e dalla versione del firmware.

Funzione	Richiesta JSON	Risposta indicativa
Lettura temperatura	{"id":1,"method":"Temperature.GetStatus","params":{"id":0}}	{"id":0,"tC":26.2,"tF":79.2}
Lettura umidità	{"id":1,"method":"Humidity.GetStatus","params":{"id":0}}	{"id":0,"rh":43.6}
Lettura illuminazione	{"id":1,"method":"Illuminance.GetStatus","params":{"id":0}}	{"id":0,"lux":200,"illumination":"bright"}
Impostazione setpoint a 22 °C	{"id":1,"method":"Thermostat.SetConfig","params":{"id":0,"config":{"target_C":22.0,"enable":true}}}	{"restart_required":false}
Lettura stato termostato	{"id":1,"method":"Thermostat.GetStatus","params":{"id":0}}	{"id":0,"enable":true,"target_C":14.5,"current_C":22.9,"output":false,"schedules":{"enable":false}}

Nota: i metodi Temperature.GetStatus, Humidity.GetStatus, Illuminance.GetStatus e Thermostat.GetStatus non sono necessariamente disponibili su tutti i modelli Shelly. Verificare la documentazione RPC del dispositivo utilizzato prima di eseguire le richieste.

2. Programma SlimLine

Realizziamo ora un semplice programma su SlimLine per acquisire la temperatura dal termostato Shelly. Il programma può essere esteso per leggere altre variabili o modificare il setpoint.

Ambiente di sviluppo: LogicLab

Progetto: Ptp181

Programma: ShellyWallDisplay

Codice Structured Text (ST)

PROGRAM ShellyWallDisplay

VAR CONSTANT
    BSize : UDINT := 128;    (* Buffer size definition *)
END_VAR

VAR
    CaseNr : USINT;          (* Program case *)
    Errors : UDINT;          (* Execution errors *)
    TimeBf : UDINT;          (* Time buffer (mS) *)
    Temperature : REAL;      (* Temperature °C *)
    PStart : PVOID;          (* Result start position *)
    PEnd : PVOID;            (* Result end position *)
    Answer : STRING[128];    (* Page string *)
    TCPClient : SysTCPClient; (* TCP client management *)
    HTTPRq : HTTPClient_v5;  (* HTTP client *)
END_VAR

// -------------------------------------------------------------------------
// PROGRAM "ShellyWallDisplay"
// The program reads the current temperature from a Shelly Wall Display.
// -------------------------------------------------------------------------

// INITIALIZATIONS

IF (SysFirstLoop) THEN

    // Set TCPClient parameters.

    TCPClient.PeerAdd := ADR('192.168.1.109'); // Peer address
    TCPClient.PeerPort := 80;                  // Peer port
    TCPClient.LocalAdd := ADR('0.0.0.0');      // Local address
    TCPClient.LocalPort := 0;                  // Local port
    TCPClient.FlushTm := 50;                   // Flush time (mS)
    TCPClient.LifeTm := 20;                    // Life time (S)
    TCPClient.RxSize := 512;                   // Rx buffer size
    TCPClient.TxSize := 512;                   // Tx buffer size

    // Set HTTPClient parameters.

    HTTPRq.SpyOn := TRUE;                      // Activate the spy
    HTTPRq.KeepAlive := FALSE;                 // HTTP keep-alive
    HTTPRq.RMethod := HTTP_REQUEST#HTTP_POST;  // HTTP request method
    HTTPRq.HostName := TCPClient.PeerAdd;      // Hostname
    HTTPRq.Page := ADR('rpc');                 // Web page
    HTTPRq.Request := eNULL;                   // Request string
    HTTPRq.Header := ADR('Content-Type: application/json$r$nAccept: application/json$r$n');
    HTTPRq.DBSize := 512;                      // Data buffer size
    HTTPRq.Timeout := T#10s;                   // Execution timeout

    // Set local variables.

    TimeBf := SysTimeGetMs();                  // Time buffer (mS)
END_IF;

// MANAGE CONNECTION

TCPClient(Connect := HTTPRq.Connect);
HTTPRq(Enable := TRUE, File := TCPClient.File);

IF (HTTPRq.Fault) THEN
    CaseNr := 0;
END_IF;

// PROGRAM SEQUENCES

CASE (CaseNr) OF

    // Initialize timer for acquisition delay.

    0:
        HTTPRq.Send := FALSE;
        TimeBf := SysTimeGetMs();

        IF (HTTPRq.Request <> eNULL) THEN
            eTO_JUNK(SysRMFree(ADR(HTTPRq.Request)));
        END_IF;

        CaseNr := CaseNr + 1;

    // Wait for delay, then allocate buffers and enable client.

    1:
        IF ((SysTimeGetMs() - TimeBf) < TO_UDINT(T#10s)) THEN
            RETURN;
        END_IF;

        IF NOT(SysRMAlloc(BSize, ADR(HTTPRq.Request))) THEN
            RETURN;
        END_IF;

        CaseNr := CaseNr + 1;

    // Create an RPC request to read the temperature and send it.
    // {"id":1,"method":"Temperature.GetStatus","params":{"id":0}}

    2:
        eTO_JUNK(SysVsnprintf(
            HTTPRq.Request,
            BSize,
            ADR('%s'),
            STRING_TYPE,
            ADR('{"id":1,"method":"Temperature.GetStatus","params":{"id":0}}')
        ));

        HTTPRq.Send := TRUE;
        CaseNr := CaseNr + 1;

    // Wait for the response.

    3:
        IF ((HTTPRq.DBChars <> 0) AND HTTPRq.HPSelector) THEN
            IF ((Sysstrlen(ADR(Answer)) + HTTPRq.DBChars) < SIZEOF(Answer)) THEN
                eTO_JUNK(Sysmemmove(
                    eTO_POINTER(ADR(Answer)) + Sysstrlen(ADR(Answer)),
                    HTTPRq.DBAddress,
                    HTTPRq.DBChars
                ));
            END_IF;
        END_IF;

        // When complete, read the temperature.

        IF (HTTPRq.Done) THEN
            CaseNr := 0;

            IF NOT(HTTPRq.PLoad) THEN
                Errors := Errors + 1;
                RETURN;
            END_IF;

            // Find the "result" JSON from the response.

            PStart := SysStrFind(
                ADR(Answer),
                ADR('"result":'),
                FIND_GET_END
            );

            PEnd := SysStrFind(
                PStart,
                ADR('}'),
                FIND_DEFAULT
            );

            eTO_JUNK(Sysmemmove(
                ADR(Answer),
                PStart,
                TO_UDINT(PEnd - PStart)
            ));

            IF (JSONDecoder(
                ADR(Answer),
                ADR('tC'),
                REAL_TYPE,
                ADR(Temperature),
                1,
                0
            ) <> 0) THEN
                Errors := Errors + 1;
            END_IF;
        END_IF;

END_CASE;

// [End of file]

Parametri da personalizzare

Parametro	Descrizione
TCPClient.PeerAdd	Indirizzo IP del termostato Shelly. Nell'esempio è 192.168.1.109.
TCPClient.PeerPort	Porta HTTP del dispositivo, normalmente 80.
HTTPRq.Page	Endpoint RPC, impostato su rpc.
HTTPRq.Timeout	Timeout della richiesta HTTP.
Temperature	Variabile REAL in cui viene memorizzata la temperatura letta.
Errors	Contatore degli errori rilevati dal programma.

3. Possibili estensioni

Il programma può essere esteso per:

• acquisire umidità e illuminazione;
• modificare il setpoint del termostato;
• leggere lo stato dell'uscita di riscaldamento;
• gestire più termostati;
• integrare la temperatura in logiche di regolazione e supervisione.

Attenzione: prima di utilizzare il codice in un impianto reale, verifica la gestione del buffer Answer, che deve essere azzerato prima di ogni nuova richiesta, e il parsing della risposta JSON. La risposta RPC può contenere campi aggiuntivi e il codice che cerca la prima parentesi graffa di chiusura potrebbe non estrarre correttamente tutto l'oggetto result. Verifica inoltre che il modello Shelly supporti i metodi RPC riportati e che il blocco HTTPClient_v5 sia compatibile con la versione della libreria installata.