diff --git a/README.md b/README.md new file mode 100644 index 0000000..b27d58b --- /dev/null +++ b/README.md @@ -0,0 +1,159 @@ +# Power Event Provider + +Power Event Provider is a Windows service which posts power events such as power scheme changes, battery status changes, display state changes, etc. into the Windows event log. +Besides for monitoring purposes, these events can also be used as triggers for the Windows task scheduler. This makes it possible to run any application or script when a power event occurs. + +## Available events + +Power Event Provider supports 5 groups of events. Not all events are supported on each and every system. + +### Power schemes + +Event | ID +-------------------------------------------------------|--------- +Power scheme personality changed: **Power saver** | 1000 +Power scheme personality changed: **Automatic** | 1001 +Power scheme personality changed: **High performance** | 1002 + +### Power line status + +Event | ID +-------------------------------------------------------|--------- +Power line status changed: **AC power source** | 2000 +Power line status changed: **Battery** | 2001 +Power line status changed: **UPS power source** | 2002 +Power line status changed: **Out of range** | 2003 + +### Notebook lid state + +Event | ID +-------------------------------------------------------|--------- +Notebook lid state changed: **Closed** | 3000 +Notebook lid state changed: **Open** | 3001 + +### Battery percentage + +Event | ID +-------------------------------------------------------|--------- +Remaining battery percentage changed: **1%** | 4*001* +Remaining battery percentage changed: **2%** | 4*002* +...|... +Remaining battery percentage changed: **99%** | 4*099* +Remaining battery percentage changed: **100%** | 4*100* + +:bulb: Battery percentage events are disabled by default to avoid spamming the event log. + +### Display state + +Event | ID +-------------------------------------------------------|--------- +Display state changed: **Off** | 5000 +Display state changed: **On** | 5001 +Display state changed: **Dimmed** | 5002 + +## Download + +You can download the PowerEventProvider setup from github: [link (github)](https://github.com/hirschmann/powereventprovider/releases) + +## Configuration + +You can enable/disable monitoring of event groups by editing the *PowerEventProvider.exe.config* file in the PowerEventProvider installation directory. +Just set event groups which should show in the event log to **True**. + +After changing the config file, the *PowerEventProvider* service must be restarted (e.g. via Windows task manager or *services.msc*) in order for the changes to take effect. + +The default configuration looks like this: + +```xml + + + + +
+ + + + + + + + + False + + + True + + + True + + + True + + + True + + + + +``` + +## Viewing power events in the event log + +### Powershell + +You can list all PowerEventProvider event log entries by entering the following line in powershell: + +```powershell +get-eventlog -logname Application -source PowerEventProvider +``` + +### Event Viewer + +If you prefer GUI over command line, you can create a custom view for PowerEventProvider related events in the Windows Event Viewer. + +Open the Windows event log (*eventvwr.msc*) and create a custom view: + +![Create a custom view](images/event-viewer-create-view.png) + +Select a log (*Application*) and a source (*PowerEventProvider*) to view: + +![Select a log](images/event-viewer-select-source.png) + +Open your custom view: + +![Open the custom view](images/event-viewer.png) + +## Using events as scheduled task triggers + +Since PowerEventProvider was created as a companion application for [NoteBook FanControl (NBFC)](https://github.com/hirschmann/nbfc), this example shows how to switch NBFC profiles when a notebook's power source changes. + +Open the Windows task scheduler (*taskschd.msc*): + +![Create a task](images/task-create.png) + +Give the task a name and select the user account which should be used to run the task: + +![Task - general settings](images/task-general.png) + +Create a new trigger and select "Begin the task: On an event". Then select a log (*Application*) and a event source (*PowerEventProvider*). +To run the task as soon as the notebook's power source switches to "battery", set the *Event ID* to *2001*: + +![Task - trigger](images/task-trigger.png) + +Create a new action and select "Start a program". Then put in the path to the NBFC command line interface as program to run: `"C:\Program Files (x86)\NoteBook FanControl\nbfc.exe"` + +Finally, set `config --apply ""` as arguments. In this case I wanted the fan to be more silent when the notebook is not in it's docking station, so the argument was `config --apply "HP ProBook 6465b silent"`. + +![Task - action](images/task-action.png) + +At last - in this case - it's important to untick all conditions, because the task should run immediately when the power source changes without any delays. + +![Task - action](images/task-conditions.png) + +The task settings can be left at default values: + +![Task - action](images/task-settings.png) + +After completing these steps, you can test if everything is working properly by unplugging your notebook. NBFC should switch to the profile you have defined in the task. + +To make NBFC switch back to the default profile when you plug in your notebook, just create a second task which is triggered by event ID 2000 (instead of 2001) and sets the default configuration for your notebook (in my case: `config --apply "HP ProBook 6465b"`). diff --git a/images/event-viewer-create-view.png b/images/event-viewer-create-view.png new file mode 100644 index 0000000..b70cb29 Binary files /dev/null and b/images/event-viewer-create-view.png differ diff --git a/images/event-viewer-select-source.png b/images/event-viewer-select-source.png new file mode 100644 index 0000000..d2c03e0 Binary files /dev/null and b/images/event-viewer-select-source.png differ diff --git a/images/event-viewer.png b/images/event-viewer.png new file mode 100644 index 0000000..2156232 Binary files /dev/null and b/images/event-viewer.png differ diff --git a/images/task-action.png b/images/task-action.png new file mode 100644 index 0000000..f103c52 Binary files /dev/null and b/images/task-action.png differ diff --git a/images/task-conditions.png b/images/task-conditions.png new file mode 100644 index 0000000..08ea03d Binary files /dev/null and b/images/task-conditions.png differ diff --git a/images/task-create.png b/images/task-create.png new file mode 100644 index 0000000..e09879a Binary files /dev/null and b/images/task-create.png differ diff --git a/images/task-general.png b/images/task-general.png new file mode 100644 index 0000000..c2d69ff Binary files /dev/null and b/images/task-general.png differ diff --git a/images/task-settings.png b/images/task-settings.png new file mode 100644 index 0000000..565f56b Binary files /dev/null and b/images/task-settings.png differ diff --git a/images/task-trigger.png b/images/task-trigger.png new file mode 100644 index 0000000..afb5e49 Binary files /dev/null and b/images/task-trigger.png differ