Smart Home Fill Trait Schema

action.devices.traits.Fill - This trait applies to devices that support being filled such as a bathtub.

Device ATTRIBUTES

Devices with this trait may report the following attributes as part of the SYNC operation. To learn more about handling SYNC intents, see Intent fulfillment.

Attributes Type Description
availableFillLevels Object

Describes different levels of filling the device.

levels Array

Required.

List of level names and language-specific synonyms.

[item, ...] Object

Level name and its language-specific synonyms.

level_name String

Required.

Internal name of the level. This can be non-user-friendly, and will be shared across all languages.

level_values Array

Required.

Synonyms of the level in each supported language.

[item, ...] Object

Synonyms of the level in a given language.

level_synonym Array

Required.

Synonym of the level. The first string in this list is used as the canonical name of the level in that language.

[item, ...] String

Synonym name.

lang String

Required.

Language code (ISO 639-1). See supported languages.

ordered Boolean

Required.

If true, the device handles additional grammar for increase or decrease logic, as represented by the levels array (for example, half level).

supportsFillPercent Boolean

(Default: false)

If true, accept commands for adjusting the level to a percentage.

Examples

Device with basic fill or drain capabilities that does not support discrete fill levels.

Device that supports discrete fill levels.

{
  "availableFillLevels": {
    "levels": [
      {
        "level_name": "half_level",
        "level_values": [
          {
            "level_synonym": [
              "half",
              "half way",
              "one half"
            ],
            "lang": "en"
          }
        ]
      },
      {
        "level_name": "full_level",
        "level_values": [
          {
            "level_synonym": [
              "full",
              "all the way",
              "complete"
            ],
            "lang": "en"
          }
        ]
      }
    ],
    "ordered": true
  }
}

Device STATES

Devices with this trait may report the following states as part of the QUERY operation. To learn more about handling QUERY intents, see Intent fulfillment.

States Type Description
isFilled Boolean

Required.

True if the device is filled to any level. False if the device is completly drained.

currentFillLevel String

Required if availableFillLevels attribute is set. Indicates the current level_name from the availableFillLevels attribute at which the device is filled.

currentFillPercent Number

Required if supportsFillPercent attribute is set. Indicates the current fill level percentage.

Examples

Is the bathtub filled?

{
  "isFilled": true
}

Is the bathtub filled? (with levels).

{
  "isFilled": true,
  "currentFillLevel": "half_level"
}

Device COMMANDS

Devices with this trait may respond to the following commands as part of the EXECUTE operation. To learn more about handling EXECUTE intents, see Intent fulfillment.

action.devices.commands.Fill

Fill or drain the device.

Parameters

Parameters Type Description
fill Boolean

Required.

True to fill, false to drain.

fillLevel String

Indicates the level_name from the availableFillLevels attribute to set. If unspecified, fill to the default level.

fillPercent Number

Indicates the requested level percentage.

Examples

Fill the bathtub.

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": true
  }
}

Drain the bathtub.

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": false
  }
}

Fill the bathtub halfway.

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": true,
    "fillLevel": "half_level"
  }
}

Increase the bathtub fill level by one (require ordered attribute to be true).

{
  "command": "action.devices.commands.Fill",
  "params": {
    "fill": true,
    "fillLevel": "full_level"
  }
}

Device ERRORS

See the full list of errors and exceptions.