search

WebThingsIO / schemas

A Web of Things schema repository
https://webthings.io/schemas/
5 stars 8 forks source link

Thermostat Capability Schema #13

Closed mrstegeman closed 5 years ago

mrstegeman commented 6 years ago

See also mozilla-iot/wot#61

mrstegeman commented 6 years ago

HomeKit defines the following:

dhylands commented 6 years ago

I picked up a CentraLite Zigbee thermostat. https://www.amazon.ca/Centralite-3-Pearl-Touch-Thermostat/dp/B01G99KR94

It has the following attributes that I think should be represented as properties:

It might make sense to initially drop fanMode, and limit systemMode to Off/Auto/Cool/Heat

flatsiedatsie commented 5 years ago

The next label has been removed. Does this mean this has been implemented?

mrstegeman commented 5 years ago

No, we switched project management tools. The new one doesn't rely on labels.

flatsiedatsie commented 5 years ago

No, we switched project management tools. The new one doesn't rely on labels.

Does that mean is still has the 'next' label in that tool?

Does that have a public view by any chance? :-)

mrstegeman commented 5 years ago

No, we're using GitHub Projects now instead.

https://github.com/orgs/mozilla-iot/projects/3

benfrancis commented 5 years ago

See a proposed schema below. Uses http://iotschema.org/Thermostat as a starting point, but adds a heating/cooling mode and current status as per existing implementations above.

Thermostat

TemperatureProperty (already exists)

TargetTemperatureProperty

HeatingCoolingProperty

ThermostatModeProperty

Notes:

Example

{
  "@context": "https://iot.mozilla.org/schemas/",
  "@type": ["Thermostat", "TemperatureSensor"],
  "title":"My Thermostat",
  "description": "A web connected thermostat",
  "properties": {
    "temperature": {
      "@type": "TemperatureProperty",
      "type": "number",
      "description": "Current room temperature",
      "unit": "celsius",
      "readOnly": true,
      "href": "/things/thermostat/properties/temperature",
    },
    "targetTemperature": {
      "@type": "TargetTemperatureProperty",
      "type": "number",
      "description": "User desired temperature",
      "unit": "celsius",
      "minimum": 0,
      "maximum": 40,
      "href": "/things/thermostat/properties/targettemperature",
    },
    "status": {
      "@type": "ThermostatStatusProperty",
      "type": "string",
      "description": "Whether the thermostat is currently heating or cooling",
      "emum":  ["off", "heating", "cooling"],
      "href": "/things/thermostat/properties/status",
    },
    "mode": {
      "@type": "ThermostatModeProperty",
      "type": "string",
      "description": "User defined mode to heat, cool or both",
      "emum":  ["off", "heat", "cool", "auto"],
      "href": "/things/thermostat/properties/mode",
    },
  },
  "links": [
    {
      "rel": "properties",
      "href": "/things/thermostat/properties"
    }
  ]
}

Feedback?

mrstegeman commented 5 years ago
  • degree celsius is an SI unit used by the schema. The actual unit displayed to the user can be set by a UI setting.

Do we want to define a standard property for unit display? For instance, there is a difference between the unit displayed on my thermostat and the unit displayed on my UI. The former is a property of the device itself, while the latter is a property of our UI. This is a problem I have with my home thermostats right now -- thermostat shows °F, but UI shows °C.

If we want to keep that separation, that's fine, but maybe we should come up with something constant for the thermostat property, e.g. ThermostatUnitProperty (enum, ["degree celsius", "degree fahrenheit"]).

  • I can't remember does "number/integer" in the existing TemperatureProperty schema mean that it can either be an integer or a float?

Yes, that's correct.

  • The name "HeatingCoolingProperty" is a bit clunky. The other alternative I thought of was "ThermostatStatusProperty", but "status" is a bit too generic as it could include other aspects of status like current temperature.

What about "ThermostatCurrentModeProperty" and "ThermostatTargetModeProperty"?

  • I can't think of any essential actions or events.

The only event I can think of off-hand is a "filter needs changed" event, but this might make more sense as a writable AlarmProperty.

mrstegeman commented 5 years ago

@dhylands thoughts?

dhylands commented 5 years ago

Some other useful (but not essential) events would be when the mode changes. I like the CurrentMode/TargetMode.

Aside: I'd really like to see something like an enum with predefined values rather than just being the position in the array. Something like: enum: [{off: 0}, {heat: 4},{cool: 8}, {auto:1}] although as I typed this I realized I could do something like: enum: ["off", "heat", "cool", "auto"] and then have a parallel array enumData:[0, 4, 8, 1] but then the data winds up living someplace separate from the strings and if somebody reorders the string they might not remember to reorder the data. Having 2 parallel arrays and allowing enumData to be stored in the schema would be ok.

