HomeElixir DSL

A complete reference of everything you can declare with use HomeElixir.DSL. For a tutorial-style walkthrough, see the README.

Entities

entity type, "id" do
  ...
end

Every entity is defined by three things:

type — the entity domain, one of the four supported types below (:input_boolean, :input_number, :input_select, :alarm_control_panel).
id — the second argument to entity/3. It becomes the entity's Home Assistant entity_id (e.g. input_boolean.presence), the YAML file name (input_boolean/presence.yaml), and the suffix of the generated get_*/set_* helpers.
name — optional, set inside the do block. The human-friendly display name shown in the Home Assistant UI. It's independent from id; if omitted, Home Assistant derives a display name from the id.

Everything else inside the do block is an optional, type-specific attribute — listed under each type below. Keyword pairs not listed here are still passed through as-is, so Home Assistant options not covered by this guide keep working.

Declaring an entity injects get_<type>_<id>/0 and set_<type>_<id>/... helper functions into the enclosing module.

`:input_boolean`

No required keys.

Optional attributes: name, initial (boolean), icon (an mdi icon string, e.g. "mdi:lightbulb").

entity :input_boolean, "presence" do
  name "Presence"
  initial false
end

Injects get_input_boolean_presence/0 and set_input_boolean_presence/1.

`:input_number`

Requires min and max.

Optional attributes: name, initial, step, mode (:slider or :box, as accepted by Home Assistant's input_number), unit_of_measurement, icon.

entity :input_number, "temperature_limit" do
  min 10
  max 30
  initial 20
end

With every optional attribute set:

entity :input_number, "thermostat_offset" do
  min -5
  max 5
  initial 0
  name "Thermostat offset"
  step 0.5
  mode :slider
  unit_of_measurement "°C"
  icon "mdi:thermometer"
end

Injects get_input_number_temperature_limit/0 and set_input_number_temperature_limit/1.

`:input_select`

Requires options.

Optional attributes: name, initial, icon, editable (boolean, whether the options can be edited from the Home Assistant UI).

entity :input_select, "cover_mode" do
  options ["open", "close"]
  initial "open"
end

With every optional attribute set:

entity :input_select, "cover_mode" do
  options ["open", "close"]
  initial "open"
  name "Cover mode"
  icon "mdi:window-shutter"
  editable false
end

Injects get_input_select_cover_mode/0 and set_input_select_cover_mode/1.

`:alarm_control_panel`

Requires platform and code.

Optional attributes: arming_states (list of alarm states that require the code to arm), arming_time, delay_time, trigger_time (seconds, applied to every arm mode unless overridden), and per-mode overrides armed_home, armed_away, armed_night, armed_vacation, armed_custom_bypass — each written as a keyword list, e.g. armed_home delay_time: 10 (a literal %{delay_time: 10} map also works; both end up normalized to a map before being written to YAML).

entity :alarm_control_panel, "alarm" do
  platform :manual
  code "1234"
end

With every optional attribute set:

entity :alarm_control_panel, "alarm" do
  platform :manual
  code "1234"
  arming_states [:armed_home, :armed_away]
  arming_time 30
  delay_time 20
  trigger_time 120
  armed_home delay_time: 10
  armed_away delay_time: 30
  armed_night delay_time: 10
  armed_vacation delay_time: 30
  armed_custom_bypass delay_time: 10
end

Injects get_alarm_control_panel_alarm/0 and set_alarm_control_panel_alarm_state/2.

Automations

automation "alias" do
  trigger do
    ...
  end

  condition do
    ...
  end

  action do
    ...
  end
end

condition is optional. trigger and action each accept one or more of the forms below.

Triggers

`state`

Allowed keys: affected_entities (required), to, from.

state do
  affected_entities [{:input_boolean, "presence"}]
  to true
end

`numeric_state`

Allowed keys: affected_entities (required), above, below.

numeric_state do
  affected_entities [{:input_number, "temperature_limit"}]
  above 20
end

`sun`

Allowed keys: event (required).

sun do
  event :sunrise
end

`time`

Allowed keys: at (required), weekday.

time do
  at "22:00:00"
end

Conditions

`state_condition`

Allowed keys: affected_entities (required), state_value (required).

state_condition do
  affected_entities [{:alarm_control_panel, "alarm"}]
  state_value "armed_home"
end

`numeric_state_condition`

Allowed keys: affected_entities (required), above, below.

numeric_state_condition do
  affected_entities [{:input_number, "temperature_limit"}]
  above 20
end

`logical_condition`

Combines nested conditions with :and or :or instead of the default :and.

logical_condition :or do
  state_condition do
    affected_entities [{:alarm_control_panel, "alarm"}]
    state_value "armed_home"
  end

  state_condition do
    affected_entities [{:alarm_control_panel, "alarm"}]
    state_value "armed_away"
  end
end

Actions

`service`

Generic Home Assistant service call.

Allowed keys: affected_entities (required). For domain: :input_select, also requires option (or options).

service :input_boolean, "turn_on" do
  affected_entities [{:input_boolean, "presence"}]
end

service :input_select, "select_option" do
  affected_entities [{:input_select, "cover_mode"}]
  option "open"
end

`persistent_notification`

Shows a notification in the Home Assistant UI.

Allowed keys: message (required), title.

persistent_notification "create" do
  message "Hello from HomeElixir"
end

Introspection helpers

Every module using HomeElixir.DSL also gets:

__home_elixir_entities__/0 — the entities declared in that module.
__home_elixir_automations__/0 — the automations declared in that module.
restart_home_assistant/0 — calls the Home Assistant restart service.

← Previous Page Home Assistant Elixir