Termostato

Todos os modelos do Google Nest Thermostat são compatíveis com a API Smart Device Management (SDM). Esses dispositivos retornam o tipo de dispositivo THERMOSTAT:

sdm.devices.types.THERMOSTAT

Características

Referência

As seguintes características, comandos ou eventos estão relacionados a este grupo:

Característica	Descrição	Comandos
Conectividade	Essa característica pertence a qualquer dispositivo que tenha informações de conectividade.
Fã	Essa característica pertence a qualquer dispositivo que tenha a capacidade do sistema de controlar o ventilador.	SetTimer
Umidade	Essa característica pertence a qualquer dispositivo que tenha um sensor para medir a umidade.
Informações	Essa característica pertence a qualquer dispositivo para informações relacionadas a ele.
Configurações	Essa característica pertence a qualquer dispositivo para informações de configuração relacionadas ao dispositivo.
Temperatura	Essa característica pertence a qualquer dispositivo que tenha um sensor para medir a temperatura.
ThermostatEco	Essa característica pertence aos tipos de dispositivos do TERMOSTATO compatíveis com os modos ECO.	SetMode
ThermostatHvac	Essa característica pertence a tipos de dispositivos de TERMOSTATO que podem informar detalhes de AVAC (aquecimento, ventilação e ar-condicionado).
ThermostatMode	Essa característica pertence a tipos de dispositivos do TERMOSTATO que oferecem suporte a diferentes modos de termostato.	SetMode
ThermostatTemperatureSetpoint	Essa característica pertence aos tipos de dispositivos do TERMOSTATO que oferecem suporte à definição de temperatura e faixa de temperatura desejadas.	SetHeat SetCool SetRange

JSON

A ausência de uma característica em uma resposta GET indica que a característica ou o recurso não está disponível no momento para o dispositivo. Consulte Tipos de dispositivos para mais informações.

{
  "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
    }
  }
}

Temperatura e umidade

Para ler a temperatura ambiente do termostato, use a característicaTemperatura . A temperatura ambiente é medida no dispositivo.

Para ler a umidade do ambiente do termostato, use a característica Umidade . A umidade do ambiente é medida no dispositivo.

Escala de temperatura

O Google Nest Thermostat pode exibir a temperatura em graus Celsius ou Faahrenheit, mas a escala não pode ser definida pela API SDM. Para determinar a escala de temperatura definida pelo usuário, use a característica Configurações .

Mudar o modo

O modo do termostato é gerenciado por duas características diferentes: ThermostatMode e ThermostatEco.

Modos padrão

Para mudar o modo do termostato para Aquecer, Resfriar ou Aquecer, use o comando SetMode da característica ThermostatMode.

Esse comando também pode ser usado para desativar o modo do termostato e não para ativar o modo Eco.

Por exemplo, para mudar um dos modos de termostato padrão:

Solicitação

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

Resposta

{}

Modo Eco

Para ativar o modo Eco, use MANUAL_ECO como modo com o comando SetMode da característica ThermostatEco:

Solicitação

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

Resposta

{}

Esse comando afeta outras características, com base no status atual ou nas alterações feitas no modo Eco:

• Se o modo Eco estiver DESATIVADO, o termostato vai usar por padrão o último modo padrão ativo (Aquecer, Resfriamento, Aquecer ou Desativado) que estava ativo.
• Se o modo Eco for MANUAL_ECO:
• Os comandos para a característica ThermostatTemperaturaSetpoint são rejeitados.
• As configurações de temperatura não são retornadas pela característica ThermostatTemperaturaSetpoint .

Alguns modelos de termostato não são compatíveis com a mudança do modo Eco quando ele está DESATIVADO, de acordo com a característica ThermostatMode . O modo do termostato precisa ser mudado para Aquecer, Resfriar ou HEATCOOL antes de alterar o modo Eco.

Mudar as temperaturas programadas

As temperaturas programadas só podem ser alteradas quando o termostato estiver nos modos Aquecer, Resfriar ou HEATCOOL, e as configurações permitidas correspondem ao modo atual do termostato. As configurações de temperatura não podem ser alteradas quando o modo está desativado ou quando o modo Eco está definido como MANUAL_ECO.

O termostato precisa estar no modo que corresponde ao comando que está sendo chamado antes da mudança das temperaturas programadas. O comando e os campos para mudar as temperaturas programadas variam de acordo com o modo do termostato.

Por exemplo, para emitir o comando SetHeat, o termostato precisa estar no modo Aquecer primeiro:

