Trang này được dịch bởi Cloud Translation API.

Bộ điều nhiệt

Smart Device Management (SDM) API hỗ trợ tất cả các mẫu Google Nest Thermostat. Các thiết bị này trả về loại thiết bị THERMOSTAT:

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ểm	Mô tả	Lệnh
Khả năng kết nối	Đặc điểm này thuộc về mọi thiết bị có thông tin kết nối.
Fan	Đặc điểm này thuộc về mọi thiết bị có khả năng điều khiển quạt.	SetTimer
Độ ẩm	Đặc điểm này thuộc về mọi thiết bị có cảm biến đo độ ẩm.
Thông tin	Đặc điểm này thuộc về mọi thiết bị để cung cấp thông tin liên quan đến thiết bị.
Cài đặt	Đặc điểm này thuộc về mọi thiết bị để biết 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ề mọi thiết bị có cảm biến đo nhiệt độ.
ThermostatEco	Đặc điểm này thuộc về các loại thiết bị THERMOSTAT hỗ trợ chế độ TIẾT KIỆM NĂNG LƯỢNG.	SetMode
ThermostatHvac	Đặc điểm này thuộc về các loại thiết bị THERMOSTAT có thể báo cáo thông tin chi tiết về hệ thống sưởi ấm, thông gió và điều hoà không khí (HVAC).
ThermostatMode	Đặc điểm này thuộc về các loại thiết bị THERMOSTAT hỗ trợ nhiều chế độ của máy điều nhiệt.	SetMode
ThermostatTemperatureSetpoint	Đặc điểm này thuộc về các loại thiết bị THERMOSTAT (MÁY ĐIỀU NHIỆT) hỗ trợ việc đặt nhiệt độ mục tiêu và phạm vi nhiệt độ.	SetHeat SetCool SetRange

JSON

Nếu không có đặc điểm trong phản hồi GET, tức là đặc điểm hoặc tính năng đó hiện không dùng được cho thiết bị. Hãy xem phần Các 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 của máy điều nhiệt, hãy dùng đặc điểmNhiệ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 đặc điểmĐộ ẩm . Độ ẩm môi trường được đo tại thiết bị.

Thang đo nhiệt độ

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

Thay đổi chế độ

Chế độ của máy điều nhiệt được quản lý bằng 2 đặc điểm khác nhau:ThermostatMode vàThermostatEco.

Chế độ 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 đặc điểm ThermostatMode.

Bạn cũng có thể dùng lệnh này để chuyển 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ụ: để thay đổi một trong các chế độ tiêu chuẩn của máy điều nhiệt, hãy làm như sau:

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ế độ bằng 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 ảnh hưởng đến các đặc điểm khác, dựa trên trạng thái hiện tại hoặc các thay đổi đối với Chế độ tiết kiệm năng lượng:

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

Các lệnh cho đặc điểm ThermostatTemperatureSetpoint bị từ chối.
Các điểm đặt nhiệt độ không được trả về theo đặc điểm ThermostatTemperatureSetpoint .

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 ở chế độ SƯỞI ẤM, LÀM MÁT hoặc SƯỞI ẤM LÀM MÁT và các điểm đặ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ế độ là TẮT hoặc khi Chế độ tiết kiệm năng lượng được đặt thành MANUAL_ECO.

Máy điều nhiệt phải ở chế độ tương ứng với lệnh đượ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ụ: để đưa 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`
LÀM MÁT	SetCool	`coolCelsius`
HEATCOOL	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 ở chế độ SƯỞI ẤM, hãy dùng lệnh SetHeat của đặc điểm ThermostatTemperatureSetpoint:

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 chế độ Tiết kiệm năng lượng

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

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

Nếu máy điều nhiệt hỗ trợ quạt, hãy 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 thời gian chạy quạt (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 các lệnh hoặc gửi sự kiện, hoặc bạn nhận được lỗi từ API liên quan đến thiết bị, hãy sử dụng đặc điểmKhả năng kết nối để kiểm tra khả năng kết nối của thiết bị ở trạng thái NGOẠI TUYẾN. Kiểm tra kết nối Internet của thiết bị và đảm bảo Dịch vụ Nest đang hoạt động.

Nếu đã bật sự kiện, bạn cũng sẽ nhận được một sự kiện tài nguyên cho biết rằng thiết bị đã chuyển sang trạng thái không kết nối mạng:

Phần tải

{
  "eventId" : "e915e9ce-f227-42f4-aa76-2a6e1e40dafd",
  "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 một trường đặc điểm đều 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:

Phần tải

{
  "eventId" : "66464d68-b841-49ad-ae25-b896d54d14a9",
  "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"
  ]
}

Các sự kiện được kích hoạt cho tất cả các đặc điểm liên kết với 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 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 các sự kiện thay đổi chế độ của máy điều nhiệt.

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

Lỗi

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

Thông báo Lỗi	RPC	Khắc phục sự cố
Giá trị làm mát phải lớn hơn giá trị sưởi ấm.	`INVALID_ARGUMENT`	Đảm bảo rằng trường `heatCelsius` nhỏ hơn trường `coolCelsius` trong lệnh của bạn.
Không được phép dùng lệnh này ở chế độ hiện tại của máy điều nhiệt.	`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 là TẮT, theo đặc điểm ThermostatMode . Bạn phải thay đổi chế độ của máy điều nhiệt thành HEAT, COOL hoặc HEATCOOL trước khi thay đổi chế độ Tiết kiệm năng lượng.
Quạt của máy điều nhiệt không hoạt động.	`FAILED_PRECONDITION`	Máy điều nhiệt không có chức năng quạt. Bạn không thể dùng các đặc điểm và lệnh liên quan đến quạt cho thiết bị này.
Không được phép dùng 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 ở 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.

Bộ điều nhiệt Sử dụng bộ sưu tập để sắp xếp ngăn nắp các trang Lưu và phân loại nội dung dựa trên lựa chọn ưu tiên của bạn.

Đặc điểm

Tài liệu tham khảo

JSON

Nhiệt độ và độ ẩm

Thang đo nhiệt độ

Thay đổi chế độ

Chế độ chuẩn

Yêu cầu

Phản hồi

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

Yêu cầu

Phản hồi

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

Yêu cầu

Phản hồi

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

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

Yêu cầu

Phản hồi

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

Phần tải

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

Phần tải

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

Lỗi

Bộ điều nhiệt