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

Entities 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.