# `Homex.Entity.Light`
[🔗](https://github.com/kevinschweikert/homex/blob/v0.1.2/lib/homex/entity/light.ex#L1)

A light entity for Homex

Implements a `Homex.Entity`. See module for available callbacks.

https://www.home-assistant.io/integrations/light.mqtt/

## Options

* `:name` (`t:String.t/0`) - Required. the name of the entity

* `:update_interval` - the interval in milliseconds in which `handle_timer/1` get's called. Can also be `:never` to disable the timer callback The default value is `:never`.

* `:modes` - a list of supported light modes. Available: [`brightness`] The default value is `[]`.

* `:retain` (`t:boolean/0`) - if the last state should be retained The default value is `true`.

## Overridable Functions

The following functions can be overridden in your entity:

* `handle_init/1` - From `Homex.Entity`
* `handle_timer/1` - From `Homex.Entity`
* `handle_on/1` - From `Homex.Entity.Light`
* `handle_off/1` - From `Homex.Entity.Light`
* `handle_brightness/1` - From `Homex.Entity.Light`

### Default Implementations

All overridable functions have safe default implementations that return the entity unchanged.
You only need to override the functions you want to customize.

## Example

```elixir
defmodule MyLight do
  use Homex.Entity.Light, name: "my-light", modes: [:brightness]

  def handle_brightness(entity, brightness) do
    IO.puts("Light set to #{brightness}%")
    entity
  end
end
```

# `handle_brightness`

```elixir
@callback handle_brightness(entity :: Homex.Entity.t(), brightness :: float()) ::
  entity :: Homex.Entity.t() | {:error, reason :: term()}
```

Gets called when a new brightness value gets published to the brightness command topic 

# `handle_off`

```elixir
@callback handle_off(entity :: Homex.Entity.t()) ::
  entity :: Homex.Entity.t() | {:error, reason :: term()}
```

Gets called when the command topic receieves an `off_payload`

# `handle_on`

```elixir
@callback handle_on(entity :: Homex.Entity.t()) ::
  entity :: Homex.Entity.t() | {:error, reason :: term()}
```

Gets called when the command topic receieves an `on_payload`

# `set_brightness`

```elixir
@callback set_brightness(entity :: Homex.Entity.t(), brightness :: float()) ::
  entity :: Homex.Entity.t()
```

Sets the lights brightness to the specified value. Must be between 0 and 100

# `set_off`

```elixir
@callback set_off(entity :: Homex.Entity.t()) :: entity :: Homex.Entity.t()
```

Sets the light state to off

# `set_on`

```elixir
@callback set_on(entity :: Homex.Entity.t()) :: entity :: Homex.Entity.t()
```

Sets the light state to on

# `modes`

---

*Consult [api-reference.md](api-reference.md) for complete listing*