Skip to content

Latest commit

 

History

History
250 lines (185 loc) · 7.84 KB

README.md

File metadata and controls

250 lines (185 loc) · 7.84 KB
Raw

Momentary devices for Home Asistant

Momentary is a component that provides momentary switches for Home Assistant. That is, it provides a simple switch that once turned on will turn itself off.

icon

!!!BREAKING CHANGES!!!

Version 0.7 supports adding momentary devices using config flow. By default it will move your existing devices into a single file momentary.yaml. If you DO NOT want this behaviour add this to your momentary configuration.

momentary:
  yaml_config: True

Introduction

Notes

Wherever you see /config in this README it refers to your home-assistant configuration directory. For me, for example, it's /home/steve/ha that is mapped to /config inside my docker container.

Version 0.6 Documentation

This documentation is for the 0.7x version, you can find the 0.6.x version here.

Thanks

Many thanks to:

  • JetBrains for the excellent PyCharm IDE and providing me with an open source license to speed up the project development.

    JetBrains

  • Icon adapted from svg icons and is licensed by CC BY 4.0

Installation

HACS

hacs_badge

Momentary is part of the default HACS store. If you're not interested in development branches this is the easiest way to install.

Manually

Copy the momentary directory into your /config/custom_components directory.

From Script

Run the install script. Run it once to make sure the operations look sane and run it a second time with the go parameter to do the actual work. If you update just rerun the script, it will overwrite all installed files.

install /config
# check output looks good
install go /config

Component Configuration

  • yaml_config; set to True to enable backwards compatability, set to False to disable it. The default is False.

For example, this enable backwards compatability.

virtual:
  yaml_config: True

Entity Configuration

Add the component using the standard Home Assistant Integration method.

Because this component creates fake entries and because I'm still figuring out the Config Flow interface you still have to configure it by file.

The default file is named /config/momentary.yaml and is a similar format to the standard Home Assistant configuration files. This file will be created during an upgrade or when you add in a Momentary integration. An empty file looks like this:

version: 1
switches:

To create a single momentary device add the following:

version: 1
switches:
- name: Empty House Trigger

To create a single momentary device with custom options use:

version: 1
switches:
- name: Empty House Trigger
  mode: "on"
  toggle_for: 5
  cancellable: True

To create multiple momentary device add more devices at the bottom:

version: 1
switches:
- name: Empty House Trigger
  mode: "on"
  toggle_for: 5
  cancellable: True
- name: Full House Trigger
- name: Overflowing House Trigger
  toggle_for: 2

You can group switches together under an umbrella device. To do this use a device name instead of name: as the first line of the switch entry. This config create a device with 3 entities:

version: 1
switches:
- House Alarm:
  - name: House to Armed Trigger
    toggle_for: 1
  - name: House to Disarmed Trigger
    toggle_for: 1
  - name: House to Home Trigger
    toggle_for: 1

Once you've updated the file you will need to reload the component from its integration setting.

The integration uses the name to distinguish different switches. If you update the name of a switch the old name will be deleted and the new name created on reload.

The integration supports multiple installs, you can use this group similar momentary devices together.

Options

The following additional parameters can be specified against the switches:

Field Type Default Description
name strings Name of the switch. Has to be supplied.
mode string "on" Is the switch a momentary ON or OFF switch. Use "on" for on and "off" for off.
toggle_for seconds 1 Amount of time to turn toggle switch for.
cancellable Boolean False Allow switched to be untoggled manually.

Upgrade Notes

After the Upgrade

Check the devices and entities on the Integrations page, if everything looks good then you can comment out the old configuration. Don't delete it yet, this is alpha and I might change some settings...

Names

The qualifier applied to the name has changed. The old qualify of ! has been removed, not adding momentary to the device/entity name is the default. A new qualify of + has been created, adding this tells the integration to add momentary to the device/entity name.

The upgrade code will change this for you.

Old Name New Name Entity Name
Empty House Trigger +Empty House Trigger switch.momentary_empty_house_trigger
!Empty House Trigger Empty House Trigger switch.empty_house_trigger

unique_id

During an upgrade the original name based unique id will be created. For a new install a UUID based unique id will be created.

If you want to move to the new UUID based unique IDs you can manage this with the following:

  • Delete the imported Momentary integration.
  • Re-add the imported Momentary integration. You can use the default values for group and file name.

The system will re-create your devices with the correct entity ids but with new UUID based unique ids.

I will look at how this can be made cleaner... maybe a config flow button or as part of the upgrade.

Known Issues

You will see errors like this on upgrade. They don't seem to cause an issue and they disappear once you remove the legacy configuration.

2023-10-13 17:28:09.154 ERROR (MainThread) [homeassistant.components.switch] The momentary platform for the switch integration does not support platform setup. Please remove it from your config.

Turning on Debug

If you do run into issues you can enable debug with the following configration.

logger:
  default: info
  logs:
    custom_components.momentary: debug

If you can create a bug report with this debug output it would help me track down the problem.