Bộ điều nhiệt

Tất cả các kiểu máy Google Nest Thermostat đều được hỗ trợ trong API Quản lý thiết bị thông minh (SDM). Các thiết bị này trả về loại thiết bị THERHARAT:

sdm.devices.types.THERMOSTAT

Đặc điểm

Tài liệu tham khảo

Các đặc điểm, lệnh hoặc sự kiện sau đây có liên quan đến nhóm này:

Đặc điểmNội dung mô tảLệnh
Khả năng kết nốiTrait này thuộc về bất kỳ thiết bị nào có thông tin về khả năng kết nối.
Người hâm mộĐặc điểm này thuộc về bất kỳ thiết bị nào có tính năng hệ thống điều khiển quạt.SetTimer
Độ ẩmĐặc điểm này thuộc về bất kỳ thiết bị nào có cảm biến đo độ ẩm.
Thông tinĐặc điểm này thuộc về mọi thiết bị có thông tin liên quan đến thiết bị.
Cài đặtTrait này thuộc về mọi thiết bị có thông tin về chế độ cài đặt liên quan đến thiết bị.
Nhiệt độĐặc điểm này thuộc về bất kỳ thiết bị nào có cảm biến đo nhiệt độ.
ThermostatEcoĐặc điểm này thuộc các loại thiết bị của MÁY ĐIỀU NHIỆT có hỗ trợ các chế độ Tiết kiệm năng lượng.SetMode
ThermostatHvacĐặc điểm này thuộc các loại thiết bị của MÁY ĐIỀU NHIỆT có khả năng báo cáo thông tin chi tiết về hệ thống sưởi, thông gió và điều hoà.
ThermostatModeTrait này thuộc các loại thiết bị của MÁY ĐIỀU NHIỆT hỗ trợ nhiều chế độ của máy điều nhiệt.SetMode
ThermostatTemperatureSetpointĐặc điểm này thuộc các loại thiết bị của MÁY ĐIỀU NHIỆT có hỗ trợ đặt nhiệt độ mục tiêu và phạm vi nhiệt độ mục tiêu.SetHeat
SetCool
SetRange

JSON

Việc không có trait trong phản hồi GET cho biết rằng trait hoặc tính năng đó hiện không dùng được cho thiết bị. Hãy xem phần Loại thiết bị để biết thêm thông tin.

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

Nhiệt độ và độ ẩm

Để đọc nhiệt độ môi trường xung quanh của máy điều nhiệt, hãy sử dụng chỉ sốNhiệt độ . Nhiệt độ môi trường xung quanh được đo tại thiết bị.

Để đọc độ ẩm môi trường xung quanh của máy điều nhiệt, hãy sử dụng chỉ sốĐộ ẩm . Độ ẩm của môi trường xung quanh được đo tại thiết bị.

Thang nhiệt độ

Google Nest Thermostat có thể hiển thị nhiệt độ ở độ C hoặc độ F, nhưng API SDM không thể đặt thang đo. Để xác định thang nhiệt độ mà người dùng đang đặt, hãy sử dụng thuộc tínhCài đặt .

Thay đổi chế độ

Chế độ của máy điều nhiệt được quản lý qua hai đặc điểm: ThermostatMode và ThermostatEco.

Chế độ tiêu chuẩn

Để thay đổi chế độ của máy điều nhiệt thành HEAT, COOL hoặc HEATCOOL, hãy sử dụng lệnh SetMode của trait ThermostatMode.

Bạn cũng có thể dùng lệnh này để TẮT chế độ của máy điều nhiệt thành TẮT. Bạn không thể dùng lệnh này để bật Chế độ Tiết kiệm năng lượng.

Ví dụ: Cách thay đổi một trong các chế độ tiêu chuẩn của máy điều nhiệt:

Yêu cầu

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

Phản hồi

{}

Chế độ Tiết kiệm năng lượng

Để bật chế độ Tiết kiệm năng lượng, hãy sử dụng MANUAL_ECO làm chế độ có lệnh SetMode của đặc điểm ThermostatEco:

Yêu cầu

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

Phản hồi

{}

Lệnh này tác động đến các đặc điểm khác, dựa trên trạng thái hiện tại của chế độ Tiết kiệm năng lượng:

  • Nếu chế độ Tiết kiệm năng lượng đang TẮT, thì theo mặc định, chế độ dành cho máy điều nhiệt sẽ chuyển sang chế độ tiêu chuẩn gần đây nhất (SƯỞI ẤM, MỞ RỘNG, SƯỞI ẤM hoặc TẮT) đang hoạt động.
  • Nếu chế độ Tiết kiệm năng lượng là MANUAL_ECO:

Thay đổi điểm đặt nhiệt độ

Bạn chỉ có thể thay đổi điểm đặt nhiệt độ khi máy điều nhiệt đang ở chế độ SƯỞI ẤM, Làm mát hoặc SƯỞI ẤM và các điểm đặt nhiệt độ được phép tương ứng với chế độ hiện tại của máy điều nhiệt. Bạn không thể thay đổi điểm đặt nhiệt độ khi chế độ này đang TẮT hoặc khi Chế độ tiết kiệm được đặt thành MANUAL_ECO.

Máy điều nhiệt phải ở chế độ tương ứng với lệnh đang được gọi trước khi thay đổi điểm đặt nhiệt độ. Lệnh và(các) trường để thay đổi(các) điểm đặt sẽ khác nhau tuỳ theo chế độ của máy điều nhiệt.

