alarm

alarm#

Description#

Alarm/timer plugin.

It requires at least one enabled media plugin to be configured if you want to play audio resources.

Example configuration:

alarm:
    # Media plugin that will be used to play the alarm audio.
    # If not specified, the first available configured media plugin
    # will be used.
    media_plugin: media.vlc

    alarms:
        morning_alarm:
            # Cron expression format: run every weekday at 7 AM
            when: '0 7 * * 1-5'
            media: ~/path/your_ringtone.mp3
            audio_volume: 10       # 10%

            # Repeat the played media resource until the alarm is
            # snoozed/dismissed (default: true)
            media_repeat: true

            # Wait 5 minutes between a snooze and another run
            snooze_interval: 300

            # After 10 minutes with no manual snooze/dismiss,
            # stop the alarm
            dismiss_interval: 600

            # Actions to be executed when the alarm goes on
            actions:
                - action: tts.say
                  args:
                      text: Good morning

                - action: light.hue.bri
                  args:
                      value: 1

                - action: light.hue.bri
                  args:
                      value: 140
                      transitiontime: 150

        one_shot_alarm:
            # One-shot execution, with timestamp in ISO format
            when: '2020-02-18T07:00:00.000000'
            media: ~/path/your_ringtone.mp3
            actions:
                - action: light.hue.on

        timer:
            # This alarm will execute the specified number of seconds
            # after being initialized (5 minutes after the plugin has
            # been initialized in this case)
            when: 300
            media: ~/path/your_ringtone.mp3
            actions:
                - action: light.hue.on

Configuration#

alarm:
  # [Optional]
  # List or name->value dict with the configured alarms.
  # alarms:   # type=Union[List[dict], Dict[str, dict], NoneType]

  # [Optional]
  # Media plugin (instance of
  # `MediaPlugin <https://docs.platypush.tech/platypush/plugins/media.html#platypush.plugins.media.MediaPlugin>`_) that will be used to
  # play the alarm audio. It needs to be a supported local media
  # plugin, e.g. ``media.mplayer``, ``media.vlc``, ``media.mpv``,
  # ``media.gstreamer``, ``sound``, etc. If not specified, the first
  # available configured local media plugin will be used. This only
  # applies to alarms that are configured to play an audio resource.
  # media_plugin:   # type=Optional[str]

  # [Optional]
  # (Internal) poll interval, in seconds (default: 2).
  # poll_interval: 2.0  # type=Optional[float]

  # [Optional]
  # Default snooze interval in seconds. This
  # specifies how long to wait between alarm runs when an alarm is
  # dismissed (default: 300).
  # snooze_interval: 300.0  # type=float

  # [Optional]
  # Default dismiss interval in seconds. This
  # specifies how long an alarm should run without being manually
  # snoozed/dismissed before being automatically dismissed (default:
  # 300).
  # dismiss_interval: 300.0  # type=float

  # [Optional]
  # How long we should wait for any running
  # threads/processes to stop before exiting (default: 5 seconds).
  # stop_timeout: 5  # type=Optional[float]

  # [Optional]
  # If set to True then the plugin will not monitor
  # for new events. This is useful if you want to run a plugin in
  # stateless mode and only leverage its actions, without triggering any
  # events. Defaults to False.
  # disable_monitor: False  # type=bool

Triggered events#

Actions#

Module reference#

class platypush.plugins.alarm.AlarmPlugin(*_, **__)[source]#

Bases: RunnablePlugin, EntityManager

Alarm/timer plugin.

It requires at least one enabled media plugin to be configured if you want to play audio resources.

Example configuration:

alarm:
    # Media plugin that will be used to play the alarm audio.
    # If not specified, the first available configured media plugin
    # will be used.
    media_plugin: media.vlc

    alarms:
        morning_alarm:
            # Cron expression format: run every weekday at 7 AM
            when: '0 7 * * 1-5'
            media: ~/path/your_ringtone.mp3
            audio_volume: 10       # 10%

            # Repeat the played media resource until the alarm is
            # snoozed/dismissed (default: true)
            media_repeat: true

            # Wait 5 minutes between a snooze and another run
            snooze_interval: 300

            # After 10 minutes with no manual snooze/dismiss,
            # stop the alarm
            dismiss_interval: 600

            # Actions to be executed when the alarm goes on
            actions:
                - action: tts.say
                  args:
                      text: Good morning

                - action: light.hue.bri
                  args:
                      value: 1

                - action: light.hue.bri
                  args:
                      value: 140
                      transitiontime: 150

        one_shot_alarm:
            # One-shot execution, with timestamp in ISO format
            when: '2020-02-18T07:00:00.000000'
            media: ~/path/your_ringtone.mp3
            actions:
                - action: light.hue.on

        timer:
            # This alarm will execute the specified number of seconds
            # after being initialized (5 minutes after the plugin has
            # been initialized in this case)
            when: 300
            media: ~/path/your_ringtone.mp3
            actions:
                - action: light.hue.on
