From 4f03a0e110227f2d17cf2d8a9d64c42e9d0828db Mon Sep 17 00:00:00 2001 From: Deborah Femia Date: Tue, 27 Aug 2024 17:34:42 +0000 Subject: [PATCH] GITBOOK-424: Note device props not available offline --- docs/api-clients/devices/README.md | 12 +++++++----- .../devices/displaying-device-power-status.md | 6 +++--- docs/products/smart-locks/lock-and-unlock.md | 2 +- 3 files changed, 11 insertions(+), 9 deletions(-) diff --git a/docs/api-clients/devices/README.md b/docs/api-clients/devices/README.md index 1ee01f25..0e0169b9 100644 --- a/docs/api-clients/devices/README.md +++ b/docs/api-clients/devices/README.md @@ -22,7 +22,7 @@ Superseded by [capability flags](../../capability-guides/device-and-system-capab ### `device.properties` Properties -
PropertyTypeDescription
onlineBoolean
Required		Indicates whether the device is online.
accessory_keypadObject
Optional		Accessory keypad state. See accessory_keypad Properties.
appearanceObject
Required		Appearance-related properties, including the read-only name of the device, as seen from the provider API and application.
modelObject
Required		Device model properties. See model Properties.
has_direct_powerBoolean
Optional		Indicates whether the device has direct power.
battery_levelNumber
Required		Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
Deprecated. Use device.properties.battery.level instead.
batteryObject
Optional		Device battery properties. See Devicebattery Properties.
manufacturerString
Optional		Manufacturer of the device. See Device Manufacturers.
image_urlString (URL)
Optional		Image URL for the device or placeholder image URL if a device-specific image is unavailable.
image_alt_textString
Optional		Alternative text for the device image.
serial_numberString
Optional		Serial number of the device.
online_access_codes_enabledBoolean
Optional		Indicates whether it is currently possible to use online access codes for the device.
Superseded by the device.properties.can_program_online_access_codes capability flag.
offline_access_codes_enabledBoolean
Optional		Indicates whether it is currently possible to use offline access codes for the device.
Superseded by the device.properties.can_program_offline_access_codes capability flag.
lockedBoolean
Optional

Indicates whether the device is locked.

Applicable to locks.

keypad_batteryObject
Optional

Keypad battery properties.

Applicable to locks.

See keypad_battery Properties.

door_openBoolean
Optional

Indicates whether the door is open.

Applicable to locks.

code_constraintsArray of objects
Optional

Constraints on access codes that can be set on the device.

Applicable to devices that support access codes.
See Access Code Constraints.

supported_code_lengthsArray of numbers
Optional

Supported code lengths for the device.

For example, [4,5] means that 1234 and 12345 are valid codes, but 123 and 123456 are invalid codes.
Applicable to devices that support access codes.

max_active_codes_supportedNumber
Optional		Maximum number of codes that can exist on the device at one time.
Applicable to devices that support access codes.
supports_backup_access_code_poolBoolean
Optional		Indicates whether the device supports backup access code pools.
Applicable to devices that support access codes.
temperature_fahrenheitNumber
Required		Temperature, measured in Fahrenheit.
Applicable to thermostats.
temperature_celsiusNumber
Required		Temperature, measured in Celsius.
Applicable to thermostats.
relative_humidityNumber
Required		Relative humidity, the amount of moisture in the air compared to the maximum amount of moisture the air can hold at a given temperature. It is a percentage expressed as a number between 0 and 1, inclusive.
Applicable to thermostats.
available_hvac_mode_settingsArray of enums (strings)

List of the available HVAC modes for the thermostat.
Possible values:

  • cool
  • heat
  • heat_cool
  • off

Applicable to thermostats.

is_heatingBoolean
Required		Indicates whether the heating system is currently heating.
Applicable to thermostats.
is_coolingBoolean
Required		Indicates whether the cooling system is currently cooling.
Applicable to thermostats.
is_fan_runningBoolean
Required		Indicates whether the fan is currently running.
Applicable to thermostats.
fan_mode_settingEnum (string)
Required

Fan mode of the thermostat.
Possible values:

  • on: The fan continuously operates, ensuring air circulation regardless of the heating or cooling demand.
  • auto: The fan activates only when heating or cooling is on, making it a more energy-efficient choice.

Applicable to thermostats.

is_temporary_manual_override_activeBoolean
Required		Indicates whether the current thermostat settings differ from the configured current_climate_setting.
Applicable to thermostats.
current_climate_settingObject
Required		Current climate setting for the thermostat. Can only be overridden manually if device.properties.current_climate_setting.manual_override_allowed is true.
Applicable to thermostats.
See Thermostat climate_setting Properties.
min_cooling_set_point_celsiusNumber
Required		Minimum cooling set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
min_cooling_set_point_fahrenheitNumber
Required		Minimum cooling set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
max_cooling_set_point_celsiusNumber
Required		Maximum cooling set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
max_cooling_set_point_fahrenheitNumber
Required		Maximum cooling set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
min_heating_set_point_celsiusNumber
Required		Minimum heating set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
min_heating_set_point_fahrenheitNumber
Required		Minimum heating set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
max_heating_set_point_celsiusNumber
Required		Maximum heating set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
max_heating_set_point_fahrenheitNumber
Required		Maximum heating set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
min_heating_cooling_delta_celsiusNumber
Required		Minimum temperature difference—that is, delta—in degrees Celsius between the cooling and heating set points when in heat-cool (auto) mode.
Applicable to thermostats.
min_heating_cooling_delta_fahrenheitNumber
Required		Minimum temperature difference—that is, delta—in degrees Fahrenheit between the cooling and heating set points when in heat-cool (auto) mode.
Applicable to thermostats.
XXX_metadataObjectManufacturer-specific metadata for the device, where XXX is the manufacturer.
+
PropertyTypeDescription
onlineBoolean
Required		Indicates whether the device is online.
accessory_keypadObject
Optional		Accessory keypad state. See accessory_keypad Properties.
appearanceObject
Required		Appearance-related properties, including the read-only name of the device, as seen from the provider API and application.
modelObject
Required		Device model properties. See model Properties.
has_direct_powerBoolean
Optional		Indicates whether the device has direct power.
battery_levelNumber
Required		Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
If the device is offline, Seam does not return this property.
Deprecated. Use device.properties.battery.level instead.
batteryObject
Optional

Device battery properties.

If the device is offline, Seam does not return this property.
See Devicebattery Properties.

manufacturerString
Optional		Manufacturer of the device. See Device Manufacturers.
image_urlString (URL)
Optional		Image URL for the device or placeholder image URL if a device-specific image is unavailable.
image_alt_textString
Optional		Alternative text for the device image.
serial_numberString
Optional		Serial number of the device.
online_access_codes_enabledBoolean
Optional		Indicates whether it is currently possible to use online access codes for the device.
Superseded by the device.properties.can_program_online_access_codes capability flag.
offline_access_codes_enabledBoolean
Optional		Indicates whether it is currently possible to use offline access codes for the device.
Superseded by the device.properties.can_program_offline_access_codes capability flag.
lockedBoolean
Optional

Indicates whether the device is locked.

Applicable to locks.
If the device is offline, Seam does not return this property.

keypad_batteryObject
Optional

Keypad battery properties.

Applicable to locks.

See keypad_battery Properties.

door_openBoolean
Optional

Indicates whether the door is open.

Applicable to locks.
If the device is offline, Seam does not return this property.

code_constraintsArray of objects
Optional

Constraints on access codes that can be set on the device.

Applicable to devices that support access codes.
See Access Code Constraints.

supported_code_lengthsArray of numbers
Optional

Supported code lengths for the device.

For example, [4,5] means that 1234 and 12345 are valid codes, but 123 and 123456 are invalid codes.
Applicable to devices that support access codes.

max_active_codes_supportedNumber
Optional		Maximum number of codes that can exist on the device at one time.
Applicable to devices that support access codes.
supports_backup_access_code_poolBoolean
Optional		Indicates whether the device supports backup access code pools.
Applicable to devices that support access codes.
temperature_fahrenheitNumber
Required		Temperature, measured in Fahrenheit.
Applicable to thermostats.
temperature_celsiusNumber
Required		Temperature, measured in Celsius.
Applicable to thermostats.
relative_humidityNumber
Required		Relative humidity, the amount of moisture in the air compared to the maximum amount of moisture the air can hold at a given temperature. It is a percentage expressed as a number between 0 and 1, inclusive.
Applicable to thermostats.
available_hvac_mode_settingsArray of enums (strings)

List of the available HVAC modes for the thermostat.
Possible values:

  • cool
  • heat
  • heat_cool
  • off

Applicable to thermostats.

is_heatingBoolean
Required		Indicates whether the heating system is currently heating.
Applicable to thermostats.
is_coolingBoolean
Required		Indicates whether the cooling system is currently cooling.
Applicable to thermostats.
is_fan_runningBoolean
Required		Indicates whether the fan is currently running.
Applicable to thermostats.
fan_mode_settingEnum (string)
Required

Fan mode of the thermostat.
Possible values:

  • on: The fan continuously operates, ensuring air circulation regardless of the heating or cooling demand.
  • auto: The fan activates only when heating or cooling is on, making it a more energy-efficient choice.

Applicable to thermostats.

is_temporary_manual_override_activeBoolean
Required		Indicates whether the current thermostat settings differ from the configured current_climate_setting.
Applicable to thermostats.
current_climate_settingObject
Required		Current climate setting for the thermostat. Can only be overridden manually if device.properties.current_climate_setting.manual_override_allowed is true.
Applicable to thermostats.
See Thermostat climate_setting Properties.
min_cooling_set_point_celsiusNumber
Required		Minimum cooling set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
min_cooling_set_point_fahrenheitNumber
Required		Minimum cooling set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
max_cooling_set_point_celsiusNumber
Required		Maximum cooling set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
max_cooling_set_point_fahrenheitNumber
Required		Maximum cooling set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
min_heating_set_point_celsiusNumber
Required		Minimum heating set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
min_heating_set_point_fahrenheitNumber
Required		Minimum heating set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
max_heating_set_point_celsiusNumber
Required		Maximum heating set point that this thermostat supports, measured in Celsius.
Applicable to thermostats.
max_heating_set_point_fahrenheitNumber
Required		Maximum heating set point that this thermostat supports, measured in Fahrenheit.
Applicable to thermostats.
min_heating_cooling_delta_celsiusNumber
Required		Minimum temperature difference—that is, delta—in degrees Celsius between the cooling and heating set points when in heat-cool (auto) mode.
Applicable to thermostats.
min_heating_cooling_delta_fahrenheitNumber
Required		Minimum temperature difference—that is, delta—in degrees Fahrenheit between the cooling and heating set points when in heat-cool (auto) mode.
Applicable to thermostats.
XXX_metadataObjectManufacturer-specific metadata for the device, where XXX is the manufacturer.
### `location` Properties @@ -42,15 +42,17 @@ Superseded by [capability flags](../../capability-guides/device-and-system-capab ### `model` Properties -
PropertyTypeDescription
can_connect_accessory_keypadBoolean
Optional		Indicates whether the device can connect a accessory keypad.
display_nameString
Required		Display name of the device model.
manufacturer_display_nameString
Required		Display name that corresponds to the manufacturer-specific terminology for the device.
has_built_in_keypadBoolean
Optional		Indicates whether the device has a built in accessory keypad.
offline_access_codes_supportedBoolean
Optional		Indicates whether the device supports offline access codes.
Superseded by the device.properties.can_program_offline_access_codes capability flag.
online_access_codes_supportedBoolean
Optional		Indicates whether the device supports online access codes.
Superseded by the device.properties.can_program_online_access_codes capability flag.
accessory_keypad_supportedBoolean
Optional		Indicates whether the device supports an accessory keypad.
Deprecated. Use device.properties.model.can_connect_accessory_keypad instead.
+
PropertyTypeDescription
can_connect_accessory_keypadBoolean
Optional		Indicates whether the device can connect a accessory keypad.
display_nameString
Required		Display name of the device model.
manufacturer_display_nameString
Required		Display name that corresponds to the manufacturer-specific terminology for the device.
has_built_in_keypadBoolean
Optional		Indicates whether the device has a built in accessory keypad.
offline_access_codes_supportedBoolean
Optional		Indicates whether the device supports offline access codes.
Superseded by the device.properties.can_program_offline_access_codes capability flag.
online_access_codes_supportedBoolean
Optional		Indicates whether the device supports online access codes.
Superseded by the device.properties.can_program_online_access_codes capability flag.
accessory_keypad_supportedBoolean
Optional		Indicates whether the device supports an accessory keypad.
Deprecated. Use device.properties.model.can_connect_accessory_keypad instead.
### Device `battery` Properties +If the device is offline, Seam does not return these properties. +
PropertyTypeDescription
levelNumber
Required		Indicates the battery level of the device as a decimal value between 0 and 1, inclusive.
statusEnum (string)
Required

Represents the current status of the battery charge level.

Values are:

  • critical: Indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging.
  • low: Signifies that the battery is under the preferred threshold and should be charged soon.
  • good: Denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging.
  • full: Represents a battery that is fully charged, providing the maximum duration of usage.
### Thermostat `climate_setting` Properties -
PropertyTypeDescription
hvac_mode_settingEnum (string)
Required

HVAC mode to which the thermostat is set.

Possible values:

  • cool
  • heat
  • heat_cool
  • off
cooling_set_point_celsiusNumber
Optional		The cooling set point, measured in Celsius, if cooling is turned on. When the ambient temperature rises above this set point, cooling turns on.
heating_set_point_celsiusNumber
Optional		The heating set point, measured in Celsius, if heating is turned on. When the ambient temperature drops below this set point, heating turns on.
cooling_set_point_fahrenheitNumber
Optional		The cooling set point, measured in Fahrenheit, if cooling is turned on. When the ambient temperature rises above this set point, cooling turns on.
heating_set_point_fahrenheitNumber
Optional		The heating set point, measured in Fahrenheit, if heating is turned on. When the ambient temperature drops below this set point, heating turns on.
manual_override_allowedBoolean
Required		Indicates whether another user can use the thermostat or API to override this climate setting.
+
PropertyTypeDescription
hvac_mode_settingEnum (string)
Required

HVAC mode to which the thermostat is set.

Possible values:

  • cool
  • heat
  • heat_cool
  • off
cooling_set_point_celsiusNumber
Optional		The cooling set point, measured in Celsius, if cooling is turned on. When the ambient temperature rises above this set point, cooling turns on.
heating_set_point_celsiusNumber
Optional		The heating set point, measured in Celsius, if heating is turned on. When the ambient temperature drops below this set point, heating turns on.
cooling_set_point_fahrenheitNumber
Optional		The cooling set point, measured in Fahrenheit, if cooling is turned on. When the ambient temperature rises above this set point, cooling turns on.
heating_set_point_fahrenheitNumber
Optional		The heating set point, measured in Fahrenheit, if heating is turned on. When the ambient temperature drops below this set point, heating turns on.
manual_override_allowedBoolean
Required		Indicates whether another user can use the thermostat or API to override this climate setting.
## Device Error Types @@ -139,11 +141,11 @@ The following example shows a `device_provider` object: ## Access Code Constraints -Each constraint in the `code_constraints` array contains objects with the `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are [manufacturer](broken-reference) or [device](broken-reference)-specific. +Each constraint in the `code_constraints` array contains objects with the `constraint_type` property. Depending on the constraint type, there may also be additional properties. Note that some constraints are [manufacturer](broken-reference/) or [device](broken-reference/)-specific. The `constraint_type` property can be one of the following enum values: -
Constraint TypeDescription
no_zeros0s cannot be used as digits in the PIN code.
cannot_start_with_12The PIN code cannot start with the sequence of digits 12.
no_triple_consecutive_intsNo more than three digits in a row can be consecutive or the same in the PIN code.
cannot_specify_pin_codeYou cannot specify a PIN code. You must leave the code empty, and the lock provider generates a PIN code.
pin_code_matches_existing_set

If you specify a PIN code, it must match an existing set of PIN codes used in the account.

For example, the PIN code could match the code assigned to a user in the system.

start_date_in_futureFor time-bound codes, the start date must be in the future.
no_ascending_or_descending_sequenceThe PIN code cannot consist of a sequence of consecutive digits.
at_least_three_unique_digitsThe PIN must contain at least three unique digits.
cannot_contain_089

The PIN code cannot contain the digits 0, 8, or 9.

For example, this restriction could apply to a cylinder lock that only includes the digits 1 to 7.

name_length

The name of the code has some restrictions on length.

When the constraint_type is name_length, the constraint object has one or two additional properties called min_length and max_length to specify the length constraints.

name_must_be_uniqueThe name of the code must be unique within the device.
+
Constraint TypeDescription
no_zeros0s cannot be used as digits in the PIN code.
cannot_start_with_12The PIN code cannot start with the sequence of digits 12.
no_triple_consecutive_intsNo more than three digits in a row can be consecutive or the same in the PIN code.
cannot_specify_pin_codeYou cannot specify a PIN code. You must leave the code empty, and the lock provider generates a PIN code.
pin_code_matches_existing_set

If you specify a PIN code, it must match an existing set of PIN codes used in the account.

For example, the PIN code could match the code assigned to a user in the system.

start_date_in_futureFor time-bound codes, the start date must be in the future.
no_ascending_or_descending_sequenceThe PIN code cannot consist of a sequence of consecutive digits.
at_least_three_unique_digitsThe PIN must contain at least three unique digits.
cannot_contain_089

The PIN code cannot contain the digits 0, 8, or 9.

For example, this restriction could apply to a cylinder lock that only includes the digits 1 to 7.

name_length

The name of the code has some restrictions on length.

When the constraint_type is name_length, the constraint object has one or two additional properties called min_length and max_length to specify the length constraints.

name_must_be_uniqueThe name of the code must be unique within the device.
## `device` Methods diff --git a/docs/core-concepts/devices/displaying-device-power-status.md b/docs/core-concepts/devices/displaying-device-power-status.md index 6fb12c6e..98ab8e58 100644 --- a/docs/core-concepts/devices/displaying-device-power-status.md +++ b/docs/core-concepts/devices/displaying-device-power-status.md @@ -17,7 +17,7 @@ To display this information, use either of the following Seam mechanisms: Seam polls connected devices and accounts every ten minutes and updates the following device properties accordingly: -
PropertyTypeDescription
properties.has_direct_powerBooleanIndicates whether the device has direct power, that is, whether the device is wired
properties.batteryObjectBattery information, including level and status
properties.battery.levelNumber (0-1)Battery level of the device as a decimal value between 0 and 1, inclusive
properties.battery.statusEnum (string)

Current status of the battery charge level.

Values are:

critical: Indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging.

low: Signifies that the battery is under the preferred threshold and should be charged soon.

good: Denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging.

full: Represents a battery that is fully charged, providing the maximum duration of usage.

+
PropertyTypeDescription
properties.has_direct_powerBooleanIndicates whether the device has direct power, that is, whether the device is wired
properties.batteryObjectBattery information, including level and status
If the device is offline, Seam does not return this property.
properties.battery.levelNumber (0-1)Battery level of the device as a decimal value between 0 and 1, inclusive
If the device is offline, Seam does not return this property.
properties.battery.statusEnum (string)

Current status of the battery charge level.
If the device is offline, Seam does not return this property.

Values are:

critical: Indicates an extremely low level, suggesting imminent shutdown or an urgent need for charging.

low: Signifies that the battery is under the preferred threshold and should be charged soon.

good: Denotes a satisfactory charge level, adequate for normal use without the immediate need for recharging.

full: Represents a battery that is fully charged, providing the maximum duration of usage.

Use a [Get Device](../../api-clients/devices/get-device.md) request to retrieve the current power status of a device. First, determine whether the device is wired. If the device is battery-powered (that is, not wired), get the battery level and status. Then, display the retrieved device power status in your app. @@ -237,7 +237,7 @@ You can retrieve these events using a [List Events](../../api-clients/events/lis When issuing a [List Events](../../api-clients/events/list-events.md) request to retrieve [`device.low_battery`](../../api-clients/events/#event-types) or [`device.battery_status_changed`](../../api-clients/events/#event-types) events for a specific device, include the following parameters: -
ParameterTypeDescription
device_idString (UUID)ID of the device for which you want to retrieve device.connected or device.disconnected events
event_typeStringEvent type that you want to retrieve, that is, device.connected or device.disconnected
sinceStringDesired starting event generation date and time
You must include since or between.
betweenSet of two stringsDesired starting and ending event generation dates and times
For example:
["2024-01-01T00:00:00Z", "2024-02-01T00:00:00Z"]
You must include between or since.
+
ParameterTypeDescription
device_idString (UUID)ID of the device for which you want to retrieve device.connected or device.disconnected events
event_typeStringEvent type that you want to retrieve, that is, device.connected or device.disconnected
sinceStringDesired starting event generation date and time
You must include since or between.
betweenSet of two stringsDesired starting and ending event generation dates and times
For example:
["2024-01-01T00:00:00Z", "2024-02-01T00:00:00Z"]
You must include between or since.
The following example uses the List Events request to retrieve all `device.battery_status_changed` events for a specific device since January 1, 2024: @@ -472,4 +472,4 @@ return nil ### Retrieve Battery-Related Events Using a Webhook -You can set up webhook endpoints to receive `device.battery_status_changed` and `device.low_battery` events. Then, you can use the receipt of these events to display the corresponding device status in your app. For more information about configuring webhooks, see [Webhooks](../webhooks.md). +You can set up webhook endpoints to receive `device.battery_status_changed` and `device.low_battery` events. Then, you can use the receipt of these events to display the corresponding device status in your app. For more information about configuring webhooks, see [Webhooks](../webhooks.md). diff --git a/docs/products/smart-locks/lock-and-unlock.md b/docs/products/smart-locks/lock-and-unlock.md index b78e183f..c35c438d 100644 --- a/docs/products/smart-locks/lock-and-unlock.md +++ b/docs/products/smart-locks/lock-and-unlock.md @@ -1120,7 +1120,7 @@ return nil ## Checking the Locked Status of a Lock -To retrieve the locked status of a specific door lock, use the [Get Lock](../../api-clients/locks/get-lock.md) or [Get Device](../../api-clients/devices/get-device.md) endpoint by providing the `device_id` of the desired lock. This operation returns detailed information, including the current locked status. +To retrieve the locked status of a specific door lock, use the [Get Lock](../../api-clients/locks/get-lock.md) or [Get Device](../../api-clients/devices/get-device.md) endpoint by providing the `device_id` of the desired lock. This operation returns detailed information, including the current locked status. Note that if the lock is offline, Seam does not return the `device.locked` property. {% tabs %} {% tab title="Python" %}