benfrancis commented 5 years ago

@dhylands wrote:

I'd really like to see something like an enum with predefined values rather than just being the position in the array.

This is just JSON Schema Validation notation for defining an enum.

"emum": ["off", "heating", "cooling"]

means that the property's string value can be one of "off", "heating" or "cooling".

benfrancis commented 5 years ago

@mrstegeman wrote:

Do we want to define a standard property for unit display? For instance, there is a difference between the unit displayed on my thermostat and the unit displayed on my UI. The former is a property of the device itself, while the latter is a property of our UI. This is a problem I have with my home thermostats right now -- thermostat shows °F, but UI shows °C.

Hmm, this is a bit of a grey area between internal settings of a device (which I don't generally think should be represented as web thing properties), and a physical property in the real world (because it effects what is displayed on the screen like setting the colour of an LED). Given the device, by definition, must have a UI of its own in order to display this value I'm inclined to leave that setting to the device's own UI to save confusion at the API layer where the unit is always going to stay the same. Otherwise there'd be a property displayed in the web UI to set a unit, which would have no effect in the web UI.

The unit displayed in the web UI might instead be set with a global setting (e.g. gateway settings).

What about "ThermostatCurrentModeProperty" and "ThermostatTargetModeProperty"?

I'd argue these properties are not quite as closely related as these names imply. A "target mode" of "heat" does not mean that the user wants the "current mode" to be "heating", unless the temperature property reaches a certain threshold, which might never happen. The same applies to cool/cooling. Plus there's no target mode for auto, it effectively means both heating and cooling (but only one at a time, and only if certain conditions are met).

filter needs changed

What does this refer to? A filter of an air conditioner/heater, or of the thermostat itself? If it's the former then I'd suggest that might be a separate capability (I'm not aware of thermostats having filters...)

dhylands commented 5 years ago

I'd argue these properties are not quite as closely related as these names imply. A "target mode" of "heat" does not mean that the user wants the "current mode" to be "heating", unless the temperature property reaches a certain threshold, which might never happen. The same applies to cool/cooling. Plus there's no target mode for auto, it effectively means both heating and cooling (but only one at a time, and only if certain conditions are met).

Your argument sounds fine from a programmers perspective, but from a users perspective, I think they inherently understand. My thermostat has a swith called Off, Heat, Cool, and Auto and it a status inidcator to show what it's currently using. I'd also be happy with TargetMode and CurrentStatus.

Also note that there may be multiple target temperatures, typically one for heating and one for cooling (auto mode needs 2 temperatures).

Some thermostats also include a configurable min/max for each of the target temperatures.

Another thing to include might be a fan mode (auto or always on).

mrstegeman commented 5 years ago

@mrstegeman wrote:

Do we want to define a standard property for unit display? For instance, there is a difference between the unit displayed on my thermostat and the unit displayed on my UI. The former is a property of the device itself, while the latter is a property of our UI. This is a problem I have with my home thermostats right now -- thermostat shows °F, but UI shows °C.

Hmm, this is a bit of a grey area between internal settings of a device (which I don't generally think should be represented as web thing properties), and a physical property in the real world (because it effects what is displayed on the screen like setting the colour of an LED). Given the device, by definition, must have a UI of its own in order to display this value I'm inclined to leave that setting to the device's own UI to save confusion at the API layer where the unit is always going to stay the same. Otherwise there'd be a property displayed in the web UI to set a unit, which would have no effect in the web UI.

The unit displayed in the web UI might instead be set with a global setting (e.g. gateway settings).

That's fair.

What about "ThermostatCurrentModeProperty" and "ThermostatTargetModeProperty"?

I'd argue these properties are not quite as closely related as these names imply. A "target mode" of "heat" does not mean that the user wants the "current mode" to be "heating", unless the temperature property reaches a certain threshold, which might never happen. The same applies to cool/cooling. Plus there's no target mode for auto, it effectively means both heating and cooling (but only one at a time, and only if certain conditions are met).

I agree with @dhylands argument above.

filter needs changed

What does this refer to? A filter of an air conditioner/heater, or of the thermostat itself? If it's the former then I'd suggest that might be a separate capability (I'm not aware of thermostats having filters...)

Yes, it refers to the AC/heater filter. Every thermostat I've ever had, even basic ones, have filter notices.

dhylands commented 5 years ago

What does this refer to? A filter of an air conditioner/heater, or of the thermostat itself? If it's the former then I'd suggest that might be a separate capability (I'm not aware of thermostats having filters...)

Yes, it refers to the AC/heater filter. Every thermostat I've ever had, even basic ones, have filter notices.

and yes, the centralite has a filter status. It basically tracks how longhave the furnace has been running and after X minutes of runtime, it turns on the filter status to remind you to change the filter. Some of my simple thermostats don't have, but normally all of the programmable ones do.

Another type of "mode" is the "Hold Temperature" which is often used when you you go on vacation. Just set the hold temperature before you leave, and then when you get back you turn off hold mode and it goes back to running the programmed schedule.Usually this is separate from the mode we've been discussing previously.

Zigbee actually supports setting up a schedule for the thermostat as wel (and the Centralite thermostat: https://www.amazon.com/Centralite-3-Pearl-Touch-Thermostat/dp/B01G99KR94/ supports this.

benfrancis commented 5 years ago

@dhylands wrote:

Some other useful (but not essential) events would be when the mode changes.

No need for events for this, you can just listen for property changes (which in the WebSocket API are just like events).

@dhylands wrote:

I'd also be happy with TargetMode and CurrentStatus.

I don't like "target mode" because I don't think mode is a "target". The target is not to "heat", the target is a temperature, heat mode just means that the thermostat can request heat in order to reach that target temperature if it needs to. If you put the thermostat in heating mode then it's immediately in heating mode, which is completely separate information to whether it's actively requesting heat from a heater at any given point in time (also arguably a setting rather than a physical property of the thermostat). A thermostat in heating mode may continuously turn a "heat" switch on and off in order to maintain a certain temperature, or may never request heat if the current temperature remains above the target temperature. A "target mode" of "auto" is also nonsensical to me, what would that mean?

ThermostatModeProperty (off|heat|cool|auto) and HeatingCoolingProperty (off|heating|cooling) still make the most sense to me.

Your argument sounds fine from a programmers perspective, but from a users perspective, I think they inherently understand

Remember we are defining an API, not a UI which could represent things completely differently.

@mrstegeman wrote:

The only event I can think of off-hand is a "filter needs changed" event, but this might make more sense as a writable AlarmProperty.

I agree this could be represented as an AlarmProperty, or a more specialised alarm property specifically for this purpose. Should this maybe be part of a separate Furnace capability though, given this is a property of the furnace rather than the thermostat? My thermostat UI might also inform me when the water pressure of my boiler drops below the required pressure, is overheating or needs servicing for example. Where do you stop?

A device could expose both the Thermostat and Furnace capabilities if the web thing it is representing the state of a furnace as well as the state of the thermostat.

@dhylands wrote:

Another type of "mode" is the "Hold Temperature" which is often used when you you go on vacation. Just set the hold temperature before you leave, and then when you get back you turn off hold mode and it goes back to running the programmed schedule.Usually this is separate from the mode we've been discussing previously.

My (non-smart) thermostat has a similar but different function in that it has daytime and nighttime temperatures and you can either have it switch automatically between them on a fixed schedule or just be permanently set on one or the other. So rather than "off, heat, cool, auto" modes it has "auto, day, night, off". When I go away I often switch it to the "night" mode as an equivalent to "hold" in your example.

See below: IMG_20190924_161503

The slider on the bottom sets the mode, the slider on the right lets you set the clock, two on and off times, daytime temperature, nighttime temperature and "run" to run the programme. The dial in the middle is for incrementing/decrementing numbers when setting them and for temporarily overriding the target temperature (it will return to the programme at the next scheduled time). It's not obvious from the photo, but the icon of a house with a thermometer means that the thermostat is currently requesting heat from the boiler (which is the equivalent of HeatingCoolingProperty, just with no cooling option).

(I'd say this is a very standard thermostat in the UK as all the houses I've lived in have had something similar.)

Below is a Hive thermostat, which is a popular smart (Zigbee) thermostat in the UK, coming to the US. hive

On the UI it just has a target temperature, an actual (current) temperature and an indicator to show whether it's currently actively heating. No mode is displayed (there is no cool mode).

Zigbee actually supports setting up a schedule for the thermostat as well

I imagine that's a very common feature. Though trying to define a schema for this could be interesting!

flatsiedatsie commented 5 years ago

I guess most of these are properties that can just be added as required, but perhaps they're relevant:

I built my own thermostat once. It had a general "is it in a safe state" boolean, which was a compound of:

Having an alarm/safe property to trigger an alarm if something strange was detected could be very useful. Then again, it probably doesn't have to be part of the core spec.

An assumption I would be weary of is that the thermostat is for homes only. Personally, I use the code mentioned above to manage a meat smoker. People may want to use it to manage the temperature of:

For these it's valuable that a thermostat doesn't assume a temperature range. For example, meat smoking goes up to 150 degrees Celsius.

A final thing to think about is multi-room heating, but that's probably outside of the scope of a single thermostat. Some modern systems will learn the co-efficient of each room in the home to keep things very stable.