# 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`](https://developers.home.google.com/cloud-to-cloud/intents/sync) operation. To learn
more about handling `SYNC` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/sync).

| 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. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `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. At least one item with a `lang` value of `en` is required in order to provide language fallback. |
| `lang` | *String* | **Required.** Language code (ISO 639-1). See [supported languages](https://developers.home.google.com/cloud-to-cloud/traits#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`](https://developers.home.google.com/cloud-to-cloud/intents/query) operation. To learn
more about handling `QUERY` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute).

| 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. Value must be between `0` and `100`. |

#### 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`](https://developers.home.google.com/cloud-to-cloud/intents/execute) operation. To learn
more about handling `EXECUTE` intents, see
[Intent fulfillment](https://developers.home.google.com/cloud-to-cloud/integration/query-execute#handle_execute_intents).

### `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. Value must be between `0` and `100`. |

#### 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](https://developers.home.google.com/cloud-to-cloud/intents/errors-exceptions).