StandbyControl Plugin

Contents

Introduction

StandbyControl provides several EventGhost actions and events in order to build a sophisticated standby control environment, primarily intended for media center computers.

StandbyControl's functionality can be grouped as follows:
  1. Timer
  2. Standby blocking counters
  3. Monitored processes
  4. Keep Alive schedule
  5. OSD Countdown

1. Timer

StandbyControl runs an internal timer which is started when the plugin starts. At the end of it's configured time, let's say after 10 minutes, the timer fires an event "StandbyControl.Trigger". This event is intended to run an action like "Stand By" or "Hibernate computer" or even "Turn off Computer". So in a first step you could create a macro on event "StandbyControl.Trigger" with the action "Stand By" or "Hibernate". All right? That's already the magic of StandbyControl - almost ;)

Are we happy now? No! Because the media center shuts down every 10 minutes after start. That's unusable. We want to add conditions. We want to say, "Yes, shut down the machine, but not while ..." - and that's the rest of the magic of StandbyControl plugin. It provides a set of conditions and helpers to decide when to shut down the machine and when not.

2. Standby blocking counters

Let's assume you have a media player like DVBViewer. The plugin for this application fires events on every state change of the application. For example, we get events "DVBViewer.Play" when playback starts and "DVBViewer.Stop" when playback stops. While DVBViewer is playing, we want to inhibit standby, but when DVBViewer playback stops, we'd like to suspend the machine after a while. Two actions, "Enable Standby" and "Inhibit Standby", are intended for this purpose. Just create two macros: on event "DVBViewer.Play" run the action "Inhibit Standby" and on event "DVBViewer.Stop" run action "Enable Standby". The rest will be done by StandbyControl.

Another source of such events is the system itself. If we don't move the mouse nor use the keyboard for a while, the event "System.Idle" is fired. If the mouse is moved again, "System.Unidle" is fired. So just pack the "System.Idle" event together with the "Inhibit Standby" action into a new macro and "System.Unidle" together with "Enable Standby" into another one. Now your first running version of a standby control environment (along with the first macro mentioned in the previous section) is ready!

3. Monitored processes

Unfortunately, only few applications fire events on state changes as we saw that with DVBViewer before. Let's take a wide-spread music player like WinAmp, and we don't get events when the player starts or stops. StandbyControl can help again. In the plugin configuration, you can define a list of "Monitored processes". Just add winamp.exe to this list. As soon as WinAmp gets started, an event 'StandbyControl.Create.winamp' is fired and when it gets terminated, event 'StandbyControl.Terminate.winamp' is fired. These events can be used to set and control a Standby Blocking Counter as described above. Alternatively, in the macro that contains the "Stand By Computer" action, call first the action "IsMonitoredProcessRunning". The result of that action (provided in eg.result) tells if at least one program as defined before is currently running, allowing you to implement further logic based on it.

4. Keep Alive Schedule

Some people like to have fixed times when the media center shall be available, i.e. up and running. The Keep Alive Schedule is intended for this purpose and can be configured in the plugin configuration as well. Let's say you want to avoid standby every Saturday evening from 6pm till 11pm. First of all, define such an entry in the plugin configuration. On Saturday evening at 6pm, the event 'StandbyControl.KeepAlivePeriodStarted' is fired and at 11pm, the event 'StandbyControl.KeepAlivePeriodEnded' is fired. Again, these events can be used to set and control Standby Blocking Counters. Alternatively, in the macro that contains the "Stand By Computer" action, call first the action "IsKeepAlive". It will return "True" on Saturday evenings and "False" otherwise. You can define and combine as many schedule entries as you need.

5. OSD Countdown / Cancel OSD

As friendly people, we want to notify the user before executing Stand By and give him the choice to cancel. The actions "OSD Countdown" and "Cancel OSD" are intended for this purpose. They are similar to the "ShowOSD" action provided by EG itself, but with some useful extensions: As the name says, "OSD Countdown" implements a countdown, i.e. it can be configured how long the message shall be displayed. The current timer value can be part of the message, like "Your media center will explode in 5,4,3,2,1 secs.". At the end of the countdown, a configurable event is triggered. Your macro can catch that event and do the next actions. Another notable difference to EG's "Show OSD" action is the fact that "OSD Countdown" doesn't block the execution of further macros, it runs asynchronously.

Finally, there's a "Cancel OSD" action. You could extend the message from before with "Press ESC to cancel" and while your countdown is being displayed, you might have a macro listening on the ESC key (or any other) and the action immediately stops the current OSD Countdown, preventing the media center from exploding ;-)

Function overview

The plugin and its actions have many and some powerful options - but some of them are not self-explaining, therefore some more details here. However, only the important and hard to understand ones are documented.

Plugin Configuration