__init__(alarms: List[dict] | Dict[str, dict] | None = None, media_plugin: str | None = None, poll_interval: float | None = 2.0, snooze_interval: float = 300.0, dismiss_interval: float = 300.0, **kwargs)[source]#
Parameters:

  • alarms – List or name->value dict with the configured alarms.

  • media_plugin – Media plugin (instance of platypush.plugins.media.MediaPlugin) that will be used to play the alarm audio. It needs to be a supported local media plugin, e.g. media.mplayer, media.vlc, media.mpv, media.gstreamer, sound, etc. If not specified, the first available configured local media plugin will be used. This only applies to alarms that are configured to play an audio resource.

  • poll_interval – (Internal) poll interval, in seconds (default: 2).

  • snooze_interval – Default snooze interval in seconds. This specifies how long to wait between alarm runs when an alarm is dismissed (default: 300).

  • dismiss_interval – Default dismiss interval in seconds. This specifies how long an alarm should run without being manually snoozed/dismissed before being automatically dismissed (default: 300).

add(when: str | int | float, actions: list | None = None, name: str | None = None, media: str | None = None, media_plugin: str | None = None, media_repeat: bool = True, audio_file: str | None = None, audio_volume: float | int | None = None, enabled: bool = True, snooze_interval: float | None = None, dismiss_interval: float | None = None) → dict[source]#

Add a new alarm.

Parameters:

  • when – When the alarm should be executed. It can be either a cron expression (for recurrent alarms), or a datetime string in ISO format (for one-shot alarms/timers), or an integer/float representing the number of seconds before the alarm goes on (e.g. 300 for 5 minutes).

  • actions – List of actions to be executed.

  • name – Alarm name.

  • media – Path of the audio file to be played.

  • media_plugin – Override the default media plugin for this alarm.

  • media_repeat – Repeat the played media resource until the alarm is snoozed/dismissed (default: True).

  • audio_volume – Volume of the audio.

  • enabled – Whether the new alarm should be enabled (default: True).

  • snooze_interval – Snooze seconds before playing the alarm again.

  • dismiss_interval – Dismiss seconds before stopping the alarm.

Returns:

The newly created alarm.

delete(name: str)[source]#

Delete an alarm.

Parameters:

name – Alarm name.

disable(name: str)[source]#

Disable an alarm. This will prevent the alarm from executing until re-enabled or until the application is restarted.

Parameters:

name – Alarm name.

dismiss()[source]#

Dismiss the alarm that is currently running.

edit(name: str, new_name: str | None = None, when: int | float | str | None = None, actions: list | None = None, media: str | None = None, media_plugin: str | None = None, media_repeat: bool | None = None, audio_volume: float | int | None = None, enabled: bool | None = None, snooze_interval: float | None = None, dismiss_interval: float | None = None) → dict[source]#

Edit an existing alarm.

Note that you can only edit the alarms that are not statically defined through the configuration.

Parameters:

  • name – Alarm name.

  • new_name – New alarm name.

  • when – When the alarm should be executed. It can be either a cron expression (for recurrent alarms), or a datetime string in ISO format (for one-shot alarms/timers), or an integer/float representing the number of seconds before the alarm goes on (e.g. 300 for 5 minutes).

  • actions – List of actions to be executed.

  • media – Path of the audio file to be played.

  • media_plugin – Override the default media plugin for this alarm.

  • media_repeat – Repeat the played media resource until the alarm is snoozed/dismissed (default: True).

  • audio_volume – Volume of the audio.

  • enabled – Whether the new alarm should be enabled.

  • snooze_interval – Snooze seconds before playing the alarm again.

  • dismiss_interval – Dismiss seconds before stopping the alarm.

Returns:

The modified alarm.

enable(name: str)[source]#

Enable an alarm.

Parameters:

name – Alarm name.

get_alarms() → List[Dict[str, Any]][source]#

Deprecated alias for status().

main()[source]#

Implementation of the main loop of the plugin.

publish_entities(entities: Collection[Any] | None, callback: Callable[[Entity], Any] | None = None, **kwargs) → Collection[Entity]#

Publishes a list of entities. The downstream consumers include:

It also accepts an optional callback that will be called when each of the entities in the set is flushed to the database.

You usually don’t need to override this class (but you may want to extend transform_entities() instead if your extension doesn’t natively handle Entity objects).

set_enabled(name: str, enabled: bool)[source]#

Enable/disable an alarm.

Parameters:

  • name – Alarm name.

  • enabled – Whether the alarm should be enabled.

snooze(interval: float | None = None)[source]#

Snooze the alarm that is currently running for the specified number of seconds. The alarm will stop and resume again later.

Parameters:

interval – Snooze seconds before playing the alarm again (default: 300).

start()#

Start the plugin.

status(*_, **__) → List[Dict[str, Any]][source]#

Get the list of configured alarms and their status.

Returns:

List of the alarms, sorted by next scheduled run. Example:

[
    {
        "name": "Morning alarm",
        "id": 1,
        "when": "0 8 * * 1-5",
        "next_run": "2023-12-06T08:00:00.000000",
        "enabled": true,
        "media": "/path/to/media.mp3",
        "media_plugin": "media.vlc",
        "media_repeat": true,
        "audio_volume": 10,
        "snooze_interval": 300,
        "dismiss_interval": 300,
        "actions": [
            {
                "action": "tts.say",
                "args": {
                    "text": "Good morning"
                }
            },
            {
                "action": "light.hue.on"
            }
        ],
        "state": "RUNNING"
    }
]

stop()[source]#

Stop the plugin.

transform_entities(entities: Collection[Alarm], **_) → List[Alarm][source]#

This method takes a list of entities in any (plugin-specific) format and converts them into a standardized collection of Entity objects. Since this method is called by publish_entities() before entity updates are published, you may usually want to extend it to pre-process the entities managed by your extension into the standard format before they are stored and published to all the consumers.

wait_stop(timeout=None)#

Wait until a stop event is received.