Modo	Comando	Campo(s)
Aquecimento	SetHeat	heatCelsius
FRIO	SetCool	coolCelsius
Aquecimento	SetRange	heatCelsius, coolCelsius

Observe que os comandos de temperatura programada usam apenas graus em Celsius como parâmetro, embora o Google Nest Thermostat possa exibir a temperatura em graus Celsius ou Fahrenheit.

Todos os comandos Set* serão rejeitados se o termostato estiver no modo Eco. Consulte a característica ThermostatEco para saber mais.

Por exemplo, para mudar a temperatura programada quando o termostato estiver no modo Aquecer, use o comando SetHeat da característica ThermostatTemperaturaSetpoint:

Solicitação

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

Resposta

{}

Configurações do modo Eco

Os parâmetros heatCelsius e coolCelsius retornados pela característica ThermostatEco são definidos pelo usuário e não podem ser alterados pela API SDM.

Ligar ou desligar o ventilador

Se o termostato for compatível com um ventilador, use o comando SetTimer da característica da ventilação para ligá-lo ou desativá-lo. Ao ligar, você pode especificar o tempo de funcionamento do ventilador em segundos.

Por exemplo, para ligar o ventilador por uma hora:

Solicitação

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

Resposta

{}

Se o campo duration for omitido, o ventilador funcionará por um tempo padrão de 15 minutos.

Se o comando para ligar o ventilador não produzir o resultado esperado, pode ser porque o ventilador já está ativado (manualmente pelo usuário, de acordo com uma programação ou devido a um ciclo de AVAC). Alguns comportamentos de ventiladores para o Google Nest Thermostat não podem ser substituídos pela API SDM.

Verificar a conectividade do dispositivo

Se o dispositivo não estiver respondendo a comandos ou enviando eventos, ou se você receber erros da API relacionados ao dispositivo, use o atributo Conectividade para conferir se o dispositivo tem um status OFF-LINE. Verifique a conexão do dispositivo com a Internet e confira se o Serviço Nest está ativo.

Se você tiver eventos ativados, também vai receber um evento de recurso indicando que o dispositivo ficou off-line:

Payload

{
  "eventId" : "b7705246-9224-46af-b5f2-b2af8437cd0e",
  "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"
  ]
}

Reagir a eventos do dispositivo

Qualquer alteração em um campo de característica gera um evento. Por exemplo, você receberia o seguinte evento resourceUpdate se o status AVAC (Aquecimento, ventilação e ar-condicionado) do termostato mudasse para Aquecimento:

Payload

{
  "eventId" : "849df9a2-9a28-452e-9b34-5490fc93d88b",
  "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"
  ]
}

Os eventos são acionados para todas as características associadas a este tipo de dispositivo. Ative os eventos se precisar reagir a eles de alguma forma como parte da integração.

Tempo dos eventos

Um evento para uma mudança no status do AVAC não é exibido ao mesmo tempo que os eventos de mudança do modo do termostato.

Por exemplo, às vezes há um atraso na inicialização do modo de aquecimento ou resfriamento de um termostato para proteger o sistema AVAC (aquecimento, ventilação e ar-condicionado). Nesse cenário, a mudança do modo do termostato só pode enviar eventos inicialmente para ThermostatMode e ThermostatTemperaturaSetpoint mudanças de característica, com o ThermostatHvac{20/ que é enviado depois. Se não houvesse atraso na ativação do sistema AVAC (aquecimento, ventilação e ar-condicionado), os três eventos serão enviados ao mesmo tempo.

Erros

Os seguintes códigos de erro podem ser retornados em relação a este dispositivo:

Mensagem de erro	RPC	Solução de problemas
O valor de resfriamento deve ser maior que o valor de aquecimento.	INVALID_ARGUMENT	Verifique se o campo heatCelsius é menor que o campo coolCelsius no comando.
O comando não é permitido no modo de termostato atual.	FAILED_PRECONDITION	Alguns modelos de termostato não são compatíveis com a mudança do modo Eco quando ele está DESATIVADO, de acordo com a característica ThermostatMode . O modo do termostato precisa ser alterado para Aquecer, Resfriar ou HEATCOOL antes de alterar o modo Eco.
Ventilador do termostato indisponível.	FAILED_PRECONDITION	O termostato não tem um recurso de ventilador. Características e comandos relacionados ao ventilador não podem ser usados neste dispositivo.
O comando não é permitido com o termostato no modo MANUAL_ECO.	FAILED_PRECONDITION	Não é possível definir a temperatura programada quando o termostato está no modo Eco manual.

Consulte a Referência de código de erro da API para ver a lista completa de códigos de erro.