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

Traits

Référence

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

TraitDescriptionCommandes
ConnectivitéCe trait appartient à tout appareil disposant d'informations de connectivité.
VentilateurCe trait appartient à tout appareil doté de la capacité système de contrôler le ventilateur.SetTimer
HumiditéCe trait appartient à tout appareil doté d'un capteur permettant de mesurer l'humidité.
InfosCe trait appartient à tout appareil pour les informations le concernant.
ParamètresCe trait appartient à tout appareil pour les informations sur les paramètres liés à l'appareil.
TempératureCe trait appartient à tout appareil doté d'un capteur permettant de mesurer la température.
ThermostatEcoCe trait appartient aux types d'appareils THERMOSTAT qui sont compatibles avec les modes ECO.SetMode
ThermostatHvacCe trait appartient aux types d'appareils THERMOSTAT qui peuvent signaler des informations sur le système CVC.
ThermostatModeCe trait appartient aux types d'appareils THERMOSTAT qui prennent en charge différents modes de thermostat.SetMode
ThermostatTemperatureSetpointCe trait appartient aux types d'appareils 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 fonctionnalité ne sont actuellement pas disponibles pour l'appareil. Pour en savoir plus, consultez 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 le traitTempérature . La température ambiante est mesurée au niveau de l'appareil.

Pour lire l'humidité ambiante du thermostat, utilisez le traitHumidity . 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 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 le traitSettings .

Changer de mode

Le mode du thermostat est géré par deux traits différents : ThermostatMode et ThermostatEco.

Modes standards

Pour définir le mode du thermostat sur CHAUFFAGE, CLIMATISATION ou CHAUFFCLIM, utilisez la commande SetMode du trait ThermostatMode.

Cette commande peut également être utilisée pour désactiver le 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ê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 du trait 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 un impact sur d'autres caractéristiques, en fonction de l'état actuel du mode Éco ou des modifications apportées à ce mode :

  • 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. • CLIM. ou DÉSACTIVÉ) qui était actif.
  • Si le mode Éco est défini sur MANUAL_ECO :

Modifier les températures de consigne

Les températures de consigne ne peuvent être modifiées que lorsque le thermostat est en mode CHAUFFAGE, CLIMATISATION ou CHAUFF. • CLIM. Les températures de consigne autorisées correspondent au mode actuel du thermostat. Les consignes de température ne peuvent pas être modifiées lorsque le mode est défini sur "OFF" ou lorsque 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 consignes de température. La commande et le ou les champs permettant de modifier la ou les températures de consigne varient en fonction du 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
FRAIS SetCool coolCelsius
HEATCOOL SetRange heatCelsius, coolCelsius

Notez que les commandes de température de consigne n'acceptent que les degrés Celsius comme paramètre, bien que le Google Nest Thermostat puisse 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 du trait ThermostatTemperatureSetpoint :

Requête

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

Réponse

{}

Consignes du mode Éco

Les consignes heatCelsius et coolCelsius renvoyées par le trait ThermostatEco 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 un ventilateur, utilisez la commande SetTimer du trait "Ventilateur" pour l'allumer ou l'éteindre. 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ées à l'appareil, utilisez le traitConnectivity pour vérifier la connectivité de l'appareil et voir s'il 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" : "31a9759c-21a6-47d7-acbc-8e854f1000a7",
  "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 recevrez l'événement resourceUpdate suivant si l'état du système CVC du thermostat est passé à HEATING (CHAUFFAGE) :

Charge utile

{
  "eventId" : "20388ec2-1a03-4eba-b2fc-aa30616108be",
  "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.

Timing des événements

Notez qu'un événement de changement d'état du système CVC peut ne pas être transmis en même temps que les événements de changement de mode du thermostat.

Par exemple, il peut parfois y avoir un délai avant que le mode chauffage ou climatisation d'un thermostat ne démarre afin de protéger le système CVC. Dans ce scénario, la modification du mode du thermostat peut n'envoyer initialement que des événements pour les modifications des traits ThermostatMode et ThermostatTemperatureSetpoint . La modification du trait ThermostatHvac est envoyée ultérieurement sous forme d'événement distinct une fois que le système est réellement activé. S'il n'y avait pas de délai pour allumer le 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 en lien avec 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.
La commande n'est pas autorisée dans le mode thermostat actuel. FAILED_PRECONDITION Certains modèles de thermostats ne permettent pas de modifier le mode Éco lorsque le mode du thermostat est DÉSACTIVÉ, conformément au trait ThermostatMode . Le mode du thermostat doit être défini sur CHAUFFAGE, CLIMATISATION ou CHAUFFCLIM avant de pouvoir modifier le mode Éco.
Le ventilateur du thermostat n'est pas disponible. FAILED_PRECONDITION Le thermostat n'est pas compatible avec un ventilateur. Les traits et commandes liés au ventilateur 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.