Ví dụ: để ra lệnh SetHeat, trước tiên máy điều nhiệt phải ở chế độ SƯỞI ẤM:

Chế độ Lệnh (Các) trường
BỔ SUNG SetHeat heatCelsius
THOÁT SetCool coolCelsius
SƯỞI ẤM SetRange heatCelsius, coolCelsius

Xin lưu ý rằng các lệnh điểm đặt chỉ lấy độ C làm tham số, mặc dù Google Nest Thermostat có thể hiển thị nhiệt độ theo độ C hoặc độ F.

Ví dụ: để thay đổi điểm đặt nhiệt độ khi máy điều nhiệt đang ở chế độ SƯỞI ẤM, hãy sử dụng lệnh SetHeat của đặc điểm ThermostatNhiệt độSetpoint:

Yêu cầu

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

Phản hồi

{}

Điểm đặt cho chế độ tiết kiệm năng lượng

Các điểm đặt heatCelsius và coolCelsius do trait ThermostatEco trả về là do người dùng đặt và không thể thay đổi thông qua API SDM.

Bật hoặc tắt quạt

Nếu máy điều nhiệt hỗ trợ quạt, hãy sử dụng lệnh SetTimer của đặc điểm Quạt để bật hoặc tắt quạt. Khi bật, bạn có thể chỉ định khoảng thời gian mình muốn quạt chạy (tính bằng giây).

Ví dụ: để chạy quạt trong một giờ:

Yêu cầu

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

Phản hồi

{}

Nếu bạn bỏ qua trường duration, quạt sẽ chạy trong thời gian mặc định là 15 phút.

Kiểm tra khả năng kết nối của thiết bị

Nếu thiết bị không phản hồi lệnh hoặc gửi sự kiện, hoặc bạn gặp lỗi từ API liên quan đến thiết bị, hãy sử dụng tính năngKhả năng kết nối để kiểm tra khả năng kết nối của thiết bị xem có trạng thái NGOẠI LỆ (ngoại tuyến hay không). Kiểm tra kết nối Internet của thiết bị và đảm bảo rằng Dịch vụ Nest đã bật.

Nếu đã bật sự kiện, thì bạn cũng sẽ nhận được một sự kiện tài nguyên cho biết thiết bị đã chuyển sang chế độ ngoại tuyến:

Dung lượng

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

Phản ứng với các sự kiện trên thiết bị

Mọi thay đổi đối với trường trait sẽ tạo ra một sự kiện. Ví dụ: bạn sẽ nhận được sự kiện resourceUpdate sau đây nếu trạng thái HVAC của máy điều nhiệt thay đổi thành HEATING:

Dung lượng

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

Sự kiện được kích hoạt cho tất cả các trait liên quan đến loại thiết bị này. Bật sự kiện nếu bạn cần phản ứng với các sự kiện đó theo một cách nào đó trong quá trình tích hợp.

Thời gian diễn ra sự kiện

Xin lưu ý rằng sự kiện thay đổi trạng thái HVAC có thể không được gửi cùng lúc với sự kiện thay đổi chế độ máy điều nhiệt.

Ví dụ: đôi khi có sự chậm trễ trong việc khởi động chế độ sưởi ấm hoặc làm mát của máy điều nhiệt để bảo vệ hệ thống sưởi, thông gió và điều hoà. Trong trường hợp này, việc thay đổi chế độ máy điều nhiệt ban đầu chỉ có thể gửi các sự kiện cho ThermostatMode và ThermostattemperatureSetpoint thay đổi về trạng thái ban đầu, trong đó sự kiện ThermostatMode thực sự chuyển sang chế độ thay đổi riêng biệt. Nếu không có sự chậm trễ khi bật hệ thống sưởi, thông gió và điều hoà, thì cả ba sự kiện sẽ được gửi cùng một lúc.

Lỗi

Liên quan đến thiết bị này, có thể trả về(các) mã lỗi sau:

Thông báo lỗi RPC Khắc phục sự cố
Giá trị nhiệt độ làm mát phải lớn hơn giá trị nhiệt. INVALID_ARGUMENT Hãy đảm bảo trường heatCelsius nhỏ hơn trường coolCelsius trong lệnh.
Không cho phép lệnh ở chế độ máy điều nhiệt hiện tại. FAILED_PRECONDITION Một số mẫu máy điều nhiệt không hỗ trợ thay đổi Chế độ tiết kiệm năng lượng khi chế độ máy điều nhiệt đang TẮT, theo thuộc tính ThermostatMode . Bạn phải thay đổi chế độ của máy điều nhiệt thành SƯỞI ẤM, Làm mát hoặc SƯỞI ẤM trước khi chuyển sang chế độ Tiết kiệm năng lượng.
Không có quạt máy điều nhiệt. FAILED_PRECONDITION Máy điều nhiệt không có chế độ quạt. Không thể sử dụng các đặc điểm và lệnh liên quan đến quạt đối với thiết bị này.
Không được phép ra lệnh khi máy điều nhiệt ở chế độ MANUAL_ECO. FAILED_PRECONDITION Bạn không thể đặt điểm đặt nhiệt độ khi máy điều nhiệt đang ở chế độ Tiết kiệm năng lượng thủ công.

Hãy xem Tài liệu tham khảo về mã lỗi API để biết danh sách đầy đủ các mã lỗi API.