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érenceJSON

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 à tous les appareils dotés d'un capteur pour mesurer l'humidité.
InfosCette caractéristique appartient à n'importe quel appareil pour les informations associées.
ParamètresCette caractéristique appartient à n'importe quel appareil pour les informations sur les paramètres associés.
TempératureCette caractéristique appartient à tous les appareils équipés d'un capteur de 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 THERMOSTAT 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

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éristiqueParamètres .

Changer de mode

Le mode du thermostat est géré par 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 peut également être utilisée pour désactiver le mode du thermostat. Elle ne peut pas être utilisée pour activer le mode Éco.

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

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

{}

Mode Éco

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

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

{}

Cette commande a une incidence sur d'autres caractéristiques, en fonction de l'état actuel du mode Éco ou des modifications apportées à celui-ci:

  • Si le mode Éco est désactivé, le mode du thermostat est défini par défaut sur le dernier mode standard (CHAUFFAGE, CLIMATISATION, CHAUFFCLIM ou DÉSACTIVÉ) 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 points de consigne de température ne peuvent pas être modifiés lorsque le mode est défini sur "OFF" ou lorsque 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 émettre la commande SetHeat, le thermostat doit d'abord être en mode CHAUFFAGE:

Mode Commande Champ(s)
AUXILIAIRE SetHeat heatCelsius
FROID 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êteRéponse
POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.ThermostatTemperatureSetpoint.SetHeat",
  "params" : {
    "heatCelsius" : 22.0
  }
}

{}

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êteRéponse
POST /enterprises/project-id/devices/device-id:executeCommand
{
  "command" : "sdm.devices.commands.Fan.SetTimer",
  "params" : {
    "timerMode" : "ON",
    "duration" : "3600s"
  }
}

{}

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

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 est hors connexion:

Charge utile
{
  "eventId" : "7bfa9f08-b07a-4839-bf2f-3c64b2b40660",
  "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" : "bb46ea3e-e674-4d45-a5da-1eb163bc2b3e",
  "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 tous les traits associés à 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'un événement de modification de l'état du système CVC peut ne pas être envoyé en même temps que les événements de modification du mode du thermostat.

Par exemple, il peut y avoir un délai de démarrage du mode chauffage ou 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 dans votre commande.
Commande non autorisée dans le mode actuel du thermostat. 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.