Group Name Type Description
Standby trigger times Standby default time [s] Field Time in seconds after "StandbyControl.Trigger" event will be fired
Next trigger / force release in Label Informs when the next trigger events are scheduled.Two values <A> / <B> are displayed.
<A> displays the time when the next trigger will be fired or "Pending", if Standby blocking counters are active. The value "None" indicates that the timer has not been started yet.
<B> is the time until the next force release or "None" if none of the current  blocking counters has a release time set.
Standby default time if standby was pending [s] Field Complicated, don't read further. Still reading? Ok, ok, I'll try to explain...
This timeout applies after "Pending" state.
If the standby trigger was "Pending", i.e. if a Standby blocking counter was active (see "Inhibit Standby" action) and then released (see "Enable Standby" action) or the force release time is reached, then the next trigger event is scheduled with this "default pending time".
The action "Enable Standby" makes also use of it when option "Trigger standby timer with default pending time" is chosen.
Standby time after system resume Field Same as "Standby default time" but applies to the initial state after a system resume. 
Standby blocking counters Blocking counter name Column The name of the Standby blocking counter as defined in "Inhibit / Enable Standby"
Counter value Column The current counter value, i.e. how many times "Inhibit Standby" has been called. A value bigger than zero means that the blocker is active. Trigger events will only be fired if all counters are zero. "Inhibit Standby" action increases the counter while "Enable Standby" action decreases the value again.
Reset after resume Column If the counter shall be reset to zero after system resume
Release time Column Time when a force release will happen as defined in "Inhibit standby" action.
Clear / Clear all Button Resets the counter value and the release time for one or all entries in the table. Thought as an emergency exit and for testing. Same effect as if one calls "Enable Standby" action on the blocking counter.
Monitored processes Process name Column Name of the application (program executable) to monitor.
Hint: To add a new application, launch that application first, then press "Refresh" and you'll find the process in the dropdown list. Select it and press "Add".
Process status Column Indicates if the monitored process is currently running or not.
Note: The entries don't block standby by themselves. But your macro, deciding to shut down or not, can query the current status by calling the action "IsMonitoredProcessRunning". Alternatively, the events 'StandbyControl.Created.*' and 'StandbyControl.AllMonitoredProcessesTerminated' can be catched and used to control a Standby blocking counter.
Keep Alive Schedule Keep Alive Schedule Table This table defines time periods when the system shall remain running.
Note: The entries don't block standby by themselves. But your macro, deciding to shut down or not, can query the current status by calling the action "IsKeepAlive". Alternatively, the events 'StandbyControl.KeepAlivePeriodStarted' and 'StandbyControl.AllKeepAlivePeriodsEnded' can be catched and used to control a Standby blocking counter.

Action: Inhibit Standby

Increments the counter for a standby blocking application. Optionally, the number of inhibits can be counted.
Name Type Description
Blocking counter name Field The name of the Standby blocking counter. This might be an application name, for example.
Set release time [min] Option + Field If checked, the Standby blocking counter is force released after the specified time (in minutes) and the counter set to 0.
After a blocking counter has been force released, the next Trigger event is scheduled with the 'Default pending time' as configured in the plugin configuration.
Increment counter Option If checked, the counter is incremented as many times as "Inhibit Standby" is called (and decremented again as many times as "Enable Standby" is called).
If unchecked, the counter will only reach value 1 or 0, regardless how often "Inhibit Standby" has been called on it.
Reset counter after resume Option If checked, the counter is set to 0 after system resume.
If unchecked, the counter value after resume remains the same before suspend.
Trigger standby timer Option Leave default: "Don't trigger". Other options rarely used.

Action: Enable Standby

Decrements or resets the counter for a standby blocking application.
Name Type Description
Blocking counter name Field The name of the Standby blocking counter. This might be an application name, for example.
Reset the counter (otherwise decrement) Option If checked, the counter is set to 0 when "Enable Standby" is called, regardless of the current counter value.
If unchecked, the counter is decremented by 1 on each call of "Enable Standby".
Trigger standby timer
if counter is equal to zero		 Radio Group After all blocking counters have reached value 0, the next Trigger event can be scheduled with the following options:
- "Don't trigger": The time until next trigger event is continued from previous state before Pending state.
- "With default pending time": Next trigger event is scheduled with default pending time (as configured in the plugin configuration)
- "With default standby time": Next trigger event is scheduled with "standby default time" (as configured in the plugin configuration)
- "With following value": Specifies a special value for next
Trigger standby timer
if counter is unequal to zero		 Radio Group Leave default: "Don't trigger". Other options rarely used.

Action: Trigger Standby Timer

This action can be used to reprogram the internal timer and therefore the time when the next "StandbyControl.Trigger" shall happen. A "StandbyControl.Trigger" event is fired after the specified amount of time and in case that standby is not inhibited by a standby blocker.

Name Type Description
Force standby time Option If checked, the time until the next trigger can be decreased. Otherwise, it can only be increased.

Action: Was triggered

Returns 'True' in 'eg.result' if a trigger event has been fired before

Action: OSD Count Down

On screen display of a message, optionally with a decreasing countdown value. The execution of the OSD countdown runs asynchronously, i.e. it does not block further macro executions. It fires a configurable Event at the end of the countdown.

Field "Text to display" not only accepts normal (static) text phrases, but it also accepts Python expressions. This might be used for implementing multilingual support or anything else, where the final message is only known at runtime. The expression syntax is: ${<python expression>} while <python expression> stands for a valid Python expression which is evaluated at runtime.
Examples:
${eg.globals.myMessage} displays the value from eg.globals.myMessage (assuming that this variable is defined and has some text assigned).
${eg.globals.myClass.getMessage()} would execute the method/function eg.globals.myClass.getMessage() and display its return value (assuming again that this class and method really exists and returns a String value).

Action: Cancel OSD Count Down

Cancels a running OSD countdown.

Action: Is Monitored Process Running

Returns 'True' in 'eg.result' if a monitored process, as defined in the plugin configuration, is currently running.

Action: Is Keep Alive

Returns 'True' in 'eg.result' if a scheduled keep alive entry is active at this time.


2012-03-11 / StandbyControl %s / db