SmartBuildings thermostat name vs physical device name

Overview

The base GET/thermostats/{thermostatId} response returns thermostatName and namefields. These values represent the thermostat name on the physical device, and the thermostat name in SmartBuildings respectfully.

This is a feature many of our integrators have requested, so that they can allow the individual thermostat users to set a display name for themselves, while still allowing the property/building managers to set a name that makes sense to them in the context of a manager.

This is most relevant when a thermostat is in Resident Mode. In that case the resident of the unit with the thermostat could be expected to change the name on the thermostat themselves either directly on the physical device or after registering it in the ecobee Residential Portal.

Implementation Details

We've implemented this change of behavior in 2 areas.

1. Name as set and returned via the SmartBuildings API
2. Name as set and displayed in SmartBuildings

thermostatName vs name

This thermostatName field indicates the name that will be shown on the thermostat itself, and the name that will be shown in the ecobee Residential Portal if the thermostat is in resident mode and the resident has registered the thermostat themselves.

The name field now indicates what will be shown in SmartBuildings applications.

As a SmartBuildings API user, you now have the ability to set these names together or separately as desired. One or both of the fields may be set at the same time.

If an API user wishes to keep them in sync when setting the name, just pass in both fields with the same value in a single PATCH request.

Name as displayed in SmartBuildings Applications

In the SmartBuildings web portal or mobile application, the display name of the thermostat will always be either the value from the name field in the API, or the thermostatId.

The thermostatId will be displayed only when the name field contains an empty string.

When a user changes the name of the thermostat in one of the SmartBuildings applications, one of two outcomes will happen:

1. If the thermostat is currently in resident mode, i.e., isResidentMode is true, then the name will only be set for the SmartBuildings applications. Only the name field in the API will be updated.
2. If the thermostat is not in resident mode, then the name will be set both for SmartBuildings and on the physical device. Both the name and the thermostatName fields in the API will be updated.

This behavior is different from the behavior when setting the name through the API, as the API user has full control of both the name and thermostatName fields and can set them independently.