lib-ecobee 库参考

原文: https://finproducts.atlassian.net/wiki/spaces/JIDD3/pages/34793685028/FIN+5.3.1+lib-ecobee 中文整理基于 FIN 5.3.1

导读： Ecobee 库实现了对 Ecobee 恒温器的连接器支持。

以下为 API 参考，保留英文以便对照源码；目录已列出（英文标题便于检索）；概述已尽量中译。

---

目录（导读）

• lib
• meta
• docs
• tags
• Overview
• Prerequisites
• Connectivity
• Current Values
• Writable Points
• History Points
• Learn
• API Rate Limiting
  • def
  • supertypes
  • usage
  • tags

---

概述（中译）

Ecobee 连接器

---

API 正文（英文）

docs

Overview • Prerequisites • Connectivity • Current Values • Writable Points • History Points • Learn • API Rate Limiting

---

tags

ecobeeClientId	Your Ecobee API Key
ecobeeConn	Ecobee connector
ecobeeConnRef	Used on a proxy point to reference its parent ecobeeConn
ecobeeCur	Ecobee address to use to get the current value
ecobeeHis	Ecobee address to use to sync point history
ecobeePoint	Point which synchronizes data via an Ecobee connector
ecobeeRefreshToken	The refresh token you obtained for your API key
ecobeeWrite	Ecobee address to use to write a point value

---

lib ecobee

Overview

The Ecobee library implements connector support for Ecobee Thermostats.

Prerequisites

Before you can use the Ecobee connector, you need to follow these steps to acquire an API key and OAuth tokens for communicating with the API

1. Register your device and create a developer account at this web page: https://www.ecobee.com/en-us/developers/
2. Log into your Ecobee portal
   1. Go the the developer menu item
   2. Create your application using Create New
   3. Make note of your API key for the next step
3. Open a command prompt or terminal and run the following commands
   1. cd <installation_home>
   2. ./bin/fan hxEcobee::EcobeeAuthorization -scope smartRead
      • To enable read/write to your thermostat, use -scope smartWrite instead.
      • Follow the instructions to obtain a PIN and authorize your application. After completing the steps the program will provide you with the set of tags that must be set on your connector as describe below.

Connectivity

The Ecobee API is a RESTful API over HTTPS. You can connect to all your registered devices by creating an ecobeeConn rec (the values in <> are obtained by completing the prerequisites):

dis: "My Home"
conn
ecobeeConn
ecobeeClientId: "<API key>"
ecobeeRefreshToken: "<refresh token>"

Current Values

The Ecobee connector uses the ecobeeCur tag on a point to get the current value of a particular device property. The value of this tag is specified as:

<ecobeeCur> := <thermostat-id>('/' property-path)*
<property-path> := <property name> | <property-selector>
<property-name> := Str
<property-selector> := <property-name> '[' [<property-name> '='] <value>']'
<value> := Str

NOTE: for the property-selector syntax you can omit the property-name if the value
corresponds to an object's unique id.

Ecobee thermostats are represented in JSON format. This syntax is basically a way to navigate down the tree of JSON objects to get the property value you want. For more details on the Ecobee Thermostat object representation, see the Ecobee Thermostat Object Documentation

For example: to get the the temperature currently reported by the thermostat, this is the actualTemperature property of the runtime object on the Thermostat. The ecobeeCur for this property on thremostat with id 12345:

// The thermostat actual temperature
ecobeeCur: "/12345/runtime/actualTemperature"

// Thermostat JSON
{
  "identifier": "12345",
  "runtime": {
    "actualTemperature": 705
    ...
  }
  ...
}

Your thermostat may have multiple remote sensors connected to it. If you want to get the temperature being reported by a remote sensor you will need to use the <property-selector> syntax like below (because there are multiple remote sensors). The property-selector syntax must be used whenever an object is a list.

// The temperature reported by the "Game Room" remote sensor
ecobeeCur: "/12345/remoteSensors[rs:100]/capability[type=temperature]/value"

// Thermostat JSON
{
  "identifier": "12345",
  ...
  "remoteSensors": [
    {
      "id": "rs:100",
      "name": "Game Room",
      ...
      "capability": [
        {
          "id": "1",
          "type": "temperature",
          "value": "705"
        },
        {
          "id": "2",
          "type": "occupancy",
          "value": "false"
        }
      ]
    },
    {
      "id": "ei:0",
      "name": "Upstairs Thermostat",
      ...
      "capability": [
        {
          "id": "1",
          "type": "temperature",
          "value": "759"
        },
        {
          "id": "2",
          "type": "humidity",
          "value": "31"
        },
        {
          "id": "3",
          "type": "occupancy",
          "value": "true"
        }
      ]
    }
  ]
}

Writable Points

The connector supports writing values to an Ecobee thermostat. Use the ecobeeWrite tag to configure the address for the point to write. It uses the same syntax defined above for ecobeeCur.

History Points

The connector supports reading historical trend data from the thermostat. Use the ecobeeHis tag to configure the address for the historical point to trend. It uses a similar syntax as defined above for ecobeeCur. Only runtime report data is currently supported.

ecobeeHis: <thermostat-id>/runtime/<runtimeReportProperty>

The connector learn handles configuring this tag for the most common points but you can configure additional history points. See Ecobee Runtime Reports for more details on available runtime report properties and how they are reported.

Learn

The Ecobee connector supports connLearn() to learn the most common points from your Thermostat. It will not show you all properties that can be learned about a thermostat - just the most common. You can always manually create a point and specify the ecobeeCur and ecobeeWrite using the syntax outlined above.

API Rate Limiting

As detailed in the Ecobee API Docs, polling for API changes should be limited to once every 3 minutes. The connector handles this for your. Even if your connector is configured with a pollTime of less than 3 minutes, the connector will only attempt to sync current data values at 3 minute intervals.

---

---

def

ecobeeClientId

Your Ecobee API Key

---

meta

def	ecobeeClientId
is	password
lib	lib:ecobee
tagOn	ecobeeConn
uiInput	ui::PasswordInput

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters
password	Manages password which is hashed/stored to the password store

---

---

def

ecobeeConn

Ecobee connector

---

meta

connFeatures
def	ecobeeConn
icon	ecobee
is	conn
lib	lib:ecobee

---

usage

ecobeeConn  conn

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
conn	Connector for communication to a remote system

---

tags

actorTimeout	Timeout for messages send to the connector's actor thread
connErr	Error message associated when connStatus indicates an error condition
connLinger	Linger timeout used to keep a connector open
connOpenRetryFreq	Duration used for connector open retries
connPingFreq	Duration used to configure the auto-ping feature on a given connector
connState	Current connection state of a connector as one of the predefined strings
connStatus	Current status of a connector as one of the predefined strings See Connectors
connTuningRef	Reference to a tuning configuration defined by a connTuning rec
dis	Display name for an entity
disabled	Indicates the entity is in a disabled state
ecobeeClientId	Your Ecobee API Key
ecobeeRefreshToken	The refresh token you obtained for your API key
id	Defines the unique identifier of an entity in system using a ref value type

---

---

def

ecobeeConnRef

Used on a proxy point to reference its parent ecobeeConn

---

meta

def	ecobeeConnRef
is	ref
lib	lib:ecobee
of	ecobeeConn
tagOn	ecobeePoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
ref	Reference to an entity

---

---

def

ecobeeCur

Ecobee address to use to get the current value.

---

meta

def	ecobeeCur
is	str
lib	lib:ecobee
tagOn	ecobeePoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

ecobeeHis

Ecobee address to use to sync point history.

---

meta

def	ecobeeHis
is	str
lib	lib:ecobee
tagOn	ecobeePoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters

---

---

def

ecobeePoint

Point which synchronizes data via an Ecobee connector.

---

meta

def	ecobeePoint
is	connPoint
lib	lib:ecobee

---

usage

ecobeePoint  point

---

supertypes

marker	Marker labels a dict with typing information
entity	Top-level dicts with a unique identifier
point	Data point such as a sensor or actuator
connPoint	Point associated with a connector for data synchronization with a remote system

---

tags

connTuningRef	Reference to a tuning configuration defined by a connTuning rec
cur	Supports current value
curCalibration	Calibration value to apply to adjust the value read from the connector before updating curVal
curConvert	Conversion to apply when reading curVal from connector
dis	Display name for an entity
disMacro	Display name using macro syntax
disabled	Indicates the entity is in a disabled state
ecobeeConnRef	Used on a proxy point to reference its parent ecobeeConn
ecobeeCur	Ecobee address to use to get the current value
ecobeeHis	Ecobee address to use to sync point history
ecobeeWrite	Ecobee address to use to write a point value
enum	Defines an eumeration of string key names
equipRef	Reference to equip which contains this entity
ghgFactorHis	Identifies point record with interval emission factor data that the Greenhouse Gas Emission Engine uses to calculate emissions
his	Supports historization of data
hisConvert	Conversion to apply when reading history data from connector
id	Defines the unique identifier of an entity in system using a ref value type
kind	Kind name used to identity a value data type
maxVal	Inclusive maximum for a numeric value
minVal	Inclusive minimum for a numeric value
navName	Navigation name commonly used with disMacro to create computed display strings
pointFunction	Classifies the point as a sensor, command, or setpoint
pointQuantity	Quantity the point senses or controls
pointSubject	What the point senses or controls
siteRef	Reference to site which contains the entity
spaceRef	Reference to space which contains this entity
systemRef	Reference to system
tz	Timezone identifier from standard timezone database
unit	Unit identifier from standard unit database
writable	Supports writing data
writeConvert	Conversion to apply when writing writeVal to the connector

---

---

def

ecobeeRefreshToken

The refresh token you obtained for your API key

---

meta

def	ecobeeRefreshToken
is	password
lib	lib:ecobee
tagOn	ecobeeConn
uiInput	ui::PasswordInput

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters
password	Manages password which is hashed/stored to the password store

---

---

def

ecobeeWrite

Ecobee address to use to write a point value.

---

meta

def	ecobeeWrite
is	str
lib	lib:ecobee
tagOn	ecobeePoint

---

supertypes

val	Data value type
scalar	Scalar is an atomic value kind
str	Unicode string of characters