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

A switch entity for Homex

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

Home Assistant docs: https://www.home-assistant.io/integrations/switch.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`.

* `: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.Switch`
* `handle_off/1` - From `Homex.Entity.Switch`

### 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 MySwitch do
  use Homex.Entity.Switch, name: "my-switch"

  def handle_on(entity) do
    IO.puts("Switch turned on")
    entity
  end

  def handle_off(entity) do
    IO.puts("Switch turned off")
    entity
  end
end
```

# `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_off`

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

Sets the switch state to off

# `set_on`

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

Sets the switch state to on

---

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