Thermostat

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

sdm.devices.types.THERMOSTAT

Caractéristiques

Reference

Les caractéristiques, 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 à tout appareil capable de contrôler le ventilateur.SetTimer
HumiditéCette caractéristique appartient à tout appareil doté d'un capteur pour mesurer l'humidité.
InfosCette caractéristique appartient à n'importe quel appareil pour les informations liées à l'appareil.
ParamètresCette caractéristique appartient à n'importe quel appareil pour les informations sur les paramètres liés à l'appareil.
TempératureCette caractéristique appartient à tout appareil doté d'un capteur pour mesurer la température.
ThermostatEcoCette caractéristique appartient aux types d'appareils de THERMOSTAT compatibles avec les modes ECO.SetMode
ThermostatHvacCette caractéristique appartient aux types d'appareils de THERMOSTAT qui peuvent fournir des informations sur le système CVC.
ThermostatModeCette caractéristique appartient aux types d'appareils de THERMOSTAT compatibles avec différents modes de thermostat.SetMode
ThermostatTemperatureSetpointCette caractéristique appartient aux types d'appareils de THERMOSTAT qui permettent de définir une température cible et une plage de températures.SetHeat
SetCool
SetRange

JSON

L'absence d'un trait dans une réponse GET indique que le trait ou la caractéristique en question n'est pas disponible actuellement pour l'appareil. Pour plus d'informations, 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 au niveau de l'appareil.

Pour lire l'humidité ambiante du thermostat, utilisez la caractéristiqueHumidité . L'humidité ambiante est mesurée au niveau de l'appareil.

Échelle de température

Le Google Nest Thermostat peut afficher la température en degrés Celsius ou en Fahrenheit, mais la balance 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 : ThermostatMode et ThermostatEco.

Modes standards

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

Elle permet aussi de désactiver le mode du thermostat, mais pas d'activer le mode Éco.

Par exemple, pour changer 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 le mode MANUAL_ECO 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 modifications apportées à celui-ci:

  • Si le mode Éco est désactivé, c'est le dernier mode standard (Chauffage, Climatisation, Climatisation ou Éteint) qui est activé par défaut.
  • 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 Climatisation, et que les températures mémorisées correspondent au mode actuel du thermostat. Vous ne pouvez pas modifier les températures mémorisées lorsque le mode est désactivé ou que le mode Éco est défini sur MANUAL_ECO.

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

Par exemple, pour que vous puissiez exécuter la commande "SetHeat", le thermostat doit d'abord être en mode Chauffage:

Mode Commande Champ(s)
AUXILIAIRE SetHeat heatCelsius
FROID SetCool coolCelsius
Climatisation SetRange heatCelsius, coolCelsius

Notez que les commandes de température mémorisée ne prennent en compte que les 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 mémorisée lorsque le thermostat est en mode Chauffage, utilisez la commande SetHeat de la caractéristique "ThermostatTempératureSetpoint" :

Requête

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

Réponse

{}

Températures mémorisées pour le mode Éco

Les températures mémorisées heatCelsius et coolCelsius renvoyées par la caractéristique ThermostatÉco sont définies par l'utilisateur et ne peuvent pas être modifiées via l'API SDM.

Allumer ou éteindre le ventilateur

Si le thermostat est compatible avec le ventilateur, activez ou désactivez-le à l'aide de la commande SetTimer de la caractéristique Ventilation. Lorsque vous l'allumez, vous pouvez spécifier la durée de fonctionnement du ventilateur, 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 fonctionnera 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ée à l'appareil, utilisez la caractéristiqueConnectivité pour vérifier la connectivité de l'appareil et l'état HORS CONNEXION. Vérifiez la connexion de l'appareil à Internet et assurez-vous que le service Nest est activé.

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

Charge utile

{
  "eventId" : "dc7d0209-628c-44be-8045-3831c6f07c77",
  "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 trait génère un événement. Par exemple, vous recevez l'événement resourceUpdate suivant si l'état du système CVC du thermostat passe à CHAUFFAGE:

Charge utile

{
  "eventId" : "8e379fbd-8b8a-4c0e-a800-ea71abf53af0",
  "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'un événement correspondant à un changement d'état du système CVC peut ne pas être diffusé en même temps qu'un événement lié à un changement de mode du thermostat.

Par exemple, un délai d'activation du mode chauffage ou climatisation d'un thermostat est parfois nécessaire afin de protéger le système CVC. Dans ce cas, il est possible que la modification du mode du thermostat n'envoie que des événements liés au ThermostatMode et à ThermostatTempératureSetpoint , la modification de la température ( Thermostat Hvac ), qui active la modification par la suite sous la forme d'un événement distinct. Si l'activation du système CVC n'est pas retardée, les trois événements sont envoyés en même temps.

Erreurs

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

Message d'erreur RPC Dépannage
La valeur de climatisation doit être supérieure à la valeur thermique. INVALID_ARGUMENT Assurez-vous que la valeur du champ heatCelsius est inférieure à celle du champ coolCelsius de votre commande.
Commande non autorisée en mode thermostat actuel. FAILED_PRECONDITION Certains modèles de thermostat ne permettent pas de modifier le mode Éco lorsque le mode du thermostat est désactivé, conformément à la caractéristique ThermostatMode . Vous devez définir le mode du thermostat sur Chauffage, Climatisation ou Climatisation avant de modifier le mode Éco.
Ventilateur du thermostat indisponible. FAILED_PRECONDITION Le thermostat n'est pas équipé d'un ventilateur. Les caractéristiques et les commandes liées aux fans ne peuvent pas être utilisées sur cet appareil.
Commande non autorisée lorsque le thermostat est en mode MANUAL_ECO. FAILED_PRECONDITION Impossible de régler 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.