Thermostat

Tous les modèles de thermostat Google Nest sont compatibles avec l'API Smart Device Management (SDM). Ces appareils renvoient le type d'appareil THERMOSTAT :

sdm.devices.types.THERMOSTAT

Caractéristiques

Référence

Les traits, commandes ou événements suivants sont associés à ce groupe :

TraitDescriptionCommandes
ConnectivitéCette caractéristique appartient à tout appareil disposant d'informations de connectivité.
VentilateurCette caractéristique appartient à tous les appareils dont le système peut contrôler le ventilateur.SetTimer
HumiditéCette caractéristique appartient à tout appareil équipé d'un capteur pour mesurer l'humidité.
InfosCette caractéristique appartient à n'importe quel appareil pour les informations le concernant.
ParamètresCette caractéristique appartient à n'importe quel appareil pour les informations sur les paramètres associés.
TempératureCette caractéristique appartient à tout appareil équipé d'un capteur pour mesurer la température.
ThermostatEcoCette caractéristique appartient aux types d'appareils THERMOSTAT compatibles avec les modes ÉCO.SetMode
ThermostatHvacCette caractéristique appartient aux types d'appareils THERMOSTAT qui peuvent fournir des informations sur le CVC.
ThermostatModeCette caractéristique appartient aux types d'appareils de thermostat thermostat qui sont compatibles avec différents modes de thermostat.SetMode
ThermostatTemperatureSetpointCette caractéristique appartient aux types d'appareils THERMOSTAT qui permettent de définir la température cible et la plage de température.SetHeat
SetCool
SetRange

JSON

L'absence d'un trait dans une réponse GET indique que le trait ou la fonctionnalité n'est pas actuellement disponible pour l'appareil. Pour en savoir plus, consultez la section Types d'appareils.

{
  "type" : "sdm.devices.types.THERMOSTAT",
  "traits" : {
    "sdm.devices.traits.Connectivity" : {
      "status" : "ONLINE"
    },
    "sdm.devices.traits.Fan" : {
      "timerMode" : "ON",
      "timerTimeout" : "2019-05-10T03:22:54Z"
    },
    "sdm.devices.traits.Humidity" : {
      "ambientHumidityPercent" : 35.0
    },
    "sdm.devices.traits.Info" : {
      "customName" : "My device"
    },
    "sdm.devices.traits.Settings" : {
      "temperatureScale" : "CELSIUS"
    },
    "sdm.devices.traits.Temperature" : {
      "ambientTemperatureCelsius" : 23.0
    },
    "sdm.devices.traits.ThermostatEco" : {
      "availableModes" : ["MANUAL_ECO", "OFF"],
      "mode" : "MANUAL_ECO",
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    },
    "sdm.devices.traits.ThermostatHvac" : {
      "status" : "HEATING"
    },
    "sdm.devices.traits.ThermostatMode" : {
      "availableModes" : ["HEAT", "COOL", "HEATCOOL", "OFF"],
      "mode" : "COOL"
    },
    "sdm.devices.traits.ThermostatTemperatureSetpoint" : {
      "heatCelsius" : 20.0,
      "coolCelsius" : 22.0
    }
  }
}

Température et humidité

Pour lire la température ambiante du thermostat, utilisez la caractéristiqueTempérature . La température ambiante est mesurée sur l'appareil.

Pour lire l'humidité ambiante du thermostat, utilisez la propriétéHumidité . L'humidité ambiante est mesurée sur l'appareil.

Échelle de température

Le Google Nest Thermostat peut afficher la température en degrés Celsius ou Fahrenheit, mais l'échelle ne peut pas être définie par l'API SDM. Pour déterminer l'échelle de température actuellement définie par l'utilisateur, utilisez la caractéristiqueSettings .

Changer de mode

Le mode du thermostat dépend de deux caractéristiques différentes : ThermostatMode et ThermostatEco.

Modes standards

Pour définir le mode du thermostat sur HEAT, COOL ou HEATCOOL, utilisez la commande SetMode de la caractéristique ThermostatMode.

Cette commande permet également de désactiver le mode du thermostat, mais pas d'activer le mode Éco.

Par exemple, pour modifier l'un des modes standards du thermostat :

Requête

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatMode.SetMode",
  "params" : {
    "mode" : "HEAT"
  }
}

Réponse

{}

Mode Éco

Pour activer le mode Éco, utilisez MANUAL_ECO comme mode avec la commande SetMode de la caractéristique ThermostatEco :

Requête

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatEco.SetMode",
  "params" : {
    "mode" : "MANUAL_ECO"
  }
}

Réponse

{}

Cette commande a une incidence sur d'autres caractéristiques, en fonction de l'état actuel du mode Éco ou des changements apportés:

  • Si le mode Éco est désactivé, le mode du thermostat est défini par défaut sur le dernier mode standard (CHAUFFAGE, CLIMATISATION, CHAUFF./CLIMAT. ou ÉTEINT) qui était actif.
  • Si le mode Éco est MANUAL_ECO :

Modifier les températures mémorisées

Les températures mémorisées ne peuvent être modifiées que lorsque le thermostat est en mode CHAUFFAGE, CLIMATISATION ou CHAUFFAGE/CLIMATISATION, et que les températures mémorisées autorisées correspondent au mode actuel du thermostat. Les températures mémorisées ne peuvent pas être modifiées lorsque le mode est désactivé ou que le mode Éco est défini sur MANUAL_ECO.

Le thermostat doit être en mode correspondant à la commande appelée avant de modifier les points de consigne de température. La commande et le ou les champs permettant de modifier la ou les températures mémorisées varient selon le mode du thermostat.

Par exemple, pour que la commande SetHeat puisse être exécutée, le thermostat doit d'abord être en mode CHAUFFAGE:

Mode Commande Champ(s)
AUXILIAIRE SetHeat heatCelsius
COOL SetCool coolCelsius
HEATCOOL SetRange heatCelsius, coolCelsius

Notez que les commandes de température mémorisée n'acceptent que des degrés Celsius comme paramètre, même si le Google Nest Thermostat peut afficher la température en degrés Celsius ou Fahrenheit.

Par exemple, pour modifier la température de consigne lorsque le thermostat est en mode CHAUFFAGE, utilisez la commande SetHeat de la caractéristique ThermostatTemperatureSetpoint :

Requête

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat",
  "params" : {
    "heatCelsius" : 22.0
  }
}

Réponse

{}

Points de consigne du mode Éco

Les points de consigne heatCelsius et coolCelsius renvoyés par la caractéristique ThermostatEco sont définis par l'utilisateur et ne peuvent pas être modifiés via l'API SDM.

Activer ou désactiver la ventilation

Si le thermostat est compatible avec un ventilateur, utilisez la commande SetTimer de la caractéristique Fan pour l'allumer ou l'éteindre. Lorsque vous l'allumez, vous pouvez spécifier la durée pendant laquelle vous souhaitez que le ventilateur fonctionne, en secondes.

Par exemple, pour faire fonctionner le ventilateur pendant une heure :

Requête

POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.Fan.SetTimer",
  "params" : {
    "timerMode" : "ON",
    "duration" : "3600s"
  }
}

Réponse

{}

Si le champ duration est omis, le ventilateur s'exécute pendant 15 minutes par défaut.

Vérifier la connectivité de l'appareil

Si l'appareil ne répond pas aux commandes ou n'envoie pas d'événements, ou si vous recevez des erreurs de l'API liées à l'appareil, utilisez le traitConnectivité pour vérifier si l'appareil est hors connexion. Vérifiez la connexion Internet de l'appareil et assurez-vous que le service Nest est opérationnel.

Si les événements sont activés, vous devriez également avoir reçu un événement de ressource indiquant que l'appareil s'est déconnecté:

Charge utile

{
  "eventId" : "366dcbfb-2b0d-4c8c-9ad9-2ff7434f1dc7",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.Connectivity" : {
        "status" : "OFFLINE"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Réagir aux événements de l'appareil

Toute modification apportée à un champ de caractéristique génère un événement. Par exemple, vous recevrez l'événement resourceUpdate suivant si l'état du système CVC du thermostat est défini sur CHAUFFAGE :

Charge utile

{
  "eventId" : "1e9d0340-7543-4a6f-b498-7c12a77f0b27",
  "timestamp" : "2019-01-01T00:00:01Z",
  "resourceUpdate" : {
    "name" : "enterprises/project-id/devices/device-id",
    "traits" : {
      "sdm.devices.traits.ThermostatHvac" : {
        "status" : "HEATING"
      }
    }
  },
  "userId": "AVPHwEuBfnPOnTqzVFT4IONX2Qqhu9EJ4ubO-bNnQ-yi",
  "resourceGroup" : [
    "enterprises/project-id/devices/device-id"
  ]
}

Les événements sont déclenchés pour toutes les caractéristiques associées à ce type d'appareil. Activez les événements si vous devez y réagir d'une manière ou d'une autre dans le cadre d'une intégration.

Calendrier des événements

Notez qu'il est possible qu'un événement lié à un changement d'état du système CVC ne soit pas diffusé en même temps que les événements liés à un changement de mode du thermostat.

Par exemple, il peut y avoir un délai de démarrage du mode chauffage ou de climatisation d'un thermostat pour protéger le système CVC. Dans ce scénario, le changement de mode du thermostat ne peut envoyer initialement que des événements pour les modifications des attributs ThermostatMode et ThermostatTemperatureSetpoint , la modification de l'attribut ThermostatHvac étant envoyée ultérieurement en tant qu'événement distinct une fois que le système s'allume. S'il n'y avait pas de retard dans l'activation du système CVC, les trois événements seraient envoyés en même temps.

Erreurs

Le ou les codes d'erreur suivants peuvent être renvoyés pour cet appareil :

Message d'erreur RPC Dépannage
La valeur de refroidissement doit être supérieure à la valeur de chauffage. INVALID_ARGUMENT Assurez-vous que le champ heatCelsius est inférieur au champ coolCelsius de votre commande.
Commande non autorisée en mode thermostat actuel. FAILED_PRECONDITION Certains modèles de thermostats ne permettent pas de modifier le mode Éco lorsque le mode du thermostat est ÉTEINT, selon le trait ThermostatMode . Vous devez définir le mode du thermostat sur CHAUFFAGE, CLIMATISATION ou CHAUFFAGE/CLIMATISATION avant de modifier le mode Éco.
Ventilateur du thermostat indisponible. FAILED_PRECONDITION Le thermostat ne dispose pas de ventilateur. Les traits et les commandes liés aux ventilateurs ne peuvent pas être utilisés pour cet appareil.
Commande non autorisée lorsque le thermostat est en mode MANUAL_ECO. FAILED_PRECONDITION Vous ne pouvez pas définir la température mémorisée lorsque le thermostat est en mode Éco manuel.

Consultez la documentation de référence sur les codes d'erreur de l'API pour obtenir la liste complète des codes d'erreur de